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

The description goes well beyond the readOnlyHint annotation by detailing return behavior (ranked candidates, deterministic warnings, clarification questions, counts, recommended binding), the bounded-sample limitation, and the fact that it is free. It also explicitly states non-goals, providing thorough behavioral context.

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?

Each of the six sentences adds distinct value: purpose, input formatting instruction, use case, output contents, exclusions, and cost. There is no redundancy or filler, and the structure front-loads the core function before details.

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?

Since there is no output schema, the description carries the burden of explaining return values, and it does so thoroughly by listing ranked candidates, warnings, clarification questions, counts, and recommended geography_binding. It also covers scope and limitations, making it complete for a tool of this complexity.

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?

With 83% schema coverage, the schema already describes parameters well. The description adds valuable LLM-specific guidance (extract identifiers, pass as strings, do not include prose, preserve leading zeros) which is not fully captured in the schema, especially for the singular identifier parameter. This pushes it above the baseline of 3.

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 uses a specific verb ('checks') and resource ('identifiers against maintained reference indexes and geometry banks'), clearly stating the tool's purpose. It also explicitly states what it does not do ('does not convert the full dataset or return polygons'), distinguishing it from sibling tools like convert_reference and get_geometry.

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?

Provides explicit when-to-use context: 'Use it when a caller has geography keys but is unsure which system, level, or bank they belong to, or wants to verify a declaration...'. It also gives a when-not by stating it does not convert or return polygons, but does not explicitly name a sibling tool as the alternative, so it falls just short of a 5.

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