disclosure-compiler

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

Without relying on annotations, the description adds genuinely useful behavioral guarantees: output is deterministic, citations are attached, missing datapoints are surfaced as explicit gaps, and nothing is fabricated. What it omits is whether the compiled draft is persisted and what request_id/payment_ref imply (annotations mark it non-readOnly, non-idempotent), so side-effect behavior is left unclear.

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

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

Three tight sentences with the core action front-loaded and the anti-fabrication contract second; no filler. Slight redundancy in restating the source inputs that are visible in the schema keeps it from a 5.

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 described, but for a 6-parameter tool with nested objects and 0% schema coverage the definition leaves too much unexplained - notably the payment_ref/request_id mechanics and whether the draft is stored. Those gaps matter given readOnlyHint=false and idempotentHint=false.

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% across 6 parameters including nested objects, so the description must compensate and largely does not. It only gestures at company_facts and ghg_result; framework, options, request_id, and payment_ref are never explained, and 'framework' would benefit from pointing at get_framework or list_frameworks.

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 artifact: 'Compile a deterministic, cited disclosure draft' from company facts plus an optional verified GHG-ledger result. That is distinct from every sibling (get_framework, list_frameworks, verify_result, describe_agent), so an agent can route here without opening the schema.

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

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

Usage is implied by the input mention ('from supplied company facts and an optional verified GHG-ledger result'), which suggests verify_result should run first for the GHG part, but that is never stated. There is no explicit when-not and no named alternative, so the routing is inferential rather than directive.

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, closed-world, non-destructive, and the output schema carries the return shape, so the bar is lower. The description adds the meaningful trait 'deterministic' and the disclaimer field, but says nothing about cost, latency, or that results are stable across calls beyond that word.

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 slightly list-like ('pricing, composition, and the professional-review disclaimer') but every item corresponds to a real return field, so nothing is wasted.

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 that fully specifies returns, rich annotations, and no inputs, the description covers enough to call the tool correctly. It does not need to enumerate return values further.

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?

Zero parameters, so baseline applies; nothing is mistyped or misleading. The description doesn't need to explain any 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?

States a specific verb and resource ('Return deterministic capabilities, version, pack digest, pricing, composition...') for the agent descriptor. An agent can tell this reports static metadata about itself rather than performing a compile/get/verify action. It doesn't explicitly contrast with siblings, but the resource scope is self-evident.

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 statement of when to call this versus compile_disclosure, get_framework, or verify_result. The reader must infer that this is the 'inspect current agent' call. No prerequisites or exclusions are given.

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, openWorldHint=false, destructiveHint=false, so the safety profile is fully covered. The description usefully adds that the result spans multiple artifact types plus lineage, but says nothing about failure behavior for an unknown framework or about payload size.

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?

One sentence, front-loaded with the verb and resource, with the returned artifacts listed in a compact clause. Nothing is wasted.

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 shape needn't be explained, and annotations cover safety semantics. What remains missing is the identifier format and the discovery path from list_frameworks, which matters for a lookup tool with a 0%-documented parameter.

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 carry the burden for the single required parameter, yet it never says whether 'framework' is a slug, display name, or ID, nor where to obtain a valid value. Only the vague adjective 'bundled' hints at the accepted domain.

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 ('Return') and resource ('one bundled framework') and enumerates what the payload contains: datapoints, mappings, sources, lineage. The singularity ('one') implicitly contrasts with list_frameworks, but it never names that sibling explicitly.

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 when-to-use or when-not-to-use guidance and no named alternative, even though list_frameworks is the obvious discovery step that should precede this call. The agent must infer that this is the drill-down after listing.

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?

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds that frameworks are "bundled" and lists returned metadata such as coverage, lineage, version, and digest, but it does not add deeper behavioral context beyond the annotations.

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, front-loaded sentence that lists the returned information without filler. Every phrase contributes to clarifying the list contents.

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 zero-parameter read-only list tool with a rich output schema and full annotations, the description is nearly complete. It could explicitly note that it lists all bundled frameworks, but the essential invocation context is present.

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 are no parameter semantics to explain. The baseline for a parameterless tool is 4, and no additional parameter guidance is needed.

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 specific verb and resource: "List bundled framework IDs" plus the fields returned. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling get_framework beyond the list-vs-get naming difference.

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 no explicit guidance on when to use this tool versus alternatives such as get_framework or compile_disclosure. Usage is only implied by the phrase "List bundled framework IDs," with no conditions or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by naming exactly what gets recomputed (hash, notary payload, invariants, pack currency), telling the agent this is a consistency check rather than a simple read. It does not say whether failures throw or are reported, but the output schema covers the return contract.

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 short sentences with no filler, and the operations performed are front-loaded before the parameter instruction. Slightly dense with undefined terms, but nothing is wasted.

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 carry the safety profile. What remains missing is the relationship to compile_disclosure (which produces the 'prior result') and any failure semantics, which matter for a verification tool.

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

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

Schema coverage is 0% and the single parameter is documented only as a string titled 'Result Json'. The description partially compensates by saying to pass the prior result as JSON, which clarifies format and provenance, but gives no indication of the expected result shape or whether it must be verbatim from a prior tool call.

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?

Specific verb ('Recompute') followed by an enumerated set of artifacts checked: audit hash, notary payload, structural invariants, framework-pack currency. This clearly separates it from compile_disclosure and get_framework. It loses a point only because the enumerated items are domain jargon an agent may not map to sibling concepts.

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?

'Pass the prior result as JSON' implies this runs as a post-hoc check on output from another tool (presumably compile_disclosure), which is an implied usage. However, it never states when to use this versus compile_disclosure or what to do when verification fails, and offers no exclusions.

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