satledger timestamp receipt

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

With no annotations, the description carries the full behavioral burden and does well: it discloses an external dependency (public RFC 3161 TSA), a cost of 100 units, idempotent behavior for unchanged state, and the authentication channel. It does not cover failure modes, rate limits, or the return shape, keeping it short of 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?

Four sentences, purpose front-loaded, and the cost and auth facts each carry real information. Slightly rhetorical phrasing ('the one fact here the operator cannot manufacture') adds words without adding much operational content, but overall it is tight.

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 no annotations and no output schema, the description covers mechanism, external dependency, cost, idempotency, and authentication. What is missing (return format, error/permission failures) is relatively minor given the tool's straightforward single-effect action.

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 50%. The api_key parameter is already fully documented in the schema (including the 'prefer _meta' guidance), so the description's auth sentence largely duplicates it, and the required agent_id parameter has no explicit semantic explanation in either place. Marginal added value, 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 states a specific verb and resource ('sign the agent's current state' via an RFC 3161 Time-Stamp Authority), which is concrete and not a restatement of the title. It never names or contrasts with the closest siblings (timestamp_receipt, list_anchors), so differentiation is left to inference, but the mechanism described 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?

Usage is only implied: the cost ('Costs 100 units') and the idempotency note ('an unchanged state returns the anchor it already has') help the agent decide whether to call, but there is no explicit when/when-not guidance and no alternative tool is named. Adequate but leaves the agent to infer comparison against siblings like timestamp_receipt.

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

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

With no annotations, the description carries the full burden and does well: it discloses the signed/hash-chained ledger nature, that credits go to the workspace issuer rather than the agent, a 1-unit cost, and the auth requirement (workspace key via _meta[satledger/api-key]). It omits edge behavior such as duplicate agent_id handling or reversibility, keeping it short of 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?

Four compact sentences, each carrying distinct information: purpose and ledger nature, credits semantics plus sibling routing, cost, and auth. The purpose is front-loaded and there is 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?

For a 4-param mutation tool with no annotations and no output schema, the description covers auth, cost, credit semantics, and the immutability profile. It does not describe the return value or uniqueness constraints on agent_id, but nothing essential to invoking 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 description coverage is 25%, with only api_key documented in the schema. The description adds genuine meaning for initial_credits (mints to the workspace issuer, not the agent), but agent_id and display_name get no explanation, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Create an agent in your workspace') and immediately characterizes the resulting object as 'a named ledger whose every event is ed25519-signed and hash-chained.' It also names the sibling it is not (fund_agent), so an agent can distinguish it 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?

Explicitly routes the agent: credits are minted to the workspace issuer, and 'fund_agent moves credits across when you need usage metering,' naming both the alternative and the condition selecting it. It also flags the 1-unit cost. No explicit when-not-to-use case, so not a full 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 no annotations, the description carries the full burden and does contribute real behavioral context: it is a read of current state, it is free of charge, and it states the auth mechanism via _meta[satledger/api-key]. It does not state read-only/reversibility, error behavior for unknown agent ids, or rate limits, so the disclosure is partial.

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 terse fragments, front-loaded with the return contents, then cost and auth. Nothing is wasted, though the sentence-fragment style leaves the subject/verb implicit.

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?

With no output schema and no annotations, the description usefully compensates by enumerating the returned fields and noting the tool is free and authenticated. It still omits agent_id semantics and any failure/edge-case behavior, so it is adequate but not complete for a 2-parameter tool.

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

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

Schema coverage is 50%: api_key is documented in the schema while agent_id is not. The description's auth sentence maps to api_key but largely repeats what the schema already says, and it adds nothing about agent_id's format or role. Baseline 3 is appropriate given partial schema coverage.

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 concrete contents of the agent state snapshot (root id, state hash, event count, balance), which together with the name describe_agent makes the operation clear: read the current state of one agent. It does not explicitly differentiate from siblings like list_agents or workspace_balance, but the returned-field list is specific enough to separate it from them.

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?

'Free' implies a cost-based reason to prefer this over paid siblings (record_action, fund_agent), but there is no explicit when-to-use or when-not guidance and no named alternative. An agent must infer the use case entirely from the tool name.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the auth mechanism (workspace key via _meta[satledger/api-key] or X-API-Key), the transport, that the operation is free and permanent, and that verification runs customer-side. It does not address idempotency, side effects, or limits on bundle size, keeping it short of 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?

The text is dense and front-loaded with the action, the return content, and the auth requirement in the first two sentences. Minor redundancy: 'free' appears in the first sentence and again as 'Free, permanently.' The telegraphic style is efficient overall.

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?

There is no output schema, so the description must describe returns, and it does: a summary plus the archive URL. It also covers authentication, cost, and the meaning of the optional expectation parameters. Given four parameters and no annotations, this is nearly complete, missing only edge-case behavior such as failure modes or bundle size.

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 only 25% (only api_key is documented in the schema), so the description must compensate. It supplies the rationale and source for expect_action_head/expect_action_count ('from state YOU kept to check completeness'), which the bare schema does not convey, and echoes the api_key auth path. agent_id is left unexplained, though its meaning is self-evident.

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 specific verbs and resources: build the export bundle, run the customer-side verifier, and return the summary plus archive URL. This is unambiguous and clearly distinct from siblings like list_agents or record_action, though it never explicitly names an alternative tool. Purpose is clear without sibling routing.

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 gives operational guidance on one parameter (pass expect_action_head/expect_action_count from state you kept, to check completeness), which implies the tool's use case is post-hoc verification of an agent's action history. However, there is no explicit when-to-use vs when-not-to-use guidance and no named alternative among the 13 siblings. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a credit-moving mutation, that it costs 1 unit, and that authentication uses the workspace key in _meta. It does not explain failure modes, reversibility, permission requirements, or what happens if the workspace balance is insufficient.

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 tightly written sentences, front-loaded with the core action and followed by cost and authentication. Every sentence earns its place with 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?

For a financial mutation tool with no output schema and no annotations, the description covers purpose, cost, and auth but omits important context such as balance requirements, failure behavior, and output expectations. It is adequate but not fully complete.

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 only 33%, so the description must compensate, but it largely repeats the api_key authentication detail already present in the schema. It adds no meaningful guidance for agent_id or amount beyond what the schema's pattern and minimum already provide.

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: 'Move credits from the workspace issuer to an agent's own account.' It also explains the downstream purpose ('so record_usage can burn them'), which distinguishes it from sibling credit tools like top_up_workspace and record_usage.

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

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

The description gives clear context for when to use it by linking the operation to record_usage burning credits, and it notes the cost of 1 unit. It does not explicitly name alternatives or state when not to use it, but the intended use case is clear.

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

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

With no annotations, the description carries the full burden, and it does disclose two meaningful traits: the call is free and it requires the workspace key via _meta[satledger/api-key]. However, it says nothing about ordering, pagination, result size limits, or what the 'head hash' represents, which are real gaps for an unpaginated-looking list 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?

Three short, front-loaded sentences with no filler: what it returns, what it costs, how to authenticate. Slight inefficiency in repeating the _meta auth detail already present in the schema, but overall tight.

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 two-parameter list tool with no output schema and no annotations, the definition covers authentication and cost but leaves the return shape mostly unexplained beyond 'action log' and 'head hash'. An agent knows how to call it, but not what it will get back or whether results are complete/paginated.

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 50%: api_key is documented in the schema (including the _meta preference), and the description's auth sentence largely restates that rather than adding new meaning. The required agent_id has no description anywhere, so half the parameters remain unexplained; the description neither compensates nor misleads.

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

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

The description identifies a specific resource (the agent's action log) and an extra piece of returned data (its head hash), which is enough to separate it from write-side siblings like record_action. It stops short of naming an alternative or stating the listing scope (all actions? recent?), so it is clear but not fully differentiated from siblings such as list_anchors.

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

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

There is no when-to-use guidance: nothing says whether this should be called before/after record_action, whether it is the right tool versus list_anchors, or any precondition beyond authentication. The only contextual hint is the cost note ('Free'), which is useful but not usage 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?

With no annotations, the description carries the full load and does disclose two behavioral traits: it costs nothing ('Free') and it requires authentication via _meta[satledger/api-key]. It stops short of describing pagination or result ordering, which matters for an unbounded list.

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 fragments, front-loaded with scope, then cost, then auth. Every sentence carries distinct information with no padding.

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

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

For a simple zero-required-parameter read tool with no output schema, the description covers scope, cost, and auth. The only real omission is pagination/return-size behavior for a potentially large listing.

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 optional api_key parameter is fully documented in the schema, including the preference for _meta. The description's auth sentence reinforces but adds no syntax or fallback detail beyond the schema, 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?

The description names the resource and scope ('Every agent in your workspace'), which clearly implies a full-list operation and contrasts with singular siblings like describe_agent and create_agent. It never states the verb explicitly, but the intent 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?

Usage is implied by the scope ('every agent'), but there is no explicit when-to-use guidance or routing to alternatives such as describe_agent for per-agent detail. The 'Free' note hints at cost considerations but does not frame selection.

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

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

With no annotations, the description carries the full burden. It does disclose two genuinely useful behaviors – the call is free and it requires workspace-key authentication via _meta[satledger/api-key] – but says nothing about read-only safety, result volume, or pagination behavior for what looks like an unbounded list.

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 with no filler, and the first sentence front-loads what the tool returns. The opening fragment lacks a verb, which slightly blunts immediate comprehension, but nothing is 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?

For a two-parameter read tool with no output schema and no annotations, the description covers purpose, cost, and auth, which is the minimum viable set. It leaves gaps on ordering, result limits, and whether an unrecognized agent_id fails or returns empty.

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 50%: api_key is documented in the schema, agent_id only has a pattern. The description reinforces the auth mechanism and implicitly defines agent_id as the agent whose commitments are listed, which partially compensates but adds little beyond the schema text.

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 the resource precisely – every anchor commitment recorded for a given agent – which reads clearly as a retrieval operation. It does not explicitly contrast itself with the sibling anchor_agent (which presumably creates anchors), so an agent must infer the read-vs-write split.

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: call this to retrieve an agent's anchor commitments. The 'Free' note is a useful selection hint, but no alternatives are named and no when-not condition is given, so the agent gets context without explicit 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?

With no annotations, the description carries the full burden and does substantial work: it discloses the payment rail (x402 via _meta[x402/payment]), exact prices and unit tiers, a 10,000-unit free allowance, that the API key is returned only once, and that subsequent ledger calls are HTTP authenticated with that key. It omits failure/refund behavior and idempotency, keeping it short of 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?

Front-loaded with the core action and the value proposition, then payment, pricing, and return behavior in a tight sequence. It is dense and slightly packed but nearly every clause is load-bearing, with little 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 0 parameters, no annotations, and no output schema, the description covers the essentials an agent needs: what is bought, how to pay, cost, what is returned, and how the returned key is used. It would be more complete with error/retry guidance, but nothing critical 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 input schema is empty (0 params), so baseline is 4. The description goes further by documenting the out-of-schema payment payload in _meta[x402/payment] and the two selectable tiers (0.50 USDC/2,500 units, 15.00 USDC/100,000 units), giving the agent the effective selection semantics the schema cannot express.

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 ("Buy a workspace") and immediately defines what a workspace is: a tamper-evident signed/hash-chained ledger with offline-verifiable export. The purchasing framing separates it from top_up_workspace and timestamp_receipt, which deal with units and receipts rather than provisioning.

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 initial purchase step ("Returns an API key once, plus the next calls to make"), which hints it precedes top_up_workspace. However, it never explicitly states when to choose this tool over top_up_workspace or timestamp_receipt, so the routing is left 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?

With no annotations, the description carries the full behavioral burden and does well: it discloses that entries are signed and hash-chained, that each call costs 1 unit, and that authentication uses the workspace key via _meta[satledger/api-key]. It stops short of describing failure modes, idempotency, or what the append returns.

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, then adds cost and auth in short sentences. 'This is the thing the workspace is for' is more motivational than informational, but overall it is tight and wastes little 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 core write tool with no annotations and no output schema, the description covers the essential behavioral facts (append, signing, cost, auth). However, it does not explain what the call returns, how failures are surfaced, or provide guidance on the required agent_id and kind parameters, leaving meaningful gaps.

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 50%, with kind and agent_id undocumented in the schema. The description adds examples for kind ('a tool call, a decision, a message') but says nothing about agent_id format, detail contents, or the fallback api_key argument beyond what the schema already states. It compensates only partially for the coverage gap.

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

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

The description states a specific verb and resource: 'Append what an agent did ... as a signed, hash-chained entry,' and gives concrete examples (tool call, decision, message). This clearly distinguishes the tool from read-oriented siblings like list_actions, but it never names an alternative or explicitly contrasts itself with record_usage or timestamp_receipt.

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 implied usage context ('Append what an agent did' plus examples) and mentions a cost and auth requirement, but it provides no guidance on when not to use this tool or which sibling to choose instead. The agent must infer that list_actions is for reading and record_usage for usage metrics.

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

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

With no annotations, the description carries the full burden, and it does disclose the mutation ('burn credits'), the cost (1 unit), and the auth mechanism (_meta workspace key). However, it omits critical traits for a billing operation: idempotency/retry behavior, reversibility, and failure modes, which matter greatly since a retried call could double-burn credits.

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

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

Three tight sentences with the core action front-loaded and no filler. The one weak spot is 'costs 1 unit,' which is terse but adds confusion rather than clarity given the amount parameter.

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 description covers purpose, cost, and authentication, which is a reasonable baseline for a 3-param tool. But with no annotations and no output schema, it should also address idempotency and what a successful ledger write returns, both of which are missing for a credit-consuming mutation.

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 only 33%, so the description should compensate but largely does not. It explains the auth channel but leaves agent_id and amount unexplained; worse, 'costs 1 unit' sits ambiguously against a required 'amount' parameter, potentially confusing the agent about what amount controls.

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: burning credits from an agent's account as a signed ledger event. This is a concrete, distinct operation, but the description never explicitly distinguishes it from siblings like record_action or fund_agent, so an agent must infer the difference.

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

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

It gives no when-to-use or when-not-to-use guidance and never names an alternative. The only contextual cue is 'costs 1 unit,' which hints at a metering scenario but does not route the agent among the many 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?

With no annotations, the description carries the full burden and does so richly: 3 free calls per day, 0.05 USDC per single / 0.50 for up to 10, x402 payment, no account, and 'nothing stored here afterwards'. It also discloses the trust model (verifiable without contacting the service), which an agent cannot infer from the schema.

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

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

Front-loaded with the core action and effect in the first sentence, then pricing and trust details in short clauses. It is long, but nearly every clause carries information an agent needs (cost, batching, privacy) rather than 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 2-param tool with no output schema and no annotations, the description covers the action, cost, batching, trust model and data-handling, which is enough to invoke it correctly. It does not describe the exact shape of the returned token/proof, a minor gap given the absence of an 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; the description goes further by clarifying that the caller must hash locally and that multiple digests are bound to one timestamp via a Merkle root returned per digest. It adds the batch/payment coupling and the oneOf single-vs-array intent beyond the raw pattern constraints.

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 precise verb+resource+mechanism: submit a SHA-256 digest and receive an RFC 3161 Time-Stamp Authority token as existence evidence. It also names the verification property (verifiable against the authority without trusting this service), so an agent knows exactly what it gets back.

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?

Explains the workflow ('hash your data yourself - it never leaves your side') and the cost/free-tier conditions, which tells the agent when a call is warranted and what it costs. There are no sibling tools, so no alternative routing is needed, but it does not explicitly state when *not* to use it.

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, and it delivers a lot: required API key location, required payment header, two concrete price/unit tiers, and the guarantee that 'the units land in that workspace and nothing new is created.' It stops short of stating failure/partial-payment or refund behavior, so not quite 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?

Three tight sentences that front-load the core action before the credential/payment logistics. Minor redundancy exists between the description and schema on the api_key/_meta preference, but every sentence contributes.

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 one-parameter purchase tool with no annotations and no output schema, the description covers the preconditions, the credential and payment headers, the price tiers, and the post-condition on the ledger. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single api_key parameter is already fully documented in the schema, including the '_meta preferred because arguments are logged' guidance. The description's mention of the key largely repeats that, adding only the framing that the key identifies the target workspace. Baseline 3 for a fully covered 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?

Specific verb+resource: 'Add units to a workspace you already hold.' It explicitly differentiates from provision_workspace by stating that buying a workspace 'gives you an empty ledger under a different key.' An agent can distinguish this from all siblings without opening a 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?

States the precondition ('a workspace you already hold'), the credential source (_meta or argument), the payment mechanism, and the exact alternative (buy a workspace instead) with the reason it differs. Nothing about when to pick this vs a sibling is left 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses that the call is free (no unit cost), its authentication requirement via _meta[satledger/api-key], and what it returns. It omits rate limits or whether the cost table is exhaustive, but covers the two behaviors an agent most needs.

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, front-loaded with the return value, then the cost rationale, then auth. No filler and nothing buried.

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?

There is no output schema, so the description correctly takes on the job of explaining what comes back (units remaining and per-operation costs) and how to authenticate. Adequate for a single-optional-parameter read tool, with only minor behavioral gaps.

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 api_key parameter and its _meta preference are already documented in the schema. The description's mention of _meta[satledger/api-key] reinforces the same information rather than adding new semantics, 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 states precisely what the tool returns: remaining units plus the cost of each operation, which is more specific than the title 'Workspace balance'. It implies a read-only balance check, distinguishable from mutation siblings like top_up_workspace or record_usage, though it never names those siblings explicitly.

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

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

'Free, so you can plan before you are refused' gives a clear operating context: call this before spending operations to avoid budget refusal. It stops short of naming alternatives (e.g., top_up_workspace for adding credit), so it is clear context without explicit routing.

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