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

Goes well beyond the annotations by disclosing auth requirements (no API key), data scope (public only), an active verification step against poaw-keys.json with an explicit verifies/not result, and the precise limitation of what is not checked (no extension/consistency verification). This is exactly the kind of behavioral detail annotations alone cannot convey.

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-loads the return payload, then adds auth and verification caveats in a tight sequence. Slightly dense with a long first sentence listing many fields, but every clause (no API key, verification source, consistency-proof caveat) 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?

With no output schema, the description carries the full burden of explaining return values and does so field by field, including the conditional anchor. It also states the verification outcome, leaving no ambiguity about what a caller receives or what it does not guarantee.

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?

Zero parameters, so per the rubric the baseline is 4. The description correctly describes a no-argument call and spends its words on return content instead, which is the right trade-off.

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 ('Returns the signed tree head of QED Proof's public Merkle log') and enumerates the exact payload fields: log id, tree_size, root hash, issued time, Ed25519 signature, and on-chain anchor. An agent immediately knows this is a read of the log's signed head, distinct from receipt/verdict/claim tools.

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?

Clarifies context well: no API key needed, public data only, and the anchor is 'the latest on-chain anchor ... when one has landed.' It also draws a boundary against a consistency-proof check ('It checks the head's signature, not that the head extends an earlier one'), though it doesn't name a sibling tool that performs that check.

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 provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context by stating what is included and what is explicitly excluded ('never content'), that receipts are public, and that a shareable link is returned – details not captured in 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?

Two focused sentences with no fluff; the primary return content is listed first, followed by the public-access and link feature. Every phrase contributes meaningful 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 single-parameter read-only tool with no output schema, the description thoroughly enumerates the expected return payload and the sharing behavior. No essential detail needed for correct invocation 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 100% and the parameter receipt_id is clearly explained in the schema as coming from get_verdict or submit_claim. The description does not add additional parameter semantics beyond what the schema provides, so a baseline of 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?

Description states 'Returns the full signed receipt for a receipt_id' with a specific resource and verb, enumerating the exact contents (claim, facts/fingerprints, verdict, signature, proof). It clearly differentiates from sibling verify_receipt by describing a complete receipt with log inclusion/anchor proof rather than just verification semantics.

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 context (receipt_id comes from get_verdict or submit_claim) and notes receipts are public, implying when it can be called. However, it does not explicitly contrast with verify_receipt or state conditions when another tool should be used instead, leaving selection partially 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 read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: the queued/decided state distinction, inclusion of receipt_id, verdict meanings, and the workspace scoping restriction.

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 convey the return fields, possible states, verdict meanings, and scope restriction without wasted words. Key information is front-loaded.

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 read-only lookup with one parameter and no output schema, the description sufficiently covers what is returned, what the verdicts mean, and the workspace restriction. Nothing critical is missing for an agent to call and interpret the result.

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

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

Schema description coverage is 100% and the single claim_id parameter is already described as the ID returned by submit_claim. The description adds no meaningful parameter details 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 identifies the operation as retrieving a claim's state, verdict, and receipt_id, and enumerates the possible verdict values. It is specific about the resource and scope, though it does not explicitly contrast itself with sibling tools like get_receipt or verify_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 implies this tool is for checking a claim's status or verdict but gives no explicit guidance on when to prefer it over alternatives such as get_receipt or list_claims. The workspace visibility constraint is a limitation, not 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 already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint). The description adds genuinely useful behavioral context beyond that: result ordering, per-claim fields returned, workspace scoping, and the next_cursor pagination contract. No contradiction with annotations; 'Lists' matches readOnlyHint=true.

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 sentences with zero waste: purpose and scope first, then filters, then pagination. Every sentence earns its place and the most decision-relevant information (what the tool lists and returns) is front-loaded.

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 6-parameter, 0-required tool with no output schema, the description covers the essential surface: scope, ordering, returned per-claim fields, filter options, and pagination mechanics. The remaining gaps — the undefined semantics of action and agent_id — are the main reason it isn't a 5, but the rich annotations and clear filter/fetch narrative make it adequate for correct 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?

Schema coverage is only 33% (just limit and cursor have descriptions), so the description must compensate. It does helpfully enumerate the filter set and clarifies state's allowed values (queued or decided) and cursor's role ('Paginate with the returned next_cursor'). However, action and agent_id remain semantically opaque — what actions exist and what agent_id refers to is left undefined.

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 ('Lists claims'), scopes it to the API key's workspace, and adds ordering ('newest first') plus the returned fields (state, verdict, receipt_id). This makes it clearly distinguishable from siblings like get_verdict, get_receipt, and verify_receipt, which operate on single entities, and submit_claim, which creates.

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 filter list and pagination instruction imply the usage context, but the description never explicitly says when to prefer this tool over alternatives or when not to use it. With siblings like get_verdict and get_receipt available, no routing guidance is provided — the agent must infer the boundary between listing and fetching a single entity.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful context beyond those hints by clarifying that mutations happen externally in the QED Proof console and that the list includes live verifier status. There is no contradiction with 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?

Two short sentences, with the core purpose and output front-loaded in the first sentence and the read-only constraint in the second. Every word earns its place, and there is no redundant restating of the title.

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-only listing tool, the description is complete: it states what is listed, the per-item status, and where mutations happen. The annotations cover safety, and no output schema is present, so the description's summary of return content is sufficient.

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 the baseline is 4 per the rubric. There is nothing for the description to add about individual parameters, and it appropriately focuses on the tool's purpose and output instead.

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 ('Lists'), the resource ('destinations the workspace has connected'), and the key output detail ('whether a verifier is live for each'). It also gives concrete examples (GitHub, Slack, X) and clearly marks the operation as read-only, making it easy to distinguish from the mutation-oriented 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?

The description gives clear context: this tool is for viewing connections and their verifier status, not for changing them. It explicitly says connecting or disconnecting happens in the QED Proof console, not here. It does not name a sibling tool as an alternative, but the when-not-to-use guidance is explicit.

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?

The description goes well beyond the annotations. It discloses idempotency behavior ('Resubmitting with the same client_claim_id returns the existing claim'), permanence of receipts ('target and params are copied into the receipt, which is public and permanent'), parameter size limits ('params are limited to 4 KB'), handling of unsupported actions ('decided as unverifiable (reason unsupported_action)'), and the conditional return of verdict inline versus queued. This is rich behavioral context that annotations alone (readOnlyHint=false, idempotentHint=false) do not provide.

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 long but every section earns its place. It opens with the core purpose, then explains the return flow, and devotes a structured list to documented actions. It could arguably be trimmed, but the length is justified by the need to cover multiple action profiles. Front-loading the purpose and key behaviors helps an agent quickly grasp the tool's role.

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 complex tool with 6 parameters, nested objects, no output schema, and multiple action profiles, the description is comprehensive. It explains return values (claim_id, verdict, receipt_id, state), idempotency, permanent receipt implications, unsupported action handling, and target/param formats. Nothing an agent needs to correctly invoke the tool 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 substantial meaning beyond the schema. It documents each supported action with exact target formats (e.g., slack://<team_id>/<channel_id>, @handle) and parameter constraints (sha as 40 lowercase hex, ts regex, text_sha256). It also explains the purpose of client_claim_id for idempotency and the 4 KB limit on params. This is far more than the schema provides.

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: 'Records that an agent says it performed an action, so QED Proof can check the destination and issue a signed receipt.' It clearly distinguishes this from siblings like get_verdict (which retrieves outcomes later) and get_receipt (which presumably retrieves receipts). The purpose is unambiguous and action-oriented.

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 when to use this tool: when an agent has performed an action and wants verification. It explicitly notes that if the check does not finish inline, state is 'queued' and get_verdict returns the outcome later, which guides the agent to the sibling tool. However, it does not explicitly state 'use this tool instead of X' or list exclusions; the guidance is inferred from the flow description rather than stated as a rule.

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 far beyond the readOnly/idempotent annotations by disclosing what the checker does and does not do: no blockchain read, on-chain anchor reported as not checked, achieved trust level at most 1, change entries signed under their own domain with null verdict, and keys sourced from keys_json or the issuer's published poaw-keys.json. These are exactly the operational facts an agent 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?

Front-loaded with the core purpose, then proceeds through the checklist and the parameter routing. The long enumerated sentence is dense but every clause carries a distinct behavioral fact; no filler sentences.

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 responsibly characterizes the report (entry_kind "change", null verdict, not_checked results, capped trust level), and it covers the offline-vs-fetch input paths and the key source. 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%, so the baseline is 3, but the description adds real meaning over the schema: the pipeline document here is the policy-check input, keys_json falls back to poaw-keys.json when omitted, and receipt_json may be either a receipt or a change entry. It adds value rather than restating field 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?

States a specific verb (verify/check) and a specific resource (a receipt or change entry), plus the crucial scope distinction 'independently of QED Proof's servers'. An agent can immediately tell this apart from get_receipt or get_verdict, which are server-side lookups.

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: pass receipt_json for a fully offline check, or receipt_id to fetch the receipt first, and says the policy check is skipped (not_checked) when no pipeline is supplied. It lacks an explicit pointer to sibling tools (e.g. use get_receipt instead when you only want the stored record), so 4 rather than 5.

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