Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, non-mutating operation. The description adds that it 'never runs raw database or SQL queries' and that it produces a 'safe' plan—useful context reinforcing the read-only nature and output type. However, it doesn't describe what happens on missing context (does it return a list of required fields? does it fail?). Annotations cover the safety profile well, so the description adds moderate value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences: the first states purpose and usage, the second states a key limitation. It is front-loaded with the main purpose and immediately instructs the agent on next steps. No wasted words; every phrase carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a planner used before other calls; its behavior is inherently simple (take a question, output a plan). With an output schema present (not shown in this prompt but implied by 'Has output schema: true'), the agent likely sees the plan structure elsewhere. The description covers safety, purpose, usage, and key limitations. It might benefit from stating what 'missing context' looks like in the output, but given the output schema and annotations, what's here is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; every parameter, including all five optional ones, has a brief description. The description of the 'query' parameter ('The user's own natural-language question or requested outcome') adds meaning beyond just a generic 'text' field, clarifying that it's the raw user input. The optional parameters are clearly contextual hints. Given high schema coverage, the description's parameter handling is adequate and not redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Craft'), a resource ('Postly query'), and an outcome: converting a free-form user question into a plan of existing MCP tools, while identifying missing context. It clearly distinguishes itself from the sibling tools (which are all direct operations), and states what it does NOT do—run raw database or SQL queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this first for free-form requests; then call the planned tools.' This gives clear when-to-use guidance. It doesn't explicitly say when NOT to use it (e.g., when a direct tool call is already obvious), but the instruction to use it first for free-form requests, plus its role as a planner, provides strong context for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.