Datoka Agent

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds a genuinely important security caveat not present in the structured data: the operator must establish trust in this issuer out-of-band, meaning the returned keys cannot be self-validating.

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

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

Two short sentences, front-loading the action before the caveat, with no filler. Every sentence carries information the caller needs.

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 read tool with an output schema, the description need not explain return values, and the trust caveat covers the main non-obvious concern. The only gap is the absence of any hint about how the keys relate to the verify/prepare receipt workflow.

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 adds nothing parameter-related, but nothing is required since there are no inputs to disambiguate.

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 ("Return") and resource ("public keys of this issuer"), which clearly separates it from the sibling tools that issue, prepare, and verify receipts. It is clear what the tool does, though it does not explicitly name or contrast itself with those 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?

There is no guidance on when to call this tool versus verify_agent_receipt or the other siblings, and no workflow context (e.g., fetch keys before verifying). The trust note hints at a precondition but is framed as a warning rather than usage direction.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds material context beyond them: a real per-call cost (0.002 USDC via x402), retry semantics that require re-sending the same idempotencyKey and payment authorization, and an explicit epistemic caveat that signed declarations do not independently prove execution. It does not describe persistence failure modes or what the stored receipt looks like.

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 short sentences with zero filler; the purpose is front-loaded and each subsequent sentence (price, retry rule, disclaimer) adds a distinct fact an agent needs.

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

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

An output schema exists, so return values need not be explained, and the description covers cost, idempotency, and the trust caveat. What is missing is guidance on the relationship to the sibling prepare/verify tools, which matters for a tool in a multi-step receipt flow.

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% with two parameters, one of which is a deeply nested required event object, so the description carries the burden. It names both parameters and gives genuine semantic value for idempotencyKey (retry preservation), but says nothing about the meaning of the event fields or what a well-formed declaration contains.

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: 'Persist a signed execution declaration receipt.' An agent can tell this tool writes a receipt, but the description never differentiates it from the siblings prepare_agent_event and verify_agent_receipt, so the boundary between issuing and verifying is left to inference.

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. 'Preserve event, idempotencyKey and payment authorization on retries' is a useful operational instruction, but the description never says when to call this tool versus prepare_agent_event or verify_agent_receipt, nor does it state any prerequisite (e.g. that a receipt must be prepared first).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely non-redundant trait beyond the annotations: validation is a pure computation that does not persist anything ("Does not create a receipt"), which tells the agent this call has no lasting side effect. It omits failure semantics and what happens when validation rejects the event.

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

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

Two short sentences, front-loaded with the positive action and followed by the exclusion. No filler, no restatement of the tool name, and every clause carries information.

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 and the computed commitment need no explanation in the description, and the description covers the core purpose plus the persistence boundary. The remaining gap is behavioral on the input side: nothing explains what constitutes an invalid declaration or how validation failure is surfaced, which matters given the deeply nested required object.

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

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

There is one nested, fully required, heavily constrained event object, and schema description coverage is 0% – the schema enforces shape through patterns and consts but explains nothing about field meaning. The description refers only to an "agent execution declaration" and commitment, adding no guidance on the required fields (version, hashes, timestamps, outcome), so it does not compensate 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 names specific operations (validate a declaration, compute its commitment) on a specific resource (agent execution event), which is clearer than the tool name alone. It also partially distinguishes itself from siblings by negating issue_agent_receipt's behavior. It stops short of naming the sibling it complements directly, so it is a strong 4 rather than 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?

"Does not create a receipt" implies the boundary with issue_agent_receipt, and "prepare" implies a pre-step, but the description never states when an agent should call this instead of going straight to issue_agent_receipt or verify_agent_receipt. Usage must be inferred from the negation rather than being spelled out.

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, non-destructive and closed-world, so the safety profile is covered. The description contributes one genuinely useful semantic limitation — 'A valid signature does not independently prove the action occurred' — but says nothing about key resolution, chain/previous linkage, or failure modes, which matter for a verification 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?

Two short sentences with the action front-loaded and no wasted filler. The caveat sentence pulls its weight by conveying a non-obvious trust limitation, though the overall body is arguably too sparse for the complexity of the payload.

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 annotations cover the safety profile. Still, for a verification tool with a large nested input contract, the description omits prerequisites (trusted keys), what 'verify' entails, and how a negative result should be interpreted — modest but real 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 0% across two deeply nested required objects, so the description carries the full burden and largely fails: 'declaration' and 'trusted Datoka receipt' are never mapped to the 'event' and 'receipt' parameters, and no field-level meaning (hash algorithms, sequence/previous chaining, signature encoding) is explained.

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

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

States a specific verb ('Verify') and the resource it operates on ('the declaration against a trusted Datoka receipt'), which is enough for an agent to know this is a cryptographic attestation check rather than an issuance tool. It does not, however, name or contrast itself with the sibling issue_agent_receipt/get_agent_public_keys, and the term 'declaration' is never tied back to the 'event' parameter, leaving a small ambiguity.

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, no prerequisite (e.g., that the trusted public key must first be obtained), and no exclusion of alternatives. The second sentence is an interpretive caveat rather than routing guidance, so the agent must infer the context entirely.

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