Search Facilities

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral caveats beyond that: status is returned but cannot be used as a filter, there is no `status`/`min_mw` parameter, and construction-stage filtering must go through get_pipeline. It also states the tool takes one round trip versus the planner's added latency.

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 and front-loaded with the most important routing decision, then scope, return fields, example, caveat, and exclusions. It earns most of its length, but there is minor redundancy (get_pipeline exclusion appears twice) and the 'planner would add steps and latency' aside is slightly editorial.

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?

Given the tool has 10 optional parameters, a full schema, an output schema, and safety annotations, the description covers the remaining context an agent needs: when to route to execute_plan, what the tool returns, the status-filter caveat, an example call, and explicit sibling exclusions. The only tiny ambiguity is the mention of 'fiber connectivity' and 'DCPI verdict' as search dimensions without corresponding schema params, but the overall guidance is complete enough for correct selection and 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 coverage is 100%, so the baseline is 3. The description adds a concrete example invocation (search_facilities country=US state=VA min_capacity_mw=10), clarifies that status is a returned field rather than a filter, and warns that `status` and `min_mw` parameters do not exist. That is meaningful guidance beyond the schema.

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 names a specific action and resource: 'Search 20,100+ global data center facilities across 170+ countries' by defined filters, and gives concrete example questions ('which data centers are in Virginia'). It also distinguishes itself from siblings by explicitly saying 'Use this to find EXISTING facilities; do NOT use for the forward-looking construction pipeline (use get_pipeline) or for the full profile of one facility (use get_facility).'

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 opens with a 'FRONT DOOR CHECK' routing rule: if hits need power/fiber/water/verdict context attached, call execute_plan; if it's a plain inventory lookup, search_facilities is correct. It also names the alternatives get_pipeline and get_facility and the conditions that select them, so an agent gets explicit when-to-use and when-not-to-use guidance.

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