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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable nuance beyond that: 'status is RETURNED but is not a filter — there is no `status` or `min_mw` parameter'. It also discloses the cost/benefit profile ('costs one round trip; the planner would add steps and latency for nothing'). This prevents an agent from assuming schema-like filterability for a returned field.

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 compact yet information-dense. The front-loaded 'FRONT DOOR CHECK' routing decision is placed before any background, and every subsequent section (scope, return fields, examples, exclusions, caveat) earns its place. It avoids restating schema parameter descriptions and does not waste words.

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 10 optional parameters, an output schema, and 90+ sibling tools, the description covers all critical decision points: what the tool does, when to use it over execute_plan, what it returns, a non-obvious filter limitation, and explicit exclusions. The output schema and readOnly/idempotent annotations cover the remaining structured details, so nothing an agent needs to call it correctly is missing.

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 meaning by including a realistic invocation ('search_facilities country=US state=VA min_capacity_mw=10') and warning about non-existent parameters (`status`, `min_mw`) to steer agents away from invalid calls. This disambiguation goes beyond what the schema alone provides.

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 and resource: 'Search 20,100+ global data center facilities across 170+ countries' by location, capacity, operator, fiber, status, or DCPI verdict. It differentiates from siblings by explicitly saying this is for EXISTING facilities, not the construction pipeline (get_pipeline) or a full facility profile (get_facility). Concrete example questions like 'which data centers are in Virginia' make the purpose unmistakable.

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 gives an explicit routing rule: if the ask wants power/fiber/water/verdict context ATTACHED to hits, call execute_plan; if it is a plain inventory lookup, search_facilities is the right call. It names exact alternatives (get_pipeline, get_facility) and explains when NOT to use them. A 'Try:' example provides a concrete invocation pattern.

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