forge-mcp-tool-design

Design MCP tools with strict verb_object naming, LLM-consumable third-person descriptions, and sibling-tool guidance so the model can reliably infer usage and construct arguments. Enforce disciplined JSON Schema with descriptions on every property to resolve tool-selection ambiguity and schema-mismatch failures.

JSON Schema hygiene for LLM function calling requires descriptions on every parameter, enums for closed sets, additionalProperties: false on object types, and explicit ISO 8601 format declarations. This strict schema discipline prevents models from generating invalid or unparseable arguments.

MCP tools should return structured error objects containing code, message, and retryable fields. This standardized error contract allows LLM agents to determine whether to retry the function call or select an alternate path, ensuring recoverable workflows.

LLMs fail tool selection due to ambiguous naming, missing descriptions, and unclear sibling-tool guidance. Enforcing LLM-first tool contracts with verb_object naming and third-person descriptions helps models infer exactly when to call a specific tool.

Add dry_run support to mutation and deletion MCP tool patterns to reduce high-risk behavior. This safety mechanism allows LLM agents to validate operations before executing irreversible destructive actions.

These tool design patterns apply to any LLM agent that uses function calling and must reliably infer usage, construct arguments, and parse responses. The schema discipline and error contracts are platform-agnostic for all LLM function-calling workflows.