ghg-ledger

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 enumerates a rich set of outputs (reports, rollups, dual reporting, factor lineage, notary payload, dry-run weave) and discloses pricing and payment requirements. This goes well beyond a simple 'calculate' statement and gives the agent a clear picture of what to expect.

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 compact and front-loaded with purpose, then outputs, a boundary statement, and pricing in four sentences. It earns its length with valuable details, though some jargon (e.g., 'dry-run weave') could be simplified without losing meaning.

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 four parameters, no schema descriptions, and no annotations. The description provides rich output expectations, which partially compensates for the lack of output schema visibility, but leaves the input side under-specified: the format of activity records, options, and request_id are not explained. Given the complexity, more input guidance is needed for full completeness.

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 0%, so the description must compensate, but it only explains 'explicit activity records' and hints at payment_ref through the payment process. The options and request_id parameters are completely unexplained, and even the structure of what constitutes an activity record is not defined, leaving the agent uncertain how to populate the required 'activities' array.

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 verb+resource: 'Calculate an auditable GHG inventory from explicit activity records.' It then lists concrete outputs (per-line gas/CO2e, Scope 1/2/3 rollups, dual Scope 2 reporting, factor lineage), clearly distinguishing it from siblings like classify_activity or verify_result.

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 a boundary with 'This is calculation, not advice' and mentions usage limits, but it does not explicitly state when to use this tool over alternatives like classify_activity or verify_result. Usage context is implied by the verb 'calculate' rather than explicitly guiding the agent on tool selection.

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 meaningfully reveals non-obvious traits: the tool is deterministic, uses no inference, and returns no suggestion for unknown activity types. It does not describe side effects or error behavior, but these are less critical for a classification tool with an output schema.

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 free of filler. Every sentence adds value, and the unknown-handling note is a useful, compact addition.

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 an output schema exists and the tool has a single parameter, the description covers the most important contextual facts: deterministic behavior, the bundled map, and unknown type handling. It does not detail the return structure, but that is already implied by the output schema. Slightly more context about the expected activity object shape would improve completeness.

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 defines only a loose 'activity' object with additionalProperties and no documented fields (0% schema description coverage). The description references 'activity types' but never explains what properties the activity object must contain or the expected shape/value range, leaving the agent without enough information to construct a valid input.

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 ('suggest') and identifies the resource (scope and Scope 3 category) plus the source (bundled deterministic map). It clearly differentiates this tool from siblings like calculate_inventory and verify_result by emphasizing deterministic, non-inferential classification.

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 clear context: it uses a bundled deterministic map and performs no inference, implying when this tool is appropriate. It also mentions unknown activity types return no suggestion, but it does not explicitly name alternatives or state when not to use the tool.

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. The verb 'Return' implies a non-mutating read operation, but the description does not explicitly state that it is safe or side-effect free, nor does it mention any potential failure modes or prerequisites. It adds some transparency by listing the returned data, but lacks deeper behavioral context.

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 concise sentence of 10 words, front-loading the action ('Return') and listing exactly what is returned. Every word earns its place with 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 the tool has zero parameters and the output schema exists to describe return values, the description is mostly complete for a simple describe operation. However, it lacks any orientation about when to use this tool relative to siblings, and the term 'fleet-standard' is left undefined, though the output schema may clarify.

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 is empty (0 parameters), so the baseline score is 4. The description does not need to explain parameter semantics since there are none, and it correctly omits parameter details.

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 the specific verb 'Return' followed by a clear list of resources (capabilities, version, pack digest, pricing), making it obvious what the tool does. It is distinct from sibling tools like get_factor_pack and list_factor_packs, which focus on factor packs rather than the agent itself.

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?

No guidance is provided on when to use this tool versus alternatives. The description merely states what it returns without mentioning any exclusions, contexts, or comparisons to sibling tools, leaving the agent to infer usage.

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 behavioral disclosure burden. It clearly states what is returned (factors, GWP, conversions, sources, pack SHA) and discloses the non-substitution behavior, which is valuable. It does not mention error handling for missing exact matches, but the output schema likely covers return structure.

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, tightly packed with relevant information. It front-loads the action and resource, then adds the key behavioral constraint. No unnecessary words or redundant details.

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 simple two-parameter tool, the description is largely complete, especially since an output schema exists to define return values. It covers the core purpose and the critical exact-match constraint. It could additionally mention what happens when an exact region/year is not found, but overall it provides sufficient context for an agent to select and invoke 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?

The input schema descriptions are absent (0% coverage), so the description must compensate. It adds meaningful context by describing region and year as exact, bundled keys with no substitution, but it does not provide format, allowed values, or examples for these parameters. The description adds some semantics beyond the bare schema but not comprehensive guidance.

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 ('Return') and clearly identifies the resource: factors, GWP values, conversions, sources, and pack SHA for an exact bundled region/year. It distinguishes itself from siblings by emphasizing the exact-match, no-substitution behavior, which sets it apart from list_factor_packs and other 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 communicates clear context: this tool is for retrieving a single, exact factor pack for a specified region and year. It explicitly states that no nearest-region or nearest-year substitution occurs, which tells the agent when not to expect approximate results, though it does not name an alternative tool for approximate lookups.

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 of behavioral disclosure. It explains what the list includes, implying a read-only operation, but does not explicitly state side effects, permissions, or rate limits. The depiction of output contents adds some transparency beyond the name alone.

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 sentence that lists the returned information without unnecessary words or repetition. It is front-loaded with the verb and resource, making it scannable and efficient.

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 (zero parameters, an output schema present), the description fully captures what the tool does and what it returns. It names all key attributes of the factor packs, making it complete for an agent to select and 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 tool has zero parameters, so there is no parameter semantics to convey. The baseline of 4 applies because the description does not need to compensate for missing parameter documentation.

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 'List' and identifies the resource 'factor packs' while enumerating the exact contents (version/digest, regions, years, activity types, GWP set, MVP coverage). This clearly distinguishes it from sibling tools like get_factor_pack, which presumably fetches a single pack.

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 its usage for seeing available factor packs but does not explicitly state when to use it over alternatives like get_factor_pack. No exclusions or alternative references are provided, but the name and sibling tools make the intended context reasonably 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 provided, the description carries the full burden. It discloses the core behavior: recomputing hash, performing conservation checks, and flagging tampering/stale lineage. No side effects are mentioned, but 'recompute' implies a read-only verification, and the output schema covers return details.

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 well-structured sentences. The first sentence front-loads the main action, and the second adds usage and outcome details. No unnecessary words 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 single-parameter tool with an output schema, the description covers the essential aspects: purpose, usage, and outcome. It does not explicitly mention relationship to calculate_inventory, but sibling context implies it. Overall, the description is sufficient for selecting and invoking the tool 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 a single parameter with 0% description coverage, so the description must compensate. It adds meaning by specifying 'Pass the prior result object as JSON', clarifying that result_json should be a JSON serialization of a prior inventory result, which goes beyond the bare parameter name.

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 specific action: 'Recompute a prior inventory's audit hash and conservation checks.' It distinguishes itself from sibling tools like calculate_inventory and classify_activity by focusing on verification of an existing result rather than creating or classifying.

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: pass the prior result object as JSON, with outcomes of flagging tampering or stale factor lineage. It does not explicitly name alternatives or exclusions, but the context is unambiguous for verification tasks.

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