AgentLedger

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the authentication rule (the agent's own secret or the workspace key, matching GET /v1/alerts) and the nature of the alerts surfaced. It omits rate limits and pagination behavior, keeping it from 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?

Two tight sentences with the resource description front-loaded and the prerequisite second; nothing is padded. The credential sentence partially duplicates the schema, which is the only minor waste.

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 no explanation, and authentication is covered. Coverage is good but not exhaustive — no note on result ordering, pagination, or volume limits for a history-listing 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 description coverage is 100%, so the either/or credential semantics are already documented in the schema and the description largely restates them. Baseline 3 is appropriate — the description adds little parameter 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?

Names a specific resource (alert history for an agent) and enumerates what it returns (80% budget warnings, spending spikes), which is concrete and distinct. It does not explicitly contrast itself with siblings like ledger_report or ledger_track, so it stops 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?

Usage is implied — you call it to inspect an agent's alert history — and the credential prerequisite (agent_secret or workspace_key) is stated, which is real guidance. But there is no explicit when-to-use versus when-not guidance or named alternative among the siblings.

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, and destructiveHint=false, so the safety profile is covered structurally. The description contributes the return format ('as markdown'), which is genuinely useful context beyond the annotations, but says nothing about size, pagination, or truncation of the fallback full-docs response.

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 that leads with purpose and follows with the coverage list; no filler or redundant sentences. The inline enumeration is a little dense but earns its place by defining scope.

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-value structure need not be explained, and the annotation set covers the safety profile. For a low-complexity, no-required-param, read-only docs tool the description is essentially complete; only cross-tool routing guidance 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?

Schema coverage is 100% and the single topic parameter is fully documented in the schema, including the default and the unknown-topic fallback. The description repeats the topic areas but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 is appropriate.

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 names the tool's function (self-serve documentation) and enumerates the exact content areas it covers — quickstart, MCP tools, REST endpoints, budget caps, error codes, idempotency. An agent can immediately tell this is a documentation look-up tool. It does not, however, differentiate itself from doc-oriented siblings such as ledger_examples or read_skill, which likely also return prose/guidance.

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: the topic list signals the situations in which the tool is relevant, but there is no explicit when-to-use/when-not-to-use statement and no routing against the doc-adjacent siblings (ledger_examples, read_skill). Minimum-viable guidance rather than directive 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 only flag non-read-only, idempotent and destructive; the description adds substantive context beyond them: the decision is a one-shot exception consumed by the next ledger_track rather than a raised cap, only pending permits are decidable, and the credential separation model. It does not contradict idempotentHint — re-deciding an already-decided permit is a no-op.

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 short sentences, each carrying distinct content: the action and its scope, the authority separation, and the consumption semantics. The key constraint (owner-only) is front-loaded in the first line.

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?

Output schema exists, so return values need no explanation here. For a destructive, non-idempotent-looking mutation the description covers authorization, valid inputs, state requirements and post-decision consequences — everything an agent needs before invoking 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 description coverage is 100%, so agent_id, approval_id, decision and workspace_key are already documented with their meanings. The description restates the 'approve'/'deny' enum for decision and adds the 'pending permits only' constraint, but contributes no format or sourcing detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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 pair and resource ("Approve or deny a pending spend permit") and immediately scopes it ("workspace owner only"). It also implicitly separates itself from the sibling ledger_request_approval by explaining that requesting and deciding are different authorities, so an agent can pick the right tool without opening schemas.

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?

Explicitly names the precondition (only pending permits can be decided), the authorization requirement (workspace owner only), and the alternative path (agent_secret can REQUEST via ledger_request_approval but never decide). When/when-not and the alternative are all present.

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, and destructiveHint=false, so the safety profile is covered. The description adds the scoping constraint (personal vs workspace-wide results), which is helpful context, but says nothing about pagination, result limits, or auth failure 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?

A single short sentence, front-loaded with the verb and resource and with zero filler. Nothing redundant or padded.

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, and all four parameters (none required) are fully documented in the schema. The only mild gap is that the description does not hint at the no-argument default behavior or filtering by state, but the schema carries that adequately.

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 every parameter (state, agent_id, agent_secret, workspace_key) is documented in the schema itself. The description's scope wording loosely parallels the agent_id/workspace_key distinction but adds no syntax, defaults, or format detail beyond what the schema provides, so baseline 3 applies.

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 ('List') and resource ('spend-approval permits') plus scope ('yours, or your whole workspace's'), so an agent can distinguish it from ledger_approval_decide or ledger_check_spend. It stops short of naming which sibling to use for a different need, but the resource is 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 phrase 'yours, or your whole workspace's' implies the two access modes that map to agent_secret vs workspace_key, which is useful implied guidance. However, there is no explicit when-to-use, no exclusions, and no routing to alternatives such as ledger_check_spend when the agent wants a single permit's status rather than a list.

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 and idempotentHint=true, and the description reinforces this with 'Read-only: nothing is recorded or reserved.' It adds useful behavioral context beyond the annotations: it is equivalent to the /proxy/{provider} gate, returns stable reason codes, and does not reserve funds.

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 front-loaded with the core purpose and then compactly delivers return details, gate equivalence, side-effect transparency, and input constraints. Each sentence adds distinct value; the parenthetical enum list is dense but directly useful for interpreting the response.

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 output schema exists, the description does not need to fully restate return values; it still names the key response elements. It covers when to call, what inputs to provide, side effects, and the relationship to sibling tools, making it complete for correct selection and 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?

Although schema coverage is 100%, the description adds crucial semantics the schema alone does not convey: amount_cents and model+tokens_in/tokens_out are mutually exclusive spend shapes. It also gives concrete examples ('any rail, e.g. an x402 purchase') and clarifies tokens_out means 'e.g. your max_tokens', which helps an agent map values correctly.

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 an explicit imperative, 'Ask BEFORE you spend: may this agent spend this much right now?', which states the exact action and resource. It also distinguishes itself from ledger_track by noting that spending must be recorded separately, and from the proxy gate by clarifying it makes the same decision.

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 when-to-use guidance ('Ask BEFORE you spend'), what the tool does not do ('nothing is recorded or reserved'), and names the follow-up alternative ('record the spend with ledger_track afterwards'). It also specifies the required input shape ('Give exactly one spend shape'), leaving little to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context by stating the output is a 'complete, runnable Python recipe', implying code generation. However, it doesn't elaborate on return format or side effects beyond annotations, which is acceptable given the safe nature.

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 zero filler. It immediately communicates the key value (complete, runnable recipe) and the resource (common integration pattern), leaving the parameter details to the schema.

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 is simple (one parameter) and has an output schema, so the description doesn't need to explain return values. It sufficiently covers the core purpose, and the schema handles the pattern selection. It could slightly mention that the output is Python code, but 'recipe' already implies that, so completeness is high.

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% – the pattern parameter is fully documented with its four allowed values. The description does not add any parameter-specific meaning beyond the schema, so the baseline 3 applies.

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 provides 'Complete, runnable Python recipe' for a 'common AgentLedger integration pattern', specifying the verb and resource. It distinguishes itself from siblings like ledger_track or ledger_report by focusing on recipes/examples, which is a different 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?

No guidance on when to use this tool versus alternatives. It doesn't mention that it should be used for learning/starting points, nor does it exclude cases like when to use ledger_api_docs instead. The description is purely functional without context for 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?

Annotations already indicate readOnlyHint and idempotentHint, but the description adds valuable behavior: the exact cost formula, the conservative treatment of cache rates, and the meaning of the 'verified' flag with the caution that unverified prices are estimates. This goes well 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 well-structured with a clear opening, rationale, formula, and caveat. Each paragraph serves a distinct purpose without redundancy. It is slightly longer than minimal but every sentence earns its place.

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, the description does not need to explain return structure. It covers the computation, the source/verification semantics, and the reason for existence, which is sufficient for an agent to call it correctly and interpret results.

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% and each parameter is described in the schema. The description adds the cost formula showing how tokens_in and tokens_out are used, and clarifies that the model id is the one being called. This enriches the schema definitions with practical meaning.

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 'What will this call cost?' and states it is priced from the same table the caps use, giving a specific verb and resource. It also explains why it exists (ledger_track requires caller-supplied amount_cents) and distinguishes itself by returning the enforcement number. This clearly separates it from ledger_track and other siblings.

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 the problem with ledger_track and states this tool returns the number for honest reporting and pre-spend planning, implying use before a call. It does not list explicit when-not-to-use scenarios or name alternatives, but the rationale makes usage context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: enforcement happens BEFORE provider contact, provider credentials are forwarded but never stored, and the output contains base_url, headers, and SDK changes. No contradiction with 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 front-loaded with the core action and consequence, then provides rationale, return contents, and credential safety. Every sentence earns its place and there is no filler or repetition of schema 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 tool with only 4 parameters, 100% schema coverage, full annotations, and an output schema, this description is complete. It tells the agent what the tool does, why it matters, what it returns, and the key security behavior, without needing to reproduce structured schema details.

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 baseline is 3. The description adds extra value by clarifying that the provider credential is not part of the tool's operation and stays in Authorization / x-api-key, which helps interpret agent_secret and workspace_key semantics 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 names a specific verb and resource: 'Point your provider traffic at the proxy so budget caps are enforced', and specifies exactly what the tool returns. It clearly distinguishes this from ledger_track, which only records spend after the fact.

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 explains the gap this tool fills versus ledger_track: MCP-connected agents could record spend but could not refuse calls, and this tool enforces caps on every LLM call. It does not explicitly state prerequisites or when-not-to-use cases, so it falls just short of a 5.

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 establish read-only, idempotent, and non-destructive behavior, so the description carries a lighter burden. It adds valuable context by specifying the credential requirement (agent_secret or workspace_key, same rule as GET /v1/report) and summarizing the return contents, though it does not cover rate limits or pagination.

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 that are front-loaded with purpose, then returns, then credential requirement. Every sentence 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 presence of an output schema, annotations, and full schema coverage, the description is complete enough: it explains the report's purpose, summarizes return values, and states the credential rule. It only lacks explicit usage guidance relative to sibling tools, which prevents a 5.

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 the schema already documents all four parameters. The description reinforces the credential rule but adds no syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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 ('spend report') and resource (agent spend over a rolling window), and it enumerates the key outputs such as total spend, breakdowns, budget status, and anomalies. However, it does not explicitly differentiate this tool from siblings like ledger_alerts or ledger_track, so it stops short of the top score.

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 guidance on when to use this tool versus alternatives such as ledger_alerts, ledger_track, or ledger_set_budget. It only states what the tool returns and its credential requirement, leaving usage decisions to 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?

Beyond the annotations (which only say non-readOnly, non-idempotent, non-destructive), the description discloses the one-shot consumption rule, the 1-hour expiry, that the budget cap is unchanged, and the approval/authorization model (owner human or supervisor with workspace_key). This is exactly the behavioral context annotations cannot carry.

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 core action, then the lifecycle, then auth. Nearly every sentence carries distinct load, though the auth sentence could sit earlier and the density is high for a single paragraph.

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 non-idempotent mutating tool with a 6-param schema (100% documented) and an output schema present, the description covers everything needed: trigger, artifact semantics, expiry, consumption, decision path, and auth. Return values are correctly left to the output schema.

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 baseline is 3; the description adds real meaning by clarifying that the permit is for 'exactly amount_cents' (no partial fit) and by disambiguating the two auth parameters: workspace_key is for claiming a brand-new agent_id, otherwise pass agent_secret. That resolves a choice the schema only lists as 'either this or workspace_key'.

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 ('Ask your workspace owner for a one-shot spend exception') and precisely scopes the artifact created: a pending permit for exactly amount_cents on a given service. It also names the triggering context (a ledger_track the cap would refuse), so it is unmistakable against siblings like ledger_track and ledger_set_budget.

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?

Gives an explicit when ('before a ledger_track that the cap would refuse') and routes to the relevant siblings by role: ledger_approval_decide for the decision, ledger_approvals to poll. It also distinguishes the budget-raising alternative implicitly by noting the cap itself does not change.

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 flag destructive=true and idempotent=false, but the description adds substantial context beyond them: spend history is preserved, subsequent writes fail with agent_secret_mismatch, the agent_id remains claimed so no other workspace can inherit the ledger, and the owning workspace_key is required. This is exactly the kind of consequence detail an agent needs before a destructive call.

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 core action and its key non-effect, then usage, then side effects, then return shape. Every sentence carries information; no 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?

Covers purpose, trigger conditions, irreversible-ish consequences, auth requirement, and even names the return fields despite an output schema existing. Nothing an agent needs to call this destructive tool correctly 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?

Schema coverage is 0% for both parameters, so the description must compensate. It states that workspace_key must be the key that owns agent_id, establishing the ownership/authorization relationship between the two parameters, though it does not describe agent_id's format beyond identity.

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 (invalidate/revoke), the exact resource (agent_id's agent_secret), and a delimiting scope clause ('WITHOUT deleting its spend history') that distinguishes it from sibling ledger_rotate_secret. An agent can tell this apart from rotation without opening either 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?

Gives two clear triggering conditions ('credential may have leaked', 'stop an agent writing') and implicitly routes to rotation via 'until you rotate a new secret in'. It does not explicitly name ledger_rotate_secret as the follow-up alternative, so it stops short of full when/when-not routing.

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 declare destructive=true and idempotent=false, and the description adds genuinely new behavioral facts: the old credential stops working immediately, ownership authorization is required, self-rotation is blocked, and the new secret is shown only ONCE and must be stored before the response is dropped. This is rich disclosure beyond the annotation set.

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 core action and consequence, and each paragraph adds distinct value (usage, authorization constraint, return contract). It runs slightly long across four paragraphs, but no sentence is 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?

For a destructive, non-idempotent credential-rotation tool, the description covers purpose, precondition, authorization, irreversibility, the one-time return, and the error contract. Even though an output schema exists, the explicit return shape removes any ambiguity about the one-shot secret.

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 semantics of both parameters. It explains that agent_id must already be owned by the workspace and that workspace_key must be the owning key, which is meaningful authorization context. It stops short of stating concrete formats or where to obtain workspace_key.

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 ('Mint a NEW agent_secret for an agent_id') and immediately clarifies the consequence (invalidating the old one). It explicitly differentiates itself from the sibling ledger_track by noting it 'never claims a new agent_id', so an agent can distinguish the tools without opening schemas.

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 names the exact scenario ('RECOVER an agent whose secret was lost'), states the precondition (workspace_key that owns agent_id), and gives an explicit exclusion ('an agent's own agent_secret cannot rotate itself' and the leaked-credential rationale). The failure mode for an unknown id is also documented.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses the warn-at-80%/block-on-exceed behavior, that enforcement manifests as a rejected ledger_track call, that existing budgets are overwritten, and precise auth semantics (workspace_key required to raise/remove a cap or claim a new agent_id; agent_secret can only tighten, never loosen). This is rich context that the structured fields do not carry.

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 purpose is front-loaded in the first sentence and the denser paragraphs are grouped by topic (cap dimensions, overwrite rule, credential lifecycle). It is longer than most definitions, but nearly every sentence carries operational information; only mild tightening would be possible.

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 7-parameter mutation tool with an output schema present, the description covers everything an agent needs: enforcement behavior, required vs optional params, overwrite semantics, and the full credential lifecycle including the one-time agent_secret return. Return values are appropriately left to the output schema.

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, but the description adds genuine meaning: it explains that monthly_cents/daily_cents and monthly_tokens/daily_tokens are independent dimensions covering disjoint rails, that monthly cap is required while the rest default to 0, and which credential each parameter requires. This goes beyond the schema's per-parameter blurbs.

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 first sentence states a specific verb and resource ('Set spending caps for an agent') and immediately elaborates scope with the enforcement mechanism. It is clearly distinguishable from siblings like ledger_track (which it names as the enforcement point) and ledger_request_approval. An agent can identify what this does 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?

The description gives strong conditional guidance: dollar vs token caps are independent dimensions and 'Set both if the agent uses both,' monthly cap is required, and agents that need a larger allowance are routed to ledger_request_approval (its owner). It names an alternative with the condition that selects it, though it never states an explicit when-not-to-use case.

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 only declare the generic safety profile (readOnlyHint=false, idempotentHint=false), while the description adds substantial non-obvious behavior: the workspace_key is revealed exactly once and cannot be re-revealed, minting is rate-limited per caller IP, the free tier is capped at 3 agents, and the returned secret chain authenticates later writes. That is exactly the kind of operational context annotations cannot carry.

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?

Well front-loaded: the free-workspace purpose and the 'call this first' imperative lead, and the credential chain follows in logical order. The closing paragraph on the paid x402/Pro path is tangential to invoking this tool and is the one part that does not clearly earn its space.

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 zero-argument, unauthenticated bootstrap tool with an output schema present, the description covers everything an agent needs: prerequisites (none), the credential lifecycle, tier limits, rate limiting, and which tool to call next. Nothing required to call it correctly 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 schema has zero parameters (baseline 4), and the description reinforces this deliberately ('Takes NO arguments on purpose: the goal is zero friction'), which is helpful rather than redundant. There is no parameter syntax left to document, though the description adds nothing about the shape of the returned credential beyond what the schema/output schema covers.

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 concrete verb+resource ('Get a FREE AgentLedger workspace') and immediately scopes it as a zero-argument bootstrap operation analogous to POST /start. It also explicitly contrasts itself with the sibling tools (ledger_track, ledger_set_budget, ledger_report, ledger_alerts) that require credentials, so an agent can differentiate it without opening any 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?

Gives an explicit selection rule: 'Call this FIRST if you have no credentials yet,' and explains why the alternatives are unavailable in that state. It further describes the exact hand-off sequence (workspace_key → first ledger_track for a NEW agent_id → agent_secret), leaving nothing to 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?

Annotations only say write, non-idempotent, non-destructive; the description goes far beyond by disclosing the agent_secret minting/auth flow, the $100,000/entry cap, that over-cap entries are blocked rather than logged, and the critical caveat that caps bind the reported amount while only /proxy/{provider} enforces real spend. This is exactly the behavioral context annotations cannot carry.

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 core action is front-loaded in the first sentence, then the auth and cap mechanics follow in tight paragraphs with no filler. It is dense and long for a single tool, and a few clauses (e.g. the /start aside) could be trimmed, so a 4 rather than 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?

For a 9-parameter authenticated write tool with an output schema present, the description covers the full call lifecycle: claiming, subsequent auth, caps, blocking behavior, and trust limitations. Nothing an agent needs to invoke it correctly is missing; return values are legitimately left to the output schema.

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, but the description adds meaning on top: why agent_secret/workspace_key exist, the conditional requirement per call, and the reporting purpose of tokens_in/tokens_out + model. That genuine added value over the schema justifies a 4 rather than the baseline 3.

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 ('Record a spend entry for an AI agent') plus the scope of rails accepted and optional token counts. An agent can immediately distinguish this write-oriented tracking tool from read-side siblings like ledger_check_spend and ledger_report.

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?

Gives concrete conditions: workspace_key is needed only for claiming a brand-new agent_id, agent_secret is needed for every later call, and tokens/model should be included on every LLM call. It also routes real-enforcement users toward /proxy/{provider}. It stops short of explicitly contrasting this tool against the closest siblings (e.g. ledger_check_spend, ledger_report), which keeps it off a 5.

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 annotations already covering readOnly/idempotent/non-destructive, the description goes well beyond them: it explains the long-poll hold semantics and 30s cap, the cursor-as-ack contract, the exact condition that triggers redelivery ('when the pair changes, events that were served but never acked come back with redelivered: true'), and the credential rule. That is precisely the operational context an agent cannot infer from 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?

Purpose is front-loaded in the first sentence, and the dense material (polling loop, ack, redelivery, credentials) is ordered by what a caller needs next. It runs long for a tool description, and the webhook parenthetical and the event-envelope enumeration are partly covered by the output schema, but almost every sentence carries operational weight.

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 9-parameter, stateful, long-polling tool this covers the full picture: invocation pattern, ack/redelivery failure modes, auth options, and event shape. With an output schema present, the envelope description is a bonus rather than a gap-filler, and nothing an agent needs to call this correctly is absent.

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, but the description adds real meaning on top: it explains why `consumer_id` must be durable, how `cursor` functions as an acknowledgement rather than just an offset, and the coupled semantics of `client_instance` + `client_started` (per-boot token pair triggering redelivery). These relationships are not expressible in the flat 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 specific verb and resource — long-polling an agent's event feed — and frames it against the webhook alternative ('an agent on stdio MCP cannot host one, so it waits here instead'). That contrast makes the tool's niche immediately legible. It stops short of differentiating from the closest sibling, ledger_alerts, so an agent comparing the two gets no help from this text.

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?

Gives concrete operating instructions: call in a loop, hold up to `timeout` (max 30), reuse a stable `consumer_id`, pass the returned `cursor` back as the ack, and opt into `client_instance`/`client_started` for restart redelivery. What's missing is when-not-to-use guidance or a named alternative among siblings (e.g. ledger_alerts) for the non-polling case.

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. The verb 'read' implies a non-destructive operation, but the description does not elaborate on error handling, idempotency, or any side effects. Since it is a simple read operation, the primary behavior is clear, but the lack of explicit clarification about potential failures or returned data (beyond the output schema) leaves a gap. A 3 reflects adequate basic coverage without richer 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, front-loaded sentence that conveys the essential purpose without any fluff. It wastes no words and is immediately actionable.

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 (one parameter, an output schema exists), the description is sufficient. It states the action and the URI input. It does not explicitly mention prerequisites beyond the URI source, but that is covered in the schema. The lack of error details is acceptable for a straightforward read tool, so a 4 is appropriate.

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 description for the single parameter `uri` already includes a concrete example and instruction to get URIs from `skills_list_tool`. With 100% schema coverage, the baseline is 3. The tool description adds no additional meaning beyond paraphrasing the schema; it does not compensate further because the schema is already thorough.

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 ('read'), a clear resource ('product skill file'), and the exact input mechanism ('skill:// URI'). It clearly distinguishes itself from sibling tools like skills_list_tool, which lists skills, and the ledger_* family, which handles ledgers. An agent can immediately understand what action this performs.

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 instructs obtaining valid URIs from `skills_list_tool`, which is a sibling tool, thus providing a clear workflow: list first, then read. This is a direct usage guideline. However, it does not explicitly state when not to use this tool, but the referral to the list tool implies a prerequisite sequence that sufficiently routes the agent.

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. It discloses the output structure (entries with URI, name, description, frontmatter, manifest) and hints at a read-only listing operation. However, it doesn't mention pagination, size limits, or whether the manifest is computed on demand, which would be useful for a listing 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?

The description is two sentences, front-loads the purpose, and packs the output details into a compact list. Every sentence earns its place, and the pointer to read_skill is a useful routing hint without extra 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 zero-parameter listing tool with an output schema, the description is nearly complete. It explains what each entry contains and how to proceed to read a body. It could mention whether the list is sorted or whether it includes all skills, but these are minor gaps given the output schema exists.

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 burden. The description fully explains what the tool returns, which is the only relevant semantic content. Baseline 4 is appropriate for a no-parameter tool.

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 lists this product's skills and enumerates exactly what each entry contains (SKILL.md URI, name, description, verbatim frontmatter, sha256 manifest). It also distinguishes itself from the sibling read_skill by pointing to it for reading a body.

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 this is the listing tool and directs users to read_skill for body content, giving a clear alternative. It doesn't explicitly state when not to use it, but the context is sufficient for an agent to select it for listing versus reading.

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