green-router

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

Annotations already declare this is a write operation and not read-only, and the description adds useful context beyond them: it costs $0.50 after a free tier, performs retirement of offsets, is fail-closed if retirement does not occur, and returns a certificate verifiable for free. It does not detail permissions or whether retirement is reversible, but the key behavioral consequences are disclosed.

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 short and front-loads the paid nature, but it is a run-on sentence with cryptic acronyms, capitalization emphasis, and jargon like 'Verra provenance rides into the certificate.' Some phrases earn their place by conveying cost and fail-closed behavior, while others are unclear or redundant.

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?

Since an output schema exists, the description need not explain return values, and it does cover cost, mutation, fail-closed behavior, and certificate verifiability. However, for a complex paid mutation with a nested required object and 0% schema coverage, it omits critical input semantics and does not mention request_id or how to structure the workload.

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 has 0% description coverage, with a required nested 'workload' object whose properties are undocumented, plus an optional 'request_id' that the description never mentions. The description references 'workload' conceptually but gives no structure, fields, format, or meaning for either parameter, so it does not compensate for the schema gap.

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 specific actions and resources: computes a workload footprint, retires verified offset mass, and returns a machine-verifiable certificate. It is clear enough to distinguish certification from sibling operations like quote_footprint, but it does not explicitly name or differentiate from siblings and uses cryptic jargon such as 'clearinghouse' and 'GR3'.

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 paid cost and 'no retirement, no certificate' condition imply when the tool is needed, but the description does not explicitly say when to use this versus quote_footprint, green_route, or verify_green_certificate. Usage is implied rather than stated as clear when/when-not 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered externally. The description adds nothing beyond those annotations—no statement of what the output describes, whether it reflects static or runtime state, or any side considerations. With an output schema present the return shape is covered, but the description contributes no behavioral context of its own.

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?

A single front-loaded sentence with no filler. It is perhaps too terse for the ambiguity involved, but as a matter of conciseness there is nothing to cut.

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?

Annotations and an output schema carry most of the load, and there are no parameters to explain, so the description is not dangerously incomplete. Still, for an introspection tool an agent would benefit from knowing it describes the calling agent and when to invoke it, which is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The phrase 'input contract' loosely signals the payload describes inputs, which is consistent with the empty 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?

States a verb and a resource ('Return capabilities and input contract'), so the basic action is inferable. However, 'capabilities' and 'input contract' are abstract and it's never made explicit that this describes the calling agent itself or the server, leaving the object of the description ambiguous. Siblings (certify, green_route, etc.) are unrelated, so there is no differentiation burden, but the purpose is still only vaguely pinned down.

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?

There is no indication of when an agent should call this versus proceeding directly to the sibling tools, and no mention of prerequisites or typical triggers. The agent must guess that this is a discovery/introspection call.

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?

Annotations already cover the safety profile (destructiveHint=false, openWorldHint=false), so the bar is lower; the description adds cost context ('FREE') and carbon-only scope. However, it never reconciles why a pure ranking operation carries readOnlyHint=false, which an agent could reasonably read as hidden state changes.

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 with the value proposition front-loaded and no filler. Minor cost: the 'FREE:' prefix and the cryptic 'GR6' token consume attention without being self-explanatory.

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?

An output schema exists, so return values needn't be spelled out, and the description correctly stays high-level there. But for a tool whose required parameter is a free-form nested object, leaving the workload contract entirely undefined is a meaningful gap for correct invocation.

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% and the description does not compensate: 'workload' is an untyped object with additionalProperties=true and its expected shape is never hinted at. 'Eligible path' faintly implies allowed_backends acts as a filter, but neither parameter's format or accepted values are explained.

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

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

States a specific verb and resource — 'rank compute backends by carbon for this workload' — and even names the output shape (greenest eligible path plus gCO2e saved per call). It does not explicitly distinguish itself from the closest siblings (quote_footprint, list_green_certificates), so it falls short of a 5.

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?

'Carbon only (GR6); pair with /neurogenesis/mcp route_task for quality-floor routing' tells the agent when this tool is the right choice and names an alternative plus the condition that selects it. It gives no guidance on when NOT to use it versus the carbon siblings like quote_footprint.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that results are aggregate counts and totals rather than records, which is useful behavior context, but says nothing about pagination, ordering, or scope of the ledger. With annotations carrying the burden, this is an adequate 3.

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?

It is a single short sentence, which is appropriately sized for a simple list tool, and the ledger concept is front-loaded. However, the parenthetical "(honest books, GR8)" and the self-congratulatory marketing tone are pure noise that crowd out actual specification of the limit behavior.

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?

An output schema exists, so return values need not be explained, and annotations are rich. The remaining essential gap is the lone parameter's behavior and where the ledger draws its data from, neither of which the description addresses. For a one-parameter read tool this is adequate but thin.

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?

There is one parameter, "limit," and schema description coverage is 0%, so the description must compensate and it does not — "limit" is never mentioned. The agent learns nothing about what limit truncates (certificates? totals?), its default of 50, or whether results paginate. The gap is entirely unaddressed.

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 identifies the resource as "the certificate ledger" and names what it reports (counts, total grams retired, total clearinghouse cost), so an agent gets the gist. But it never states the action (listing) or whether it returns individual certificates versus aggregates, and it doesn't distinguish itself from sibling "verify_green_certificate" or "certify". The leading "FREE:" spends prime space on pricing rather than purpose.

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?

There is no when-to-use guidance and no reference to any sibling tool. An agent cannot tell from this text whether to call this ledger for an overview or verify_green_certificate for a specific certificate. The only quasi-guidance is the price cue ("FREE"), which is not a usage condition.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two genuinely new facts — the call is free and every model assumption is returned with its source — but says nothing about computation limits, determinism guarantees, or how custom_backend overrides interact with the presets.

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?

Front-loaded with the purpose and the cost signal, then a compact inline field spec and return list; no filler sentences. The telegraphic '?' and brace notation are terse to the point of being cryptic for a first-time reader, which costs it a point.

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?

An output schema exists, yet the description still names the key return values (joules, gCO2e, useful bits, retirement mass, assumptions with sources, Landauer GR1/GR2), so nothing critical is missing on the input or output side. The remaining gap is relational: it never positions itself against certify or green_route for a workflow decision.

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 0% — the single 'workload' object has no documented properties — so the description carries the full burden and does so: it enumerates backend_id with its three enum values, total_tokens, output_tokens, the optional calls/success_score/grid_gco2e_per_kwh/pue, and the nested custom_backend shape with wh_per_1k_tokens. Optionality is marked with '?' and the enum is spelled out, which the schema does not do.

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

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

States a specific verb+resource: computing an energy/carbon footprint for an agent workload, and the 'FREE' prefix implicitly separates it from the paid 'certify' sibling. It never names certify or green_route explicitly, so an agent must infer the boundary rather than read it.

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?

Usage is only implied: 'FREE' plus the word 'quote' signals a no-cost estimate you run before committing to a certificate, but the description never says 'use this before certify' or states any exclusion. There is no explicit when/when-not statement.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it says the recomputation is free forever (GR5), compares against certified numbers, and returns a purchase_id for an independent external check.

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 dense sentence that covers the main action and output. It is appropriately sized, though the leading 'FREE forever (GR5)' cost marker is not the most important information for tool selection.

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?

An output schema exists, so return values need not be explained in detail, and annotations cover the read-only/idempotent behavior. The description adds cost, recomputation logic, and external-check context, but leaves a small gap around what a certificate_id is and where to obtain 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?

There is one required parameter, certificate_id, but schema description coverage is 0% and the description does not explain its format, source, or expected value. It refers to 'a certificate's stored workload' but adds no concrete meaning beyond the parameter name already in 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 uses specific verbs and resource: recompute a certificate's footprint, compare against certified numbers, and surface a clearinghouse purchase_id. This clearly identifies verification of an existing green certificate, but it does not explicitly differentiate itself from siblings like certify or list_green_certificates.

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 the usage context: it surfaces the purchase_id needed for the independent x402-C verify_retirement check. However, it does not state when to use this tool versus alternatives such as certify or list_green_certificates, nor does it mention exclusions or prerequisites.

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