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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond them: results are ranked, each hit carries label/unit/period/verification date, and the full record is returned only when the top match is unambiguous — the last point materially changes how an agent should interpret output. Pagination/truncation behavior is not described.

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?

Front-loaded with the core purpose, the examples earn their space by disambiguating 'plain-language question' vs 'guessed key', and the `get_fact` linkage is placed as a short closing clause. Slightly dense in the opening sentence but no filler.

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?

With no output schema, the description usefully enumerates returned fields and the conditional full-record behavior, which is exactly what an agent needs to decide whether to call again or proceed. The only gap is what the ranking is based on and how to handle a low-confidence or ambiguous result set.

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 parameter meaning is already documented and the baseline applies. The description only restates the namespace filter and does so incompletely — it lists `uk`, `us`, `de`, `eu` but the enum also includes `jp`, which could mislead an agent into thinking Japan is unfilterable. `limit` is not mentioned in either place beyond the schema default.

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 ('ranked canonical fact keys') and shows exactly what input looks like with three concrete example queries. It also distinguishes itself from the sibling by stating 'The keys feed `get_fact`', making the resolve-then-fetch relationship explicit.

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?

Implies the workflow clearly: this tool produces keys that feed `get_fact`, so it is the discovery step before retrieval. It does not state explicit exclusions or when to skip straight to `get_fact` (e.g. if the key is already known), so it falls short of full alternative-routing guidance.

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