Server Quality Checklist

Tool Scores

• calculate_pcafB
  3.4/5.0
  Behavior2/5

  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.

  Conciseness4/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• explain_absenceA
  3.6/5.0
  Behavior4/5

  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.

  Conciseness2/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose4/5

  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.

  Usage Guidelines3/5

  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.

• calculate_business_travelA
  4.2/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• calculate_spendA
  4.2/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• resolve_factorA
  4.2/5.0
  Behavior5/5

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

  Extensively explains return labels, absence types, geography handling, and proxy behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Description is very verbose and repetitive, could be condensed.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers all key aspects: output candidates, labels, absence handling, and next steps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema already describes parameters; tool description adds some clarification but not much beyond schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it finds the best emission-factor key for a plain-language description, distinguishes from lookup/calculate tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Gives guidance on when to use (prefer over guessing) and how to include country, but could be more explicit vs other search tools.

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

• search_factorsA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosure. It explicitly notes that values are redacted, which is a key behavioral trait, and lists the returned fields (keys, names, sections). It implies a read-only operation without side effects, which is reasonable for a search tool. It doesn't mention error handling or rate limits, but these are not critical for a simple search.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with the action and search modes. The second sentence clarifies the return format and redaction, plus directs to lookup_factor for values. No wasted words, excellent structure.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a search tool with no output schema, the description adequately conveys what the tool does and what it returns (keys, names, sections, and that values are redacted). It covers the essential information for an agent to know whether and how to use it, though it doesn't discuss edge cases like empty results or pagination beyond the limit parameter. Overall, it's complete enough for its simplicity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 100% coverage with each parameter well-described (limit, query, section, key_prefix). The description adds minimal extra meaning by mentioning the three search modes (section, key prefix, free text), but this essentially restates what the schema already says. Baseline of 3 is appropriate as the description doesn't significantly expand on the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: finding emission-factor keys by section, key prefix, or free text. It specifies the resource and search modes, and distinguishes itself from lookup_factor by noting that values are redacted and calling lookup_factor is needed for the value.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implicitly guides when to use this tool vs. lookup_factor by stating 'call lookup_factor for the value,' which indicates that this is for searching and lookup_factor for getting actual values. However, it doesn't mention other sibling tools like resolve_factor or calculate_* tools, so it provides clear but not exhaustive alternative context.

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

• calculate_freightA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It transparently reveals the calculation model (emissions = tonnes × km × factor), the GLEC methodology, and the dependency on factor_key lookup. It does not describe output units or error behavior, but the formula is the core behavioral trait for this calculator.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences, front-loaded with purpose, and no filler. The formula and factor-lookup guidance are packed efficiently into a compact description.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has no output schema and no annotations, so the description must cover both inputs and behavior. It explains the input semantics via the formula and points to the factor source, but it stops short of explicitly stating the output emission unit or result format. Overall, it is complete enough for a straightforward calculator tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  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 value by showing how mass, distance, and factor combine in the formula and by giving a concrete factor_key example (freight.road_hgv.tonne_km), which clarifies the expected key format beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description specifies a clear verb and resource: calculate freight/logistics emissions using the GLEC tonne-km method. It also narrows scope to Scope 3 Categories 4 & 9, which distinguishes it from sibling calculators like calculate_activity and calculate_spend.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear context for when to use this tool: freight & logistics emissions via tonne-km. It proactively directs users to search_factors for factor lookup with a concrete section and example, but it does not explicitly state when not to use this tool versus other calculate_* siblings.

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

• calculate_activityA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• calculate_embodiedA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• calculate_electricityA
  4.6/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• lookup_factorA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does so thoroughly. It discloses what is returned (value plus audit envelope), details provenance and verification fields, and explains the missing-key fallback behavior with candidate keys.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences, each earning its place: operation, return envelope details, and usage guidance. The most important information is front-loaded in the first sentence, and the detail is dense but not bloated.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Despite no output schema and no annotations, the description is complete for a single-parameter lookup tool. It explains the return shape, provenance and verification details, error behavior, and when to use the sibling tool, leaving no critical ambiguity.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% for the single 'key' parameter, including an example. The description reinforces that the lookup is by 'canonical key' but does not add substantial parameter semantics beyond the schema, so the baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb and resource: 'Look up a single greenhouse-gas emission factor by its canonical key.' It also distinguishes itself from siblings by explicitly directing users to search_factors when the key is unknown, and describes the narrow lookup scope versus broader search/calculation tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Explicit guidance is provided: 'Use search_factors first if you do not know the key.' This clearly states when this tool is appropriate and names the alternative, which is exactly the kind of usage guidance expected.

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