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

Beyond the readOnlyHint=true and idempotentHint=true annotations, the description discloses crucial behavioral traits: literal category matching only, free text not parsing, the generic fallback response with matched_category=null and context_understood=false, and the additional fields returned on non-matching context (is_generic_answer, answer_note, next_tools). It also fully enumerates the response fields, telling the agent exactly what to expect without needing to infer from the output schema.

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 dense but every sentence carries meaningful guidance. It front-loads the core purpose and best usage, then provides exclusions. The main paragraph is long, but the density is justified given the tool's behavioral quirks and the need to prevent misuse. A slight structural improvement would be bullet formatting for the response fields, but the inline enumeration is acceptable for an AI-facing tool definition.

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?

For a single-parameter tool with a live output schema, the description is exceptionally complete. It covers the exact accepted values, error/fallback behavior, full return shape, and routes to correct sibling alternatives. The output schema already exists, so the description needn't redundantly document return types. The only niche gap might be explaining when top_pocket is stale, but recommendation_live field partially covers that. Nothing essential is missing 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?

The input schema already provides 100% coverage with a rich parameter description and example. The tool description adds critical semantic detail beyond the schema: it explicitly warns that context must match one of four literal categories, that free text does not parse, and it enumerates the exact allowed values. This prevents the agent from passing free text despite the schema's example looking like free text. Slight redundancy with the schema example, hence 4 rather than 5.

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 begins with a specific verb ('Use for') and identifies the exact resource: a ready-to-quote DESCRIPTION of DC Hub in one of four named categories, plus the live top-ranked market pocket. It explicitly states what it does NOT do ('It does NOT compute a siting answer from free text'), which sharply distinguishes it from analysis tools. The clear contrast with sibling tools like site_selection_canvas and rank_markets leaves no ambiguity about the tool's scope.

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 provides explicit when-to-use and when-not-to-use guidance. It names concrete alternatives (analyze_site for a specific lat/lon, rank_markets for ranking by one criterion, site_selection_canvas for an open-ended siting question expecting a shortlist) and states exactly what this tool returns instead of a ranked analysis. It also explains the behavior when the context parameter is non-matching, including the next_tools field that routes the agent to the right tool.

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