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 key behaviors: the unit engine converts to the factor basis (with example conversions: MWh→kWh, tonne→kg, gallon→litre, mile→km) and returns the emissions with the working, GHG Protocol scope, and source. This goes beyond the raw schema and gives concrete insight into the tool's output and conversion logic, though it does not mention failure modes or validation behavior.

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, each earning its place: the first states the purpose and formula, the second gives the input instructions and output highlights, and the third points to companion lookup tools. It is front-loaded with the core purpose and has no redundant or filler content.

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 has no annotations and no output schema, the description covers the essential context: what it does, how inputs are transformed, what the response includes, and where to find factor keys. It is complete enough for an agent to select and invoke the tool correctly. The only gap is the lack of explicit mentions of error conditions or unsupported units, but the description still provides strong operational guidance.

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. The description adds meaning beyond the schema by explaining the unit conversion behavior ('the unit engine converts to the factor basis') and providing examples of supported unit mappings. It also advises how to find the factor_key via search_factors/lookup_factor, giving practical context for that parameter. This raises it to a 4, though it does not fully detail every edge case for the activity object's value.

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 clear statement: 'Turn activity data into greenhouse-gas emissions: emissions = activity × factor.' This names the specific verb ('turn'/'calculate'), the resource ('greenhouse-gas emissions'), and the exact formula. It distinguishes from the specialized siblings (calculate_electricity, calculate_freight, etc.) by positioning itself as the generic activity calculator, and it points to search_factors/lookup_factor for factor keys, reinforcing its role.

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 usage instructions: 'Give an amount + unit and a factor key' and advises using search_factors/lookup_factor to find the factor key. However, it does not explicitly state when to prefer this tool over the sibling calculate_* tools or when not to use it. The guidance is implied (generic vs. specialized) but lacks explicit exclusions or alternative selection criteria.

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 the calculation formula, unit flexibility (km/mi via distance object), and radiational forcing variants. Does not cover output format or edge cases, but sufficient for a pure calculation tool.

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 efficient sentences: the first states purpose and formula, the second gives factor sourcing guidance. No wasted words, front-loaded with the most critical information.

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 covers the calculation method, factor usage, and unit flexibility, which is adequate for a simple calculator. It does not explicitly state the return value format, but that is inferable from the formula and tool nature.

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 already covers all parameters with descriptions (100% coverage). The description adds value by explaining the formula and clarifying that factor_key is per-passenger-km with RF variants, going beyond the schema's minimal description.

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: calculating business travel emissions (Scope 3 Cat 6) using the distance method, with an explicit formula. This distinguishes it from sibling calculate_* tools that handle other emission categories.

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 guidance on how to obtain factor keys via search_factors and notes the with_rf/without_rf variant distinction. Does not explicitly contrast with other calculate tools, but the name and context make the use case 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 carries the burden of disclosure. It states that location-based emissions are always returned and market-based only when specific inputs are supplied, and mentions that supplier_factor wins over market_factor_key (via schema, not description). It does not describe the output format or error handling, but for a calculation tool, the core behavior is adequately transparent.

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 tool's purpose, and every clause adds value. It is compact and well-structured, with no redundant information.

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 moderate complexity (two methods, two optional parameters) and 100% schema coverage, the description covers the main usage scenarios well, including how to obtain factor keys. It lacks mention of the output structure or precedence between supplier_factor and market_factor_key (though schema covers precedence), but overall it is sufficiently complete for an agent to invoke correctly.

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 baseline is 3. The description adds context beyond the schema: it explains the role of supplier_factor (e.g., green tariff/REC = 0) and market_factor_key (residual mix), and directs to search_factors for keys. This extra context 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 it calculates GHG Protocol Scope 2 for purchased electricity using both location-based and market-based methods, distinguishes from sibling calculation tools by specifying the resource (electricity) and the dual-method scope, and mentions referencing search_factors for grid keys.

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 explains when to use market-based (supplying supplier_factor or market_factor_key) versus location-based (always returned) and points to search_factors for key discovery. However, it does not directly compare with other calculation tools or state when not to use this tool, though the scope 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 fully discloses behavior: it assembles lifecycle modules (A1-A3, B, C1-C4, D) into stages, totals the boundary, reports module D separately, and flags missing stages as not-assessed (never zero). This goes beyond basic input/output and sets accurate expectations.

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 dense but every sentence earns its place: purpose, usage, behavior, and key lookup are all covered in three sentences. It is front-loaded with the core function and avoids 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?

For a complex calculation tool with no output schema and minimal annotations, the description covers purpose, input structure, boundary options, calculation behavior, and how to find valid keys. It is sufficiently self-contained for an agent to invoke correctly.

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 has 100% coverage but is minimal; the description adds significant meaning by specifying the accepted boundary values (A1-A3, A1-A4, A1-A5, A1-C) and giving example units for quantity. This helps the agent construct correct inputs.

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, using a specific verb and resource. It distinguishes from sibling calculation tools (electricity, freight, etc.) and lookup tools via its material focus and reference to search_factors for keys.

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 clear usage context: give a material key and quantity, optionally specify a boundary range, and find keys via search_factors. It does not explicitly state when not to use this tool compared to alternatives, but the material focus and boundaries make the intended use clear.

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 transparency burden; it discloses the calculation method ('emissions = tonnes × km × factor') and the factor-key source. It doesn't cover error handling or output details, but the formula fully specifies the core behavior of a calculation tool.

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 convey scope, method, formula, and factor lookup; no filler or repetition of schema fields.

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 3-parameter calculation tool with no output schema, the description provides the formula, factor lookup route, and example, which is sufficient for basic invocation. It leaves minor ambiguity about output format and invalid-factor behavior, but these are lower-stakes for a deterministic calculator.

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 input schema already documents all three parameters (100% coverage), but the description adds meaning by expressing the formula that connects mass and distance to the factor, and by giving a concrete factor_key example ('freight.road_hgv.tonne_km') plus a lookup path via search_factors.

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 specifically identifies the tool as calculating 'Freight & logistics emissions (Scope 3 Cat 4 & 9)' and gives the exact GLEC tonne-km formula, clearly distinguishing it from sibling calculate_* tools for other emission categories.

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 concrete usage context by stating the GLEC method and instructing users to 'Find mode factors via search_factors', with an example key. It doesn't explicitly say when not to use it or mention alternatives like calculate_activity, but the freight/logistics framing makes the intended scenario clear.

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 the return structure (attribution factor, financed emissions, total, DQ score, audit trail) and mentions PCAF source, which gives insight into the computation. It does not mention side effects or prerequisites, but 'Compute' implies a read-only operation.

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 an actionable verb, and every clause adds value—listing specific outputs and the audit trail. There is no redundant or vague phrasing.

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 (multiple outputs, no output schema), the description covers the main return values and relevant context (PCAF source, outstanding-weighted score). It lacks error-handling or input-format details, but for a calculation tool this is nearly 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 coverage is only 50% (holdings has a description, asset_class does not). The description does not elaborate on either parameter, adding no semantic value beyond the schema. It doesn't explain how holdings should be structured or what asset_class values are accepted, leaving a gap for the undocumented parameter.

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 ('Compute') and resource ('PCAF Part A financed emissions for a portfolio'), clearly stating the tool's function. It distinguishes itself from sibling calculation tools by naming distinct outputs (attribution factor, portfolio total, data-quality score, audit trail), making its purpose unique.

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 usage is implied: an agent would invoke this when asked for PCAF Part A financed emissions. However, there is no explicit when-to-use guidance or mention of alternatives (e.g., calculate_spend) or exclusions, leaving the choice to the agent's 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?

With no annotations present, the description carries the transparency burden well: it discloses the calculation formula, the special currency/year requirement, and notes that no FX conversion is applied. It does not explicitly describe return value structure, but the formula and tool context make the calculated result reasonably clear.

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 dense sentences deliver the formula, the core caveat, and a cross-tool pointer with a concrete example. Every clause creates value, with no wasted words.

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 only two required parameters, no annotations, and no output schema, this description is largely sufficient. It covers the method, prerequisites, and lookup path; the only obvious improvement is a short explicit statement of the returned quantity—estimated emissions—though the formula already implies it.

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; the description adds more value by explaining that factor_key must be a 'spend_based' EEIO sector factor, providing a fully qualified example key, and by stating that spend must match the factor's currency/year. This goes beyond the schema's minimal 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 states exactly what the tool does: it calculates spend-based EEIO Scope 3 emissions using a clear formula (emissions = spend × economic-intensity factor). It also distinguishes itself from sibling calculation tools by emphasizing the spend-based approach and giving a concrete sector factor example.

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 clearly indicates when this tool is relevant—for spend-based screening—and provides a direct pointer to search_factors for finding sector factors. It also gives an important usage caveat about matching currency/year, though it stops short of explicitly saying when not to use this tool vs. activity-based alternatives.

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 full burden and thoroughly discloses behavior: it explains the five classification types, what each record contains (publisher, route, confidence, review date, stale flag), and stresses that these are 'authored judgements', not derived from data. This goes beyond typical transparency.

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 dense but every sentence contributes: it defines the tool, gives context, lists classifications with meanings, describes return record fields, and provides usage guidance. It is not overly verbose, though the classification list adds length; it remains efficiently structured.

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?

Without an output schema, the description must explain what the tool returns, and it does: it enumerates the fields in each record (publisher, route, confidence, review date, stale). It also covers when to use and the data's authoritative nature, making it fully self-contained 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?

All three parameters are already described in the schema (100% coverage), so the baseline is 3. The description adds substantial semantic meaning to the 'classification' parameter by explaining each of its five values, and connects family/country to the zero-row scenario, enhancing understanding.

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 immediately states 'Ask why a factor is NOT in the corpus', a specific verb and resource, and distinguishes it from sibling calculation/lookup tools by focusing on explaining absence. It also positions it as the 'reasoned counterpart to coverage', making its unique scope clear.

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 says 'Call this before concluding that a gap is permanent, and before telling a user to look elsewhere', giving a clear when-to-use directive. It does not name specific alternative tools or provide when-not-to-use conditions, but the context is strong enough to infer.

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 carries the full burden of behavioral disclosure. It details the return envelope including provenance (publisher, cell, retrieval date, licence, redistribution, attribution) and verification (GWP set, source note), and even mentions what the publisher did not provide. This is unusually transparent.

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, compact paragraph that front-loads the primary purpose, then details the return envelope and missing-key behavior. Every sentence adds value, and there is no redundancy or 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?

Given there is no output schema, the description thoroughly explains what the tool returns, including the audit envelope fields and verification details, and what happens on a missing key. It covers all necessary behavioral aspects for a lookup tool with one parameter, making it 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% and includes an example key, so the baseline is 3. The tool description adds no new parameter semantics beyond repeating 'canonical key,' which is already in the schema. The example in the schema is sufficient; the description offers no additional clarification.

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 looks up a single emission factor by canonical key, and explicitly distinguishes it from search_factors by noting that search_factors should be used when the key is unknown. The verb 'look up' and resource 'greenhouse-gas emission factor' are specific and 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?

The description explicitly says 'Use search_factors first if you do not know the key,' providing clear guidance on when to use this tool versus the alternative. It also explains the behavior when the key does not exist (candidate keys returned), giving users context on error handling.

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 present, so the description must carry behavioral disclosure. It does so well by describing the returned audit envelope (provenance, verification) and the non-failing not_found behavior. It stops short of discussing auth or rate limits, but those are not critical for this tool.

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 focused sentences with no filler: first states what it does, second gives usage guidance, third clarifies error handling. The key behavior is front-loaded.

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 covers purpose, batch behavior, return envelope, and error handling for missing keys. Combined with the schema's key example and max count, an agent has enough to call it correctly. It could additionally point to search_factors for finding valid keys, but that is a minor gap.

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 the parameter description already explains canonical keys, provides examples, and states the max of 25. The description adds context about batch semantics but does not need to expand parameter meaning further.

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?

Clearly states it looks up several emission factors by key in one call and returns the same audit envelope as lookup_factor. It is explicitly differentiated from the singular sibling 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?

Directly instructs to use this tool instead of calling lookup_factor in a loop and describes the batch context, e.g., portfolio or multi-country comparison. This gives clear when-to-use guidance and names the alternative.

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 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.

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

With no annotations provided, the description carries the burden of behavioral disclosure. It honestly describes the returned fields and clarifies that full audit details are intentionally deferred to lookup tools. It does not describe match semantics or empty-result/pagination behavior, so it is not quite 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 dense sentences with no filler. The primary purpose is front-loaded, the return contract is summarized, and the routing guidance is placed at the end.

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 is complete for this tool category: it covers what is searched, what is returned, what is omitted, and which sibling tools cover the omitted case. Since there is no output schema, explicitly naming the returned fields is valuable and 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?

Schema description coverage is 100%, so all four parameters are already documented. The description echoes the search modes by mentioning section, key prefix, and free text, but it does not add any meaning beyond 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 states a clear verb and resource: 'Find emission factors by section, key prefix, or free text.' It also lists the exact fields returned, which immediately differentiates it from lookup_factor and lookup_factors.

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 says when to switch to alternatives: 'for one factor's full audit envelope ... call lookup_factor; for several, call lookup_factors.' This gives the agent a concrete routing decision rather than leaving it to infer.

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