api

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

No annotations are provided, so the description carries the full burden. It discloses the unit conversion behavior (MWh→kWh, tonne→kg, gallon→litre, mile→km) and the output structure (emissions with working, GHG Protocol scope, source). This is transparent for a calculation tool with no side effects. It does not mention error handling or rate limits, but that is not critical here.

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 two sentences, front-loaded with the core purpose and formula. It packs essential details (unit conversions, output, factor lookup) without redundancy. Every sentence earns its place, and it is highly scannable.

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 simplicity (2 params, no output schema), the description fully covers what an agent needs: what it does, how to provide inputs, unit conversion logic, and what it returns. It also includes a prerequisite step (find factor key) and directs to appropriate tools. Without an output schema, it adequately explains return values.

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% (both parameters described), so baseline is 3. The description adds extra meaning by explaining the unit handling (converting to factor basis) and the output fields, which goes beyond just listing parameter names. It clarifies that activity is an object with value and unit, and factor_key is canonical, complementing the schema.

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 its purpose: converting activity data into greenhouse-gas emissions using the formula emissions = activity × factor. It also details the unit conversion and what is returned (working, scope, source), distinguishing it from generic tools. The mention of finding factor keys via search_factors/lookup_factor differentiates it from specific calculation tools like calculate_electricity or calculate_freight.

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 provides clear usage guidance: give an amount + unit and a factor key, and explicitly instructs to use search_factors or lookup_factor to find the key. It implies this is the generic activity calculator, but does not explicitly exclude specialized alternatives like calculate_electricity or calculate_freight. Still, the workflow is well-defined.

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?

With no annotations, the description must convey behavior. It mentions the formula, factor variants (with_rf/without_rf), and dependency on search_factors, but does not disclose output format, potential errors, or any side effects. It's a read-only calculation implied, but not stated, and edge cases like missing factors are not addressed.

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, each earning its place. The first sentence states purpose and formula; the second gives critical factor-context and lookup guidance. No filler or redundancy.

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?

For a calculation tool with full schema coverage, the description covers the core formula, factor sourcing, and scope. It lacks explicit output details, but given no output schema and that the result is an emissions estimate, the description is sufficiently complete for a competent agent.

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%, providing baseline 3. The description adds value by explaining factor_key variants (with_rf/without_rf) and directing users to search_factors for valid keys, which goes beyond schema basics. It also clarifies the distance unit combinations via the formula.

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 purpose: calculating business travel emissions (Scope 3 Cat 6) using the distance method, including the formula. It distinguishes itself from sibling tools by naming the specific category and method, making it unambiguous which tool to choose.

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 implies usage context by naming the distance method and pointing to search_factors for factor lookups, but it doesn't explicitly state when to avoid this tool or mention alternatives for other categories. It provides clear context but lacks explicit exclusions.

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?

No annotations are provided, so the description carries the full burden. It transparently discloses that location-based is always returned and market-based is conditional, and even gives an example (green tariff/REC=0). However, it doesn't explicitly state precedence behavior (supplier_factor wins over market_factor_key), which is only in the schema 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?

The description is three sentences, front-loaded with the core purpose, then covering behavior, alternatives, and a pointer to a related tool. Every sentence adds value with no redundancy or fluff.

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?

The tool has 4 parameters, no output schema, and no annotations; the description covers the purpose, behavior, and how to source factor keys. It lacks explicit details about output format, but that isn't required given the absence of an output schema. It adequately addresses the complexity of the 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context by explaining that location_factor_key is grid-average, market_factor_key is residual-mix, and supplier_factor can be a contractual value like a green tariff/REC=0. This goes beyond simply repeating parameter names.

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 calculates GHG Protocol Scope 2 for purchased electricity and explicitly identifies both methods (location-based and market-based). It distinguishes itself from sibling tools like calculate_activity and calculate_embodied by specifying the exact resource and metric.

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 explicit guidance on when market-based results are available (when supplier_factor or market_factor_key is supplied) and clarifies that location-based is always returned. It also directs users to search_factors for finding grid keys, providing a clear path to obtaining necessary inputs.

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?

With no annotations, the description carries the burden. It discloses key behavioral traits: assembles lifecycle modules, reports module D separately, and flags missing stages as 'not-assessed' (never zero). It does not mention side effects or authentication, but for a calculation tool these are likely negligible and the core behavior is well explained.

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 two sentences, front-loads the purpose, and packs necessary details (modules, boundary, missing-stage behavior, key lookup) without redundancy. 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?

For a single-parameter tool with a well-documented schema and no output schema, the description covers the behavior, output logic, and usage thoroughly. It explains what the tool does with inputs and its output conventions (e.g., module D separately, missing stages flagged), making it complete for an agent.

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?

The schema already describes the materials array structure fully (100% coverage), but the description adds the boundary options and directs the agent to search_factors for valid material keys—useful context beyond the schema. This meaningfully aids correct invocation.

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 calculates whole-life embodied carbon for materials per EN 15978, with specific details on module assembly and boundary handling. It implicitly distinguishes itself from siblings like calculate_pcaf by focusing on materials and using the EN standard.

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 concrete usage guidance: tells the agent to find material keys via search_factors, and lists optional boundary choices (A1-A3, A1-A4, etc.). It does not explicitly state when not to use this tool, but the material-specific framing and reference to search_factors give adequate context.

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?

With no annotations, the description carries the full burden. It discloses that the factor's denominator dictates the input method, defines TEU as a container slot (not mass), explains the forty-foot conversion, and states the exact error behavior (422 rather than conversion). This goes well beyond a generic 'calculate' statement.

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 somewhat long but every sentence is functional: it states the domain, the core rule, the two methods with examples, the error condition, and the search path. The key rule is emphasized with caps and the structure is logical. It's not verbose, but slightly dense.

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 complexity (two unit systems, error handling, conditional parameters, factor discovery) and the absence of an output schema, the description covers the major pitfalls. It mentions error 422, the search_factors path, and example factor keys. It doesn't describe the return format, but that's arguably not required without an output schema. It's fairly 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?

Even though schema coverage is 100%, the description adds meaning beyond the schema: it explains the conditional requirement (mass required for per-tonne-km, teu for per-TEU-km), the relationship between factor unit and input selection, and unit conversions (forty-foot = 2 TEU). This is significant value added over the schema's bare parameter descriptions.

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 opens with a specific resource and scope: 'Freight & logistics emissions (Scope 3 Cat 4 & 9), GLEC framework.' The verb 'calculate' and the explicit domain distinguish it from sibling tools like calculate_business_travel or calculate_electricity, making the tool's purpose unambiguous.

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 explicitly instructs when to send 'mass' versus 'teu' based on the factor's unit, and warns that a mismatch is refused with a 422 error. It also directs to search_factors for finding the right factor key, covering both the 'how' and the 'when' conditions.

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?

No annotations are provided, so the description must disclose behavior. It mentions outputs (attribution factors, data quality score, audit trail) but does not state if there are side effects, authentication needs, or limitations. It doesn't clarify whether it mutates data or just reads. Given no annotations, this is insufficient.

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 a single sentence that efficiently conveys the tool's purpose and outputs without unnecessary verbosity.

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?

The description provides context about PCAF Part A and outputs, but lacks details on prerequisites, when to use vs other PCAF tools, or any limitations. Given no annotations, it leaves some context to guesswork.

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?

The 'holdings' parameter has a description outlining the structure (outstanding_amount, denominator, emissions or spend data), but the 'asset_class' parameter is undocumented. Schema coverage is only 50%, so some parameters lack clear semantics.

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 specifies the tool's verb ('Compute'), resource ('PCAF Part A financed emissions'), and output details (attribution factor, portfolio total, data-quality score, audit trail). It distinguishes from sibling tools like calculate_embodied or calculate_spend by focusing on the PCAF Part A standard.

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 implies use for PCAF Part A financed emissions calculation, but it doesn't explicitly state when to use this over alternative calculation tools (e.g., calculate_spend) or provide exclusion criteria. It gives some context but lacks explicit guidance.

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?

No annotations are provided, so the description carries the burden. It mentions the input constraint (currency/year) but does not explicitly state whether the tool has side effects or read-only status. As a calculation, it's likely safe, but this is not confirmed.

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 concise, two sentences that pack the formula, the constraint, and a reference to search_factors. No unnecessary details, well-structured for quick comprehension.

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 there is no output schema, the description adequately explains the calculation context, including the EEIO methodology and how to obtain factor keys. The output (emissions) is implied by the formula, so it's sufficient.

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?

The schema provides basic descriptions, but the tool description adds significant meaning by explaining the spend format requirement and giving an example factor key. This enriches the understanding of both parameters.

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 purpose: calculating emissions using spend and economic-intensity factor, with the formula explicitly provided. This distinguishes it from sibling tools like calculate_activity or calculate_embodied.

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 spend-based approach, emphasizes the currency/year constraint, and directs users to search_factors for finding factor keys. While it doesn't explicitly contrast with alternatives, the specific method and constraints make usage clear enough.

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?

With no annotations provided, the description bears the full burden. It transparently discloses that results are 'authored judgements' not derived data, mentions the stale flag, and details the output fields (publisher, route, confidence, review date). This goes beyond surface-level 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?

The description is verbose, with several sentences repeating the same idea (e.g., 'reasoned counterpart to coverage' and 'authored judgements'). It could be tightened while preserving key details, unlike concise equivalents like the high-scoring example.

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?

Despite verbosity, it is thoroughly complete: explains the purpose, every classification, the output structure, the nature of the data (judgements vs. derived), and the appropriate timing for use. Nothing essential 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?

The schema already covers all parameters with descriptions. The tool description adds depth to the 'classification' parameter by explaining each enum value in detail, but does not significantly enhance understanding of the other parameters. 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?

The description clearly states the tool's purpose: to explain why a factor is not in the corpus, with detailed classifications. It distinguishes itself by being the 'reasoned counterpart to coverage' and provides specific use cases, making it distinguishable from sibling tools like lookup_factor.

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 explicit guidance on when to use the tool ('Call this before concluding that a gap is permanent...'), but it does not explicitly name alternative tools or state when not to use it. The guidance is implied rather than directly contrasting with siblings.

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?

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses the audit envelope (provenance, licence and redistribution status, attribution requirement, verification of per-gas sums, GWP set, publisher omissions) and the graceful failure mode of returning candidate keys. It stops short of stating read-only semantics, permissions, or any rate limits, but the disclosure is well above typical.

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 sentences, front-loaded with the core action before the return-envelope detail. The nested parentheticals are dense but every clause conveys distinct information; nothing is padding, though the licence/provenance list is longer than strictly needed.

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?

There is no output schema and no annotations, so the description must describe what comes back, and it does so in detail for both success (value plus audit envelope) and failure (candidate keys). An agent has everything needed to call this correctly and interpret the result.

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?

Only one parameter, and schema coverage is 100% with an example key format already present in the schema. The description restates the 'canonical key' concept and adds the meaningful failure behavior for a bad key, but adds no syntax or format 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 with scope: 'Look up a single greenhouse-gas emission factor by its canonical key.' The word 'single' and 'by its canonical key' implicitly separate it from lookup_factors (plural) and search_factors, and the description explicitly routes to search_factors when the key is unknown.

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 condition for the alternative: 'Use search_factors first if you do not know the key.' That is clear when-to-use guidance. It does not, however, explain when to prefer this over the closely-named siblings lookup_factors or resolve_factor, so the agent must infer that from 'single'.

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?

With no annotations, the description carries the burden well: it discloses the return envelope contents (provenance, publisher, source reference, retrieval date, licence, redistribution, verification) and the partial-failure contract (bad keys land in `not_found` rather than failing the batch). It does not cover rate limits, auth, or ordering guarantees, so not a full 5.

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 tight sentences: the batch purpose and return shape come first, the alternative-routing instruction second, the edge-case behavior last. 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?

There is no output schema, yet the description still characterizes the response (audit envelope fields plus a `not_found` bucket), and the sole input is fully covered by the schema. Nothing needed to call this 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% and the only parameter's syntax, example keys, and 25-key cap are already documented in the schema. The description adds meaningful semantics about what happens to invalid keys, but no format details beyond the schema; 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 ('look up SEVERAL emission factors by key in one call') and immediately distinguishes itself from the singular sibling lookup_factor by emphasizing batch semantics.

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?

Explicitly says when to use this over the alternative: 'Use this instead of calling lookup_factor in a loop', and names concrete triggering scenarios (portfolio, multi-country comparison).

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?

With no annotations, the description carries the full burden and does so thoroughly: it explains that geography is parsed from the description, that omitting country yields a 'geo_match':'proxy' result, that 'review' is intentionally over-inclusive, and that absence responses have structural meanings that should stop the agent from retrying. This is far beyond minimal behavioral 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?

The description is long but each paragraph earns its place: scoping, label semantics, and absence handling are all needed for correct invocation. The use of short capitalized hooks ('PUT THE COUNTRY IN THE DESCRIPTION', 'ACT ON THE LABEL', 'A MISS MAY EXPLAIN ITSELF') front-loads key behaviors and makes the density navigable.

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 three parameters, no annotations, and no output schema, the description provides everything needed to use the tool correctly: what it returns, how the main parameter behaves, how to interpret result labels, what absence responses mean, and how to hand off to related tools. No critical guidance appears 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 baseline is 3, but the description adds real meaning beyond the schema for the critical 'description' parameter: it emphasizes the country must be embedded in the text and gives concrete examples ('diesel per litre France'). This extra semantic context justifies a 4 above 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?

The description names a specific operation ('find the best emission-factor key(s)') and a concrete resource ('for a plain-language description'), and explains the tool's distinctive role against the 16,000-key problem. It also positions the output as ranked matches with key/value/unit/confidence, and routes the chosen key onward to calculate_* tools or lookup_factor, which separates it from siblings.

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 explicit usage direction: 'Prefer this over guessing a key', tells the agent to feed the chosen key to calculate_* or lookup_factor, and points to explain_absence for querying absence directly. It also provides actionable when-to-use/when-not-to-use guidance through the 'accept'/'review' labels and the absence classifications.

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?

With no annotations, the description carries the disclosure burden and does well: it enumerates the returned fields (key, name, section, value, unit, gas) and states the results are sufficient to choose between factors or read numbers "without a second call." It omits anything about ranking, case sensitivity, or pagination behavior beyond the limit param, which keeps it short of a 5.

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 tight sentences, front-loaded with the core verb and resource; the return-value note and the sibling routing each earn their place with 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?

No output schema exists, and the description compensates by describing the return payload, so return values need not be invented by the agent. With alternatives routed and all four params schema-documented, nothing needed to call this 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 description coverage is 100%, so the baseline is 3. The description restates the three filter modes (section, key prefix, free text) that the schema already documents, adding no syntax, format, or combination semantics beyond it.

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 ("Find emission factors") plus the three lookup modes, and explicitly distinguishes itself from lookup_factor/lookup_factors. An agent can identify this as the discovery/browse tool 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?

Names the alternatives explicitly and gives the selecting condition: use this to browse/preview, call lookup_factor for one factor's full audit envelope, lookup_factors for several. Both the when-to-use and when-to-use-something-else are stated.

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