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

With no annotations provided, the description fully carries the behavioral transparency burden and does so excellently. It discloses that geography is read from the description text itself, warns that omitting a country may yield a proxy marked 'geo_match':'proxy', explains the accept/review label semantics including the note that roughly half of correct answers are flagged 'review', and details the absence object's classifications (structural, not_yet_sourced, refused, coupled) with actionable instructions like 'STOP, do not retry'. This is far beyond minimal 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?

Although lengthy, the description is dense with valuable guidance and structured in a logical flow: purpose, critical usage tips, label interpretation, and absence handling. Every sentence earns its place; there is no fluff or repetition. The front-loaded purpose sentence immediately orientates the agent, and the subsequent instructions are actionable and specific.

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's complexity (16,000 keys, proxy matching, accept/review labels, absence objects) and lack of output schema or annotations, the description is remarkably complete. It explains the return format (ranked candidates, label/why, absence object), how to interpret edge cases, and directs to explain_absence for further investigation. This covers the essential operational knowledge an agent needs.

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?

Because schema coverage is 100%, the baseline is 3, but the description adds substantial value to the main 'description' parameter: it emphasizes including the country, provides concrete examples ('UK grid electricity', 'diesel per litre France'), and clarifies that geography is parsed from the string. It does not add new semantics for 'limit' or 'section' beyond the schema, but the enhanced guidance on the key parameter justifies a 4.

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 clearly states the tool's function with a specific verb and resource: 'Find the best emission-factor key(s) for a plain-language description'. It distinguishes itself from siblings by mentioning that the chosen key is fed to calculate_* tools or lookup_factor, and by positioning itself as the recommended approach over guessing a key. This unambiguous scope differentiates it from search_factors and direct lookup tools.

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 provides explicit usage context: it is for resolving plain-language descriptions into ranked key candidates, with 'Prefer this over guessing a key' directing when to use it. It also names alternatives and follow-up tools: 'feed the chosen key to a calculate_* tool or lookup_factor' and 'Use explain_absence to ask the same question directly' for absence cases. This gives clear 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.