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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and repeatability are covered. The description adds essentially nothing beyond the title and annotations — no mention of how many suggestions are returned, ordering, or behavior on non-matching prefixes.

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?

A single front-loaded sentence with no filler; every word contributes to the meaning.

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?

An output schema exists so return values need not be described, and annotations cover the safety profile. What is missing is sibling routing and any sense of result shape or matching behavior, leaving this roughly minimal for an autocomplete tool.

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 one parameter at 100% schema coverage, the schema already documents 'partial' including an example format ('EK 01 A'). The description references the partial-code concept but adds no format or matching semantics beyond the schema, so it sits at the baseline.

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?

States a specific verb ('suggest completions') and resource ('postcode') with the scope of a partial input. It is clearly distinguishable from validate_postcode and lookup_postcode in broad terms, but never names or contrasts with those siblings explicitly.

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?

'Partly typed postcode' is an implied trigger condition, so an agent can infer this is for in-progress input rather than a complete code. However, no alternatives or exclusions are given (e.g., use lookup_postcode once the code is complete), leaving the routing decision to inference.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld), but the description adds a genuinely non-obvious behavior: names and house address are withheld unless NG_POSTCODE_MAX_LEVEL is 2 or more. That explains a conditional output shape an agent would otherwise misread as a failure. It still doesn't say what happens when no building falls inside the radius.

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?

Two sentences, zero filler. The primary behavior (return postcode of nearest building to a coordinate in Nigeria) is front-loaded, and the conditional output caveat follows immediately after.

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?

An output schema exists, so return-value structure needn't be restated, and the description covers the one surprising output behavior (field withholding). The remaining gap is the no-result / out-of-radius case and whether max_distance_m truncates or errors, which an agent would benefit from knowing.

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% and all three parameters carry their own descriptions and bounds, so the schema does the heavy lifting. The description adds only the contextual constraint that the coordinate must be in Nigeria, which is mild added value rather than new syntax or format detail. Baseline 3 is appropriate.

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?

States a specific verb (Return) plus resource (postcode of the nearest building) and a precise scope (a coordinate in Nigeria). This cleanly separates it from siblings like lookup_postcode (by postcode) and resolve_address (by address), so an agent can route correctly without opening any schema.

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 reverse-geocoding use case (coordinate in, postcode out) is implied clearly enough that an agent can infer when to pick this over the postcode-first siblings. However, it never explicitly names an alternative or states a when-not condition, e.g. what to do if the caller has an address instead of a coordinate.

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

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

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so the safety profile is covered. The description adds that output depth scales with level, which is useful, but the credit-consumption behavior for levels 2+ lives only in the schema, not the description.

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?

A single compact sentence with no filler, and the primary behavior (confirm assignment) is front-loaded ahead of the secondary tiered behavior. Efficient, though it leaves room that could have been spent on sibling routing.

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?

An output schema exists, so return-value explanation is unnecessary, and the parameter set is tiny. However, for a tool in a dense family of five similar postcode tools, the absence of any differentiation or usage context leaves the definition only minimally complete.

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%: the schema fully documents both postcode format and the five level tiers including credit cost. The description adds no syntax, format or default detail beyond what the schema already provides, so the baseline 3 applies.

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?

States a specific verb+resource: confirming a postcode is assigned and returning address details at higher levels. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling validate_postcode, which plausibly covers the same 'is it assigned' check.

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 offers no when-to-use or when-not guidance and never names an alternative, despite four closely related siblings (validate_postcode, autocomplete_postcode, find_postcode_at_location, resolve_address). The only routing signal ('at higher levels') refers to the level parameter, which the schema already explains.

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

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

Annotations already cover readOnly/openWorld/idempotent, and the description adds real behavioral value beyond them: the tiered precision model, the fact that the address text is forwarded to an external geocoder, and the fallback that returns a `question` to the user rather than a false-precise code. It does not add rate limits or auth context, but for a read-only resolver this is solid disclosure.

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?

Purpose is front-loaded, followed by the precision rule and the parameter-filling instruction. The opening clause ('only as precisely as the evidence allows') is slightly awkward but the whole thing is four tight sentences with little waste.

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?

An output schema exists, so return-shape explanation is unnecessary; the description still flags the `question` fallback, which is the key non-obvious output behavior. Combined with the precision tiers and param guidance, an agent has what it needs, with the main omission being sibling routing.

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, but the description meaningfully clarifies that `landmarks` and `geocode_queries` are agent-derived from reading the address rather than passed verbatim, and echoes the 'at' = address-is-the-landmark rule. That goes beyond the structured field text.

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?

States a specific verb + resource ('Turn a described Nigerian address into a postcode') with the unique twist that output precision varies with evidence. The distinction from siblings like lookup_postcode and validate_postcode is implied by 'described address' vs a written code, though no sibling is named explicitly.

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?

It explains the outcome tiers (full building code vs area prefix with a `question`) and instructs the agent to derive `landmarks` and `geocode_queries`, but it never states when to choose this over the four siblings (lookup_postcode, autocomplete_postcode, validate_postcode, find_postcode_at_location). Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description still adds value by disclosing that the check is offline and that it does not verify real-world assignment of the code — a semantic limit the annotations cannot express. It stops short of saying what happens on a malformed input (error vs. invalid result).

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?

Three short sentences, zero filler, with the core purpose and the cost/scope caveat front-loaded before the sibling pointer. Every sentence earns its place.

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?

An output schema exists, so return shapes need not be explained, and annotations cover the safety profile. Purpose, scope limit, and the alternative tool are all present; only the failure-mode behavior for an invalid postcode is left unstated.

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 one parameter at 100% schema description coverage, the schema already documents the input, including the any-style example. The description adds no format or normalization detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Check a postcode's structure') plus what it returns ('canonical forms and segments'), and explicitly distinguishes itself from lookup_postcode. An agent can tell it apart from autocomplete_postcode or resolve_address without opening a schema.

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?

Gives an explicit when-not ('Does not confirm the code is assigned to a building') and names the alternative to use instead ('use lookup_postcode for that'). It also frames the cost profile ('Free and instant'), which helps an agent prefer this over a heavier lookup.

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