RCO Records - Record of Cleared Orders

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

Adds real context annotations do not carry: the Bearer <customer key> auth requirement and the exact contents of the returned statement, plus that a signature is issued by Allooloo. However, annotations declare readOnlyHint=false and idempotentHint=false, and the description never explains what non-read-only behavior occurs (e.g., whether issuing a statement consumes state or why repeated calls are not idempotent).

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 packs purpose, input formats, return contents, and auth with essentially no filler. It is long but dense; the parenthetical format notes are placed where they are needed.

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 0% schema description coverage, the description compensates by enumerating returned fields and the auth header. Remaining gaps are defaults for the optional parameters and the behavior behind the non-read-only/non-idempotent hints, which one more clause could close.

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 parameter burden, and it does: month format YYYY-MM, from/to format YYYY-MM-DD, and the non-obvious detail that 'to' is exclusive. It does not state whether the modes are mutually exclusive or what happens if none are supplied (all params optional).

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

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

States a concrete resource and scope: a signed statement over the caller's slice for a month or a date range, and enumerates exactly what the statement contains (count, seq bounds, digest, chain tip, Ed25519 signature). It is distinguishable from list_receipts/verify_receipt/write_receipt, though it never explicitly routes away from 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?

It implies usage by presenting two mutually acceptable input modes (month YYYY-MM, or from/to with to exclusive), which tells an agent how to parameterize the call. It gives no when-to-use vs when-not guidance and no mention of the sibling tools, so the choice of this tool over list_receipts/verify_receipt is left implicit.

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=false, so the agent knows this is a mutation; the description adds real value beyond them by specifying the Bearer auth requirement, the read-only scope of the resulting key, and the critical one-time-only return of the key value. It does not mention expiry or revocation, which would complete the picture.

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 compact sentences, front-loaded with purpose, then auth, then the one-time return caveat. Nothing repeats the title or wastes tokens.

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, the description correctly volunteers that the key value is returned once, which is the most important return-value fact. The remaining gap is the unexplained 'name' parameter, the only input the caller must supply.

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 single parameter 'name' has 0% schema description coverage and the description never mentions it at all — it does not say whether the name labels the auditor, the key, or is required. With a low-coverage schema the description must compensate, and here it does not.

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 ('issue a read-only sub-key'), names the scope ('on your own slice'), the recipient, and the exact capability set. An agent can distinguish it from list_receipts/get_statement/write_receipt without opening any schema.

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

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

Clear context for when to use it — provisioning an auditor with a restricted key — and the permission ceiling is spelled out. No explicit exclusion such as an alternative provisioning path, but the intended usage is unambiguous.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond annotations: results are restricted to the caller's own customer key, Bearer auth is required, and requests without a key are refused.

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 compact sentences and front-loads the ownership scope before the operational details. Every clause—range modes, date format, limit cap, and auth requirement—carries useful 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?

For a six-parameter read-only list tool with no output schema, the description covers scope, both filter families, auth, and the limit cap. Return shape/ordering and default limit are not stated, but annotations and the tool name make the read operation sufficiently clear.

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 six optional parameters, so the description must carry the burden. It documents from/to as YYYY-MM-DD with inclusive to, limit capped at 500, and groups from_seq/to_seq/after_seq as seq-range parameters; after_seq cursor semantics and defaults remain somewhat implicit.

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 (list receipts) and scopes it to rows whose caller is the customer key. It does not explicitly name sibling tools or contrast with get_statement/verify_receipt, so sibling differentiation is implied rather than stated.

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 two filtering modes (seq range or date range), the limit ≤ 500, and the Bearer auth requirement. However, it does not say when to choose seq versus date filtering, nor name alternatives such as get_statement or verify_receipt, leaving tool selection partly inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: the call is unauthenticated ('Public.') and it returns both the verification result and the checking public key. No rate limits or error behavior, so not 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?

A single dense sentence that front-loads the action and return payload, with no filler; the one-word 'Public.' earns its place as an auth signal.

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, the description takes on the burden of describing return values and does so (hash, id, signature, JWK). Authentication is covered; only error/not-found behavior is absent, which is minor here.

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 the mapping the schema lacks: 'rco:… for v1, dec_… for v0', telling the agent which id prefix corresponds to which receipt version.

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

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

States a specific verb and resource (return one receipt by id) and enumerates what comes back (verification result fields plus the JWK). The singular 'one receipt' implicitly separates it from list_receipts, though no sibling is named 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?

The id-prefix hints and the trailing 'Public.' imply when this tool applies and that no auth is needed, but there is no explicit when-to-use statement or comparison to list_receipts/search alternatives.

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?

Goes meaningfully beyond the annotations: annotations only declare idempotent/non-destructive/non-readOnly, while the description adds the Bearer writer-token auth requirement, the exact idempotency key tuple, and what is returned. It omits failure modes (what happens on a duplicate or a rejected token), so not 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 short sentences, all front-loaded and load-bearing: purpose, auth, idempotency key, return. No filler or restatement of the tool name beyond the necessary scope statement.

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?

Auth and idempotency are well covered and annotations carry the safety profile, but there is no output schema and 'Returns the receipt' does not describe the returned shape or key fields. For an 8-parameter mutation with an open-ended subject_type, that leaves a real gap for an agent that needs to chain verify_receipt afterwards.

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 already 100%, so the baseline is 3, but the description adds genuinely new semantics by enumerating which fields compose the idempotency key (writer, subject, subject_type, market, rule_version, cleared_at, answer_hash), which the schema does not state. 'writer' is also mapped to the token implicitly, though caller/caller_key interplay is left to 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 a specific verb and resource — 'Write one v1 receipt for a read a gate has cleared' — which clearly distinguishes a write from the sibling reads/verifications (list_receipts, verify_receipt, get_statement). It does not explicitly name those siblings, and 'v1 receipt' / 'gate' assume domain familiarity, 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?

The phrase 'for a read a gate has cleared' implies a precondition for use, and the auth header requirement is stated, but there is no explicit when-to-use guidance, no mention of when not to write a receipt, and no routing versus verify_receipt or list_receipts.

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