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 (readOnlyHint, idempotentHint, destructiveHint=false) already cover the safety profile. The description adds useful behavioral context: the tool returns documentation as markdown and enumerates the covered topics summarises the input schema's fallback behavior. 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?

One tightly-scoped sentence that is front-loaded ('Self-serve documentation') and groups related content with a dash. every phrase earns its place; no filler or repetition.

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 a single optional parameter with full schema coverage, a read-only/idempotent annotation, and an output schema, the description covers the tool's scope and output format sufficiently. The fallback behavior for invalid topics is captured in the schema, completing the picture.

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% – single parameter `topic` with allowed values and fallback behavior fully described. The tool description only restates the topic areas already in the enum, adding no 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?

States the action (self-serve documentation), the resource (AgentLedger API), the topics covered, and the output format (markdown). This distinguishes it clearly from siblings like ledger_alerts or ledger_set_budget without needing to inspect their 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?

The description makes the usage context clear: fetch AgentLedger API docs. It doesn't explicitly name alternatives or exclusions (e.g., 'for alerts, use ledger_alerts'), but no sibling competes for this purpose, so an agent can infer when to use it. The `topic` parameter adds more granular guidance in the schema.

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?

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?

Annotations only flag destructive=true and idempotent=true; the description goes well beyond by disclosing the 80% warning, the hard block enforced through ledger_track, that an existing budget is overwritten, and the first-call workspace_key → agent_secret mint-once handshake. This is exactly the behavioral context structured fields 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 and the enforcement rule, then layered auth and cap-dimension details. Every sentence carries information, though the line-broken paragraphs are slightly denser than needed for 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?

For a 7-parameter mutating tool with an output schema, the description covers the destructive overwrite, the auth handshake, and the two-dimensional cap model, so nothing critical an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the dollar-vs-token cap independence, the rail="tokens" coverage semantics, the monthly-required / 0-means-no-limit convention, and the workspace_key/agent_secret lifecycle. That is real added value over the terse property descriptions.

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?

"Set spending caps for an agent" is a specific verb+resource, and the description clarifies scope (dollar vs token caps, monthly required) so an agent can distinguish this from ledger_track or ledger_report. It never names an alternative sibling to route against, which keeps it just 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 rather than stated: it explains that dollar and token caps are independent and "Set both if the agent uses both," and that ledger_track calls crossing the cap are rejected. There is no explicit "use this when / use X instead" routing against the six sibling tools.

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 readOnlyHint=false, idempotentHint=false, etc., which tell little. The description adds critical behavioral context: the workspace_key is shown exactly once and cannot be re-revealed, the first ledger_track returns the agent_secret, minting is rate-limited per caller IP, and free tier caps at 3 agents. 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 longer than most but every sentence carries essential onboarding information: no credentials, one-time key, first-write secret, rate limits, free tier cap, and paid alternative. It is front-loaded with the core purpose and next steps, though the paid-path paragraph could be trimmed without losing the tool's primary guidance.

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?

Despite having an output schema, the description provides crucial lifecycle context that the schema alone would not convey: the one-time display of workspace_key, how it connects to the first ledger_track call, and the resulting agent_secret. It covers prerequisites, next steps, limits, and alternative billing—comprehensive for a zero-argument setup tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description reinforces this by stating 'Takes NO arguments on purpose' and explains why, which is useful guidance even though there is no schema to clarify.

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: 'Get a FREE AgentLedger workspace with no credential and no arguments.' It clearly distinguishes this tool from siblings by positioning it as the entry point that every other ledger_* tool depends on, since all others require workspace_key or agent_secret.

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 instructs when to use: 'Call this FIRST if you have no credentials yet.' It names the alternatives (ledger_track, ledger_set_budget, ledger_report, ledger_alerts) and explains why they cannot be used without credentials, plus mentions the paid alternative via POST /v1/billing/x402. No ambiguity remains.

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 cover write/safety hints; the description adds rich behavioral context beyond that: secret-minting on first claim, rejection of unauthenticated later writes, the $100,000 cap and >=0 constraint, and the crucial fact that budget-crossing entries are blocked, not just logged. This is exactly the extra context annotations can't 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 groups auth, limits, and token guidance. There's some line-wrap noise and the x402/start detail is dense, but every sentence carries operational meaning.

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

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

For a 9-param, 4-required mutation tool with an output schema, the description covers the auth lifecycle, limits, and blocking behavior that an agent must know before calling. Return-value shape is 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, but the description adds cross-parameter workflow semantics the schema can't express: when workspace_key applies vs agent_secret, and the mandate to send tokens_in/tokens_out+model together. Enum values for rail are only in the schema, not the description.

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 (record a spend entry) and resource (agent spend on any payment rail), with the optional token dimension called out. It's clearly distinct from siblings like ledger_report or 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 clear conditional guidance for when to pass workspace_key vs agent_secret, and instructs to include token counts on every LLM call. It doesn't explicitly name sibling alternatives (e.g., ledger_set_budget for caps), but the in-tool branching is well explained.

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.