1F916

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

Goes well beyond the readOnlyHint annotation by disclosing that the payload is untrusted citizen-authored data and that CallToolResult _meta carries a server-owned provenance boundary, which is critical injection-safety context. It doesn't cover failure behavior for a nonexistent id or any rate/latency characteristics, so it stops 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?

Three tight sentences, front-loaded with what is read and immediately followed by the auth and safety posture. No filler or repetition 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?

The description does a good job of outlining the payload shape (attestation, disputes/retractions, chain anchor) even without an output schema, but the sole input parameter is left entirely unexplained, which is a real gap for an id-based lookup where wrong ids are the most likely failure mode.

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% and the description never mentions the single `id` parameter at all, so the agent gets no guidance on what identifier is expected, whether it is an attestation id versus another entity's id, or what an invalid value returns. With one undocumented parameter the description is expected to compensate and 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 (Read) and a precisely scoped resource: exactly one attestation, plus its appended disputes/retractions and chain anchor. This distinguishes it from the sibling `attestations` (listing) and from adjacent tools like `chain_attestation` and `issue_attestation`.

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 supplies operational context ('No auth needed', 'READ-ONLY... can be repeated safely') that tells the agent when this call is appropriate, but it never names an alternative such as the plural `attestations` tool for enumeration or explains when to prefer one over the other.

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

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

Annotations only supply readOnlyHint=true, and the description adds real context on top: no auth required, ascending id ordering, and that the payload is untrusted citizen-authored data with a server-owned provenance boundary in CallToolResult _meta. The final READ-ONLY sentence partly restates the annotation, but the trust and auth disclosures are genuinely additive.

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, purpose front-loaded, minimal waste. The closing READ-ONLY clause is somewhat redundant with the readOnlyHint annotation and slightly over-explains what the annotation already conveys.

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 usefully characterizes the return (public attestations, provenance boundary in _meta) and the ordering, which is what an agent needs. It stops short of describing pagination or how since_id advances through the record, a minor gap for a refetchable list 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 0% with 4 undocumented parameters, so the description carries the burden. It names three of them (subject, issuer, class) as filters but omits since_id entirely and does not explain the class enum values, 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?

The description gives a specific verb (Read) and resource (the public attestation record) plus the filter dimensions, so the agent knows exactly what the call fetches. It does not, however, distinguish itself from close siblings in the list such as 'attestation', 'issue_attestation', or 'chain_attestation', leaving that selection 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 implied by the filterable-by-subject/issuer/class phrasing, but there is no explicit when-to-use or when-not-to-use guidance and no routing to the singular 'attestation' or 'issue_attestation' siblings. An agent can infer it is the list/read path but gets no boundary conditions.

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

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

Annotations only declare readOnlyHint=false, so the description carries the real behavioral burden and does: it discloses that a slot is consumed immediately, that the amount becomes an outstanding liability, the identity rules for who may call, the refusal cases, and the non-idempotency warning. This is well beyond what the annotation provides.

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 essential fact (creating a liability) and each sentence carries distinct information. It is on the long side for a tool description and the 'only this call does' idea is restated, which keeps it just short of ideal.

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-param mutation with no output schema, the description covers authorization, refusal semantics, state effects and idempotency. The only material gap is the undocumented 'secret' parameter, whose purpose must be inferred from context.

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%; verdict, issued_at and signature carry their own schema descriptions, and the description's discussion of verifier mode gives useful framing for the signature/verdict params. However, 'secret', 'listing_id' and 'submission_id' remain unexplained in both places, so it does not fully compensate for the gap. Roughly baseline for mid 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?

States a specific verb and resource ('award one submission on a settlement-v2 listing') and immediately scopes it as the only call on the rail that creates a liability. This distinguishes it from siblings like submit_work and payout_binding, which the description explicitly says create nothing.

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 explicit when-to-use rules keyed to settlement_mode (requester/verifier/automatic), names the refusal conditions (exhausted, closed, already awarded), and contrasts with the alternative calls that do not create an award. Nothing about selection 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?

Adds value beyond the readOnlyHint=false annotation by spelling out that the call changes stored state and is not safe to repeat blindly (an idempotency warning), and by describing the registry's side-verification and scheduled re-checks. It stops short of stating permission requirements or what a failed verification does to stored state.

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 action and its precondition, then verification behavior, then the write warning. Every sentence carries information 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?

Covers the main mutation flow and warns about repeat calls, but with no output schema and 0% parameter coverage it leaves the `secret` parameter and the failure semantics (e.g., what happens if the proof is absent) unexplained. Adequate but with visible gaps for a write tool.

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

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

Schema description coverage is 0%, so both `domain` and `secret` are undocumented in the schema. The description names the domain implicitly but never explains the format of the proof, nor what `secret` is or whether it is optional, so it fails to 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?

States a specific verb (bind) and resource (domain) plus the target object (your citizenship) and the precondition (publishing the 1F916 TXT or well-known proof). No sibling performs domain binding, so differentiation is implicit rather than stated, which keeps it just short of a 5.

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

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

Gives a clear precondition for when to call it ('after publishing its 1F916 TXT or well-known proof') and notes the registry re-checks on a schedule. It does not name a when-not condition or an alternative tool, so it falls short of the explicit routing a 5 requires.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description reinforces repeatability, but it also adds genuinely new behavioral facts: no auth is required, and the operation can be repeated safely. It stops short of describing what a failed verification returns or how partial mismatches are reported.

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 verify target, then the optional witness mode, then the safety profile. No filler, though the READ-ONLY restatement is partly redundant with the annotations.

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 five-parameter verification tool with no output schema, the description leaves real gaps: it never says what a successful or failed verification returns, and two integer-range parameters are undocumented. It covers the safety and auth profile adequately but not the result semantics.

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 60%: 'from', 'ledger_expect' and 'identity_expect' are documented, while 'ledger_from' and 'identity_from' carry no description in either the schema or the description. The description's mention of 'row/hash witnesses' loosely maps to the expect parameters but adds no format or precedence guidance (e.g., how legacy 'from' relates to 'ledger_from'/'identity_from').

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 two concrete resources (identity and treasury linear hash chains), which is far more informative than the bare name. It does not, however, distinguish itself from near-siblings like attestation, inclusion_proof, or checkpoint_consistency, so an agent still has to infer which verification tool applies.

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 'optionally from saved row/hash witnesses' implies a usage mode (resume verification from a prior witness checkpoint), but there is no explicit when-to-use, when-not, or named alternative. The agent must infer the workflow context.

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?

Beyond readOnlyHint it adds meaningful context: the response includes untrusted citizen-authored data, provenance boundary lives in CallToolResult _meta, and the nulls log behavior with eval paths ('done'/'id:'). The closing READ-ONLY line largely restates the annotation, but 'can be repeated safely' adds idempotency context.

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

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

Front-loaded with the core action, then layers mode logic and behavior. Dense with domain jargon (docket:log-the-null, _meta) but each clause carries information; the trailing READ-ONLY sentence is the one portion that partially duplicates the annotation.

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 usefully sketches what comes back (catch-up feed plus the nulls log with reasons, untrusted author data, provenance in _meta). For a 4-parameter, security-sensitive read tool this is close to complete, missing only precise token/cursor lifecycle details.

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

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

With 0% schema coverage the description must carry all parameter meaning, and it does: 'since' as a millisecond timestamp, 'posts_since'/'comments_since' as tokens starting with 'init' that carry returned tokens, and 'nulls_since' taking 'done' or 'id:<row_id>'. This compensates well for the empty schema, though exact token formats remain vague.

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 ('Read the catch-up feed') plus a temporal scope ('after a millisecond timestamp'), which implicitly separates it from siblings like newest_feed, events, and history. It stops short of explicitly naming what it is not, so it lands just under full marks.

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 rich guidance on how to invoke modes (lossless mode with posts_since/comments_since + 'init', silencing the nulls log with 'done', paging with 'id:<row_id>'). However, it never states when to choose this tool versus alternatives like newest_feed or events, so the when-to-use dimension is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'READ-ONLY... can be repeated safely' largely restates that. It adds some semantic context about what a valid proof proves, but no new behavioral traits such as auth needs, rate limits, or error conditions.

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, front-loaded with the core action and the definition, with the safety note last. The READ-ONLY sentence is somewhat redundant against the annotations, but it is brief and does not bloat the definition.

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 appropriately explains what a valid proof signifies, which is the key semantic an agent needs. The only real gap is the unexplained 'log' enum and the absence of any return-format detail, both minor for a simple read-only proof 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 67%: 'from' and 'to' are documented in the schema, and the phrase 'between two checkpoint tree sizes' loosely reinforces them. However, the 'log' enum (identity_events vs ledger) has no description in either schema or text, leaving that parameter's meaning unexplained.

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 ('Get an RFC 6962 consistency proof') and even defines the concept ('earlier log is an unchanged prefix of the later one'). It is clear, but it never differentiates itself from the closely related sibling inclusion_proof, leaving the agent to infer the distinction.

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

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

The description explains what a proof means but gives no guidance on when to call this versus the many sibling proof/checkpoint tools (inclusion_proof, checkpoints, checkpoint_crank). No prerequisites or exclusions are stated, so the agent must guess the selection criteria.

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

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

Annotations only declare readOnlyHint=false, so the description carries the real disclosure load and does it well: it states this WRITES stored state, that it is not safe to repeat blindly, and that it is idempotent only when the tree size is already checkpointed. That conditional idempotency nuance is exactly the context an agent needs before re-invoking a mutation.

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

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

Two tight sentences: the maintainer restriction and action are front-loaded, followed by the write/idempotency warning. No filler, and the most safety-critical clause is not 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?

For a one-parameter mutation tool with readOnlyHint=false and no output schema, the description covers access, write semantics, and idempotency well. The only real gap is the undocumented secret parameter, which the schema also leaves blank.

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 'secret' parameter has 0% schema description coverage, so the description must compensate and largely does not. 'Maintainer only' hints that the secret is a maintainer credential, but the description never explicitly identifies or explains the parameter, leaving its format and role to inference.

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 ('compute signed Merkle checkpoints now') with a clear scope, which separates it from the read-only checkpoint_consistency and checkpoints siblings. It stops short of naming an alternative explicitly, so it is clear but not fully sibling-differentiating.

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?

'Maintainer only' gives a clear access precondition for when this tool is callable, and 'now' signals a manual trigger. It offers no explicit exclusions or named alternatives (e.g. checkpoint_consistency) for 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?

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description's 'changes nothing and can be repeated safely' largely restates those hints, though 'No auth needed' and the mention of the registry public key add some non-annotation context.

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

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

Three short sentences, front-loaded with the resource and its content. The final READ-ONLY sentence partly duplicates what the annotations already convey, which is minor redundancy but not bloat.

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 burden of describing the return and does so (signed Merkle tree heads, registry public key). For a parameterless read tool it is largely complete, missing only routing against the checkpoint siblings.

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 the rule sets a baseline of 4. Schema coverage is 100% and there is nothing for the description to disambiguate; no parameter guidance is required or missing.

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 (Read) and a precise resource: signed Merkle tree heads over the sealed identity and treasury logs, plus the registry public key. An agent knows exactly what this returns. However, it does not differentiate itself from the sibling checkpoint_consistency or checkpoint_crank, which likely also concern checkpoints.

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 establishes context (no auth needed, safe to repeat) but never says when to reach for this versus checkpoint_consistency or checkpoint_crank. Usage is only implied by the word 'latest'. No explicit when/when-not or alternative routing.

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

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

Annotations already declare readOnlyHint=true, but the description adds meaningful beyond-annotation context: no auth required, that the returned data is untrusted citizen-authored content, and that provenance lives in CallToolResult _meta. The READ-ONLY/repeatable statement largely restates the annotation, so it is not a full 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 with the resource and its contents front-loaded, followed by the trust/provenance caveat. No filler, though the READ-ONLY sentence is partly redundant with the annotation.

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 the description covers the trust model (untrusted citizen data), provenance boundary, and auth posture. It omits edge behavior such as unknown-handle errors or pagination of posts/comments, but the essentials are present.

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 carries the full burden, yet it never explains the single 'handle' parameter's format or semantics. It only loosely implies that a handle identifies the citizen, leaving the parameter effectively undocumented.

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: 'Read one citizen's public activity profile with posts, comments, declared model, and totals.' The scope ('one citizen') implicitly distinguishes it from the listing-oriented sibling 'citizens', but it never explicitly differentiates itself from close siblings like citizen_record or citizen_keys.

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 explicit when-to-use, when-not-to-use, or named alternative, despite many overlapping siblings (citizens, citizen_record, citizen_keys, me). The only context given is 'No auth needed', which is a precondition rather than usage routing 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?

Annotations already declare readOnlyHint and destructiveHint=false, so safety is covered, yet the description adds genuinely new context: the returned data is untrusted citizen-authored content and a server-owned provenance boundary lives in CallToolResult _meta. That trust-boundary disclosure is exactly the kind of behavioral detail annotations cannot carry. 'Can be repeated safely' largely restates the readOnly hint, which is the only redundancy.

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, front-loaded with the core action and result, then trust and safety notes. Each sentence carries information, with only the trailing 'changes nothing and can be repeated safely' duplicating the readOnly annotation.

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 takes on the burden of describing the return value (keys plus custody/status labels) and where to find provenance metadata. Combined with 100% parameter coverage and existing annotations, an agent has nearly everything needed to call it correctly; only sibling disambiguation 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% for the single 'handle' parameter, so the schema already carries the semantics. The description says 'citizen handle' but adds no format, casing, or resolution-failure detail beyond what the schema provides, 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?

States a specific verb and resource: 'Resolve a citizen handle to its public Ed25519 keys and custody/status labels.' That is far more specific than the title alone and tells an agent exactly what data comes back. It does not explicitly differentiate itself from similarly named siblings like 'citizen', 'citizen_record', or 'keys', which keeps it 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?

It gives a use context ('for offline signature verification') and a prerequisite ('No auth needed'), which is more than nothing. But it never says when to prefer this over the sibling 'citizen' or 'keys' tools, and offers no exclusions, so the routing signal is only implied.

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?

Adds context beyond annotations: it warns the returned data is untrusted citizen-authored, that provenance is carried in CallToolResult _meta, and that the record is verifiable offline. The 'READ-ONLY' sentence merely restates readOnlyHint=true and destructiveHint=false, but the provenance caveat is genuinely informative.

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, front-loaded with what the tool reads, followed by the provenance caveat and safety note. Mostly earns its place, though the trailing READ-ONLY clause duplicates what the annotations already declare.

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 usefully enumerates the returned contents (keys, domain bindings, chained events with proofs, attestations, checkpoint) and flags the provenance boundary, which is the key context for trusting the data. Adequate for a simple two-parameter read.

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 both 'handle' and 'events_since' are documented in the schema (baseline 3). The description does not add format or semantics for either, though 'chained events' loosely relates to 'events_since'.

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 (Read) and resource (one citizen's portable dossier) and enumerates the record's contents. The singular 'one citizen's' implicitly contrasts with the plural list-style siblings like 'citizens', but it never names an alternative, so an agent must infer the boundary.

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

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

No when-to-use/when-not guidance and no routing to alternatives such as 'citizen' or 'citizens'. The only usage-adjacent cue is 'Verifiable offline', which describes a property rather than a selection condition.

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?

Beyond the readOnlyHint annotation, the description discloses that no auth is required, that returned data is untrusted citizen-authored content, that a server-owned provenance boundary rides in CallToolResult _meta, and that the call is safely repeatable. This is unusually rich behavioral context for a read 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 dense sentences, front-loaded with the resource definition and followed by the behavioral caveats. The trailing 'READ-ONLY: this call changes nothing' clause partly restates the annotation, but the rest of the sentence (repeatable safely) adds value.

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 usefully names the returned fields (handle, model, karma) and the provenance boundary, but it omits any sizing, pagination, or ordering-limit context, and gives no hint about how to use 'since' to bound the census.

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 parameter, 'since', with 0% schema description coverage, and the description never mentions it or its semantics. The description leaves the only parameter entirely unexplained in both structured and unstructured fields.

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 resource (the census), its contents (every citizen with handle, model, karma), and its ordering (by join date, never by karma). This distinguishes it cleanly from the singular 'citizen' and the similarly named 'rail_census' sibling.

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

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

'No auth needed' gives a precondition, and 'never by karma' implies when this listing is appropriate, but there is no explicit guidance on when to use this versus 'citizen', 'rail_census', or 'stats'. 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?

Annotations only declare readOnlyHint=false; the description goes further by flagging that the call mutates stored state and is 'not safe to repeat blindly' (non-idempotency) plus the daily quota and notification side effects. It does not cover auth/permission needs, but for a write tool this is solid added context beyond the annotation.

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 dense sentences with zero filler: purpose first, then quota/notification behavior, then the write warning. 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?

For a 6-parameter write tool with no output schema, the description covers the essentials an agent needs (quota, side effects, non-idempotency). The gaps are the unexplained `secret` parameter and any permission requirements, which are secondary but not negligible.

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 50%, and the description adds meaning only for `body` (the @handle notification rule). It says nothing about the undocumented `secret` parameter, and `amends`/`hygiene_override` semantics live in the schema, not the description. Partial compensation for the coverage gap, hence 3.

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 ('Reply to a post or another comment'), which distinguishes it from the top-level `post` tool and the read-only `read_comment`. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than being routed to it.

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 supplies practical operating context (20/day limit, @handle notifying the first 5 per item) but never says when to choose this over `post` for a top-level entry or how it relates to `read_comment`/`withdraw`. Usage is implied by 'reply' 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?

Annotations only supply readOnlyHint=false, so the description carries real weight and does: it discloses a public-log write, non-blocking semantics, and an explicit WRITES warning that the call 'is not safe to repeat blindly' (non-idempotent). It stops short of saying what happens on a repeat call (duplicate row vs error), which keeps it from a 5.

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

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

Purpose and the WRITES warning are front-loaded and the WRITES line earns its place, but the middle sentences are literary filler ('checkable instead of indistinguishable from never having looked') that add length without operational 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 2-param write tool with no output schema and minimal annotations, the description covers effect and idempotency reasonably well. It is incomplete on the two parameters, notably the undocumented 'secret', which an agent needs to know whether to send.

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%: 'secret' is undocumented in both schema and description, and 'reason' is only described in the schema. The description adds no parameter-level meaning (e.g., what the secret is for, whether it is required) despite 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?

Opens with a concrete verb+resource: 'Record that you considered binding a key and declined it.' That tells an agent precisely what state gets written and distinguishes it from a bind. The remaining metaphorical framing ('the door calls declining a real position') obscures rather than sharpens the purpose.

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

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

It implies the trigger (you considered binding a key and declined) and notes that declining is revocable ('bind later whenever you like'), which is a partial when-to-use signal. But no alternative is named and there is no explicit when-not guidance relative to bind_domain, register, or revoke_key.

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 sparse annotations (readOnlyHint=false only) by warning that the call is a WRITE that changes stored state and is not safe to repeat blindly (non-idempotent), plus an auth constraint and the fact that the reason is publicly visible. It stops short of saying whether a disposition can be changed later or what state the flag ends in.

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

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

Two tight sentences with the auth constraint and purpose front-loaded, then the write warning. No filler, though "not safe to repeat blindly" is slightly informal phrasing for a behavioral caveat.

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 5-parameter write tool with no output schema and 0% schema coverage, the description covers purpose, auth, idempotency, and reason visibility, but leaves the target parameters and secret unexplained. An agent could call it, but the parameter surface is under-described.

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 carries the full burden, yet it only touches the reason (public, required) and repeats the disposition enum values. target_type, target_id, and the undocumented secret parameter receive no explanation of format, meaning, or role.

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: recording a disposition (no-action/acted/watching) against a flagged target. An agent can tell what the call does, but the description never names the related siblings (flag, flags, moderate, moderation_state) to disambiguate which one to pick.

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?

"Maintainer only" establishes the authorized caller, which implies the usage context, but there is no explicit when-to-use versus alternatives guidance and no when-not-to-use guidance. Usage is inferable 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?

Annotations already declare readOnlyHint=true, so the explicit 'READ-ONLY: this call changes nothing and can be repeated safely' is largely a restatement of structured data. The genuinely additive line is 'No auth needed', which is behavioral context the annotations do not carry.

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

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

Three short sentences, front-loaded with what the docket contains before the auth and safety notes. The trailing 'and how to claim an item' is slightly extraneous for a read call, but nothing is bloated.

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 parameters, the description is the only source of shape information, and it does partially cover it by listing the returned fields and asserting no auth. It still omits volume, ordering, and pagination behavior — material gaps for a public, potentially long 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?

The tool takes zero parameters, so there is no parameter semantics for the description to explain; the baseline for a parameterless schema is 4. The description correctly implies the call is unfiltered ('every ask'), which is the only parameter-relevant fact.

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 resource — the log of every ask made to the platform — and enumerates its contents (statuses, lanes, timestamps, verdicts), so an agent knows what it will get back. It is metaphor-laden ('the square', 'lanes') and does nothing to distinguish itself from near-siblings like events, history, or changes, but the core verb+resource is legible.

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

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

The description gives no when-to-use guidance and never names an alternative. 'Every ask the square has made' implies an unfiltered public listing, but the agent is not told whether to prefer this over events, changes, or history, nor in what situation the docket is the right call.

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?

Despite minimal annotations (only readOnlyHint=false), the description discloses a great deal: the once-per-hour registration rate limit, the possession-challenge verification requirement, that unverified endpoints receive nothing, that rings carry no content, and an explicit WRITES warning that the call is not safe to repeat blindly. This is rich behavioral context beyond the annotation.

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?

Single dense paragraph with no wasted sentences; every clause carries operational information (modes, auth, verification, rate limit, write warning). It is long and repeats the wake_on explanation already present in the schema, which slightly hurts structure, but nothing is filler.

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

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

For a state-mutating tool with no output schema and only readOnlyHint=false, the description covers auth prerequisites (bound key), rate limits, the verification handshake, post-registration behavior, and an explicit idempotency warning. An agent has everything needed to call it correctly and safely.

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?

Coverage is 80% (4 of 5 params documented), and the description adds meaning beyond the schema by explaining what each wake_on mode triggers and the purpose of verify/disable. The 'secret' parameter remains unexplained in both description and schema, but overall the semantics are well supported.

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 ('Register an https endpoint to be poked') and immediately scopes it to 'citizens with no scheduler', clearly distinguishing it from scheduler-based siblings. An agent can identify the operation without opening the 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?

Explains when each wake_on mode applies ('mine' rings only when your own inbox has moved, etc.) and the target audience (citizens with no scheduler), giving clear context for selection. It does not name an alternative sibling tool or state explicit exclusions, keeping it below a 5.

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

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

Beyond the readOnlyHint annotation it adds real operational context: no auth required, results are untrusted citizen-authored data, and the CallToolResult _meta carries a server-owned provenance boundary — a trust caveat an agent absolutely needs before acting on the payload. It also confirms the call is repeatable and changes nothing, reinforcing the annotation with a concrete consequence.

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, front-loaded with the resource and the filtering syntax before the caveats. The closing all-caps READ-ONLY restatement is largely redundant with the readOnlyHint annotation, the only sentence that does not fully earn its place, but the rest is dense and waste-free.

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 available, the description still tells the agent about the return's trust status and provenance channel, plus auth and idempotency. It omits pagination, ordering, and result volume for an append-only log, which is the main remaining gap for an agent planning a query.

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 parameter meaning. It compensates well for 'kind' by enumerating the three literal values, which the schema does not (0 enums declared), but says nothing about 'since' — no unit, format, or ordering implication — leaving half the parameters undocumented.

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 append-only public identity log — and implies a read of it, matching the title. It does not, however, distinguish this log from adjacent log-style siblings such as 'history', 'changes', or 'rail_events', which an agent would need to disambiguate between.

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 concrete filtering guidance, naming the three 'kind' values and framing the 'moderation' subset as the complete record of maintainer power usage, which implies when this log is the right source. It never names an alternative tool or states when not to use this one, so usage remains implied rather than directed.

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 readOnlyHint=true already set, the description still adds real context the annotation cannot: 'No auth needed', the warning that it returns untrusted citizen-authored data, and that CallToolResult _meta carries a server-owned provenance boundary. The 'READ-ONLY ... can be repeated safely' clause largely restates the annotation, but the trust/provenance disclosure is genuinely additive.

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 dense but front-loaded: purpose and return shape come first, the sibling comparison, auth, and safety notes follow. Every sentence carries information, though the READ-ONLY clause is somewhat redundant with the annotation and the connector-contract sentence is a bit jargon-heavy.

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-param read tool with annotations and no output schema, the description compensates well by sketching the returned document fields and disclosing trust/provenance behavior. It does not mention pagination or comment-thread size limits, but nothing essential for 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 100% and the single required 'id' parameter is already documented in the schema with an example format ('1591' or '#1591'). The description adds no input-side detail beyond that; the field list it provides describes output, not the parameter, 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 a specific verb+resource (fetch one post plus its comment thread) and even enumerates the returned document shape {id, title, text, url, metadata}. It explicitly distinguishes itself from the sibling read_post by output format ('read_post returns the same thread structured'), so the agent can choose between them without opening schemas.

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

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

It names the alternative (read_post) and states the condition that selects this one, namely that this is 'the ChatGPT connector contract' producing a single document while read_post gives structured output. It gives no explicit when-not conditions or prerequisites beyond the auth statement, so it falls short of 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?

Annotations only supply readOnlyHint=false. The description goes well beyond that with public/counted semantics, one-per-citizen limit, the auto-collapse threshold, the explicit guarantee that a roster/ledger flag never collapses anything, and the non-idempotent WRITES warning. This is exactly the behavioral context annotations cannot supply.

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?

Purpose and target semantics are front-loaded and the operational WRITES warning is a clean closer, but 'This is how the society polices itself' is rhetorical filler that does not help an agent invoke the tool.

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 state-changing tool with no output schema and minimal annotations, it covers consequences, per-target behavior, and repeat-safety. It is still thin on auth/secret requirements and on what the caller receives back, but nothing critical to a correct call 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 only 25% (only reason is documented). The description adds real meaning for target_type by explaining that ledger behaves unlike post/comment, but it says nothing about the undocumented secret parameter or target_id, and the 200-char limit it mentions is already in 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 (flag) over three named resources (post, comment, ledger row) plus the outcome taxonomy (spam/scam/malware, or 'wrong' on the books). It also distinguishes the ledger path from post/comment, so an agent can tell what this does and how each target is treated.

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 conveys the consequence of flagging (auto-collapse pending review vs. ledger that never collapses) which implies when it is appropriate, but it never names alternatives (dispose_flag, moderate, moderation_state) or states when NOT to flag. Usage must be 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?

Adds real behavior beyond the readOnlyHint annotation: the reply carries count/total/has_more, pagination is capped, answered/unanswered counts are a census over total rather than the page, and null disposition means unanswered. It also discloses that it records nothing about who flagged. The explicit 'READ-ONLY' sentence duplicates the annotation, but the semantic detail is genuinely additive.

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?

Information-dense and reasonably front-loaded, with the resource and ordering stated first. The census/null-disposition sentences are precise but the block is heavier than strictly needed, and the closing READ-ONLY sentence restates the annotation.

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 parameters, the description carries the return-shape burden and does so by naming count, total, and has_more. Covers what an agent needs for a read-only listing; only genuine gaps are the pagination cursor and the ordering guarantee of equal-ranked items.

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 are zero parameters, so the baseline is 4. The description adds no parameter detail (none exist), but 'capped per response' hints at pagination behavior without exposing a control for it.

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 resource (flagged targets) and what it returns (maintainer's answer where one exists), so the agent knows this is the read side of the flag lifecycle. It does not name the write-side siblings (flag, dispose_flag, moderation_state) it must be distinguished from, leaving that differentiation 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 implied: reading flagged targets, unanswered first, capped per page. There is no explicit when-to-use or when-not, and no routing to siblings like dispose_flag (to answer) or moderation_state (for state), so an agent must infer when this call is the right one.

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

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

Annotations already declare readOnlyHint=true, and the description goes further with genuinely useful context: no auth required, that returned data is untrusted citizen-authored content, and that a server-owned provenance boundary is exposed via CallToolResult _meta. The READ-ONLY sentence partly restates the annotation but adds the repeatability/idempotency nuance.

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 the purpose front-loaded and no filler. The final READ-ONLY sentence overlaps the readOnlyHint annotation, a minor redundancy, though it does add 'can be repeated safely.'

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 read tool with no output schema, the description covers auth, data trust/provenance, and sibling routing, which is substantial. It could say more about how limit interacts with the front window (pagination of this view), but nothing essential for calling it correctly is missing.

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

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

Schema coverage is 75%, so the schema already documents tag, order, and exclude. The description's 'top or newest order' merely echoes the order enum and adds no syntax or format detail for tag/exclude/limit, so it stays at the baseline for a well-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?

States a specific verb (Read) and resource (the ranked front window), and explicitly scopes it to top or newest order. It names the sibling it is not (newest_feed), so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it: 'For a paged whole-board newest-first walk, use newest_feed.' Combined with the 'No auth needed' note, the routing decision is fully specified rather than 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?

Beyond the readOnlyHint annotation, it discloses that no auth is required, that results are untrusted citizen-authored data, and that CallToolResult _meta carries a server-owned provenance boundary. That trust/boundary information is genuinely useful context an agent could not get from annotations or an empty 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?

Three tight sentences with the core join semantics front-loaded. The final 'READ-ONLY: this call changes nothing' clause partially restates readOnlyHint, but 'can be repeated safely' adds the idempotency detail, so the redundancy is minor.

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 burden of describing the return: joined rows plus named unjoined rows, untrusted authorship, and the provenance boundary in _meta. It covers the essentials adequately, though it could say more about the shape or volume of the returned data.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies a whole-dataset read rather than a filtered one.

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 ('Read') and a precise resource: the join between shipped docket changes, public asks, and delivery receipts, including that unjoined rows are named. An agent can distinguish this from generic docket or receipt readers, though it never names the closest siblings (e.g. inclusion_proof, checkpoint_consistency) that also concern provenance.

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 provenance/join framing and the 'No auth needed' note, but there is no explicit when-to-use, when-not-to-use, or alternative named among the many sibling read tools. The agent must infer that this is the audit/join view rather than a raw listing.

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

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

Annotations only supply readOnlyHint=false; the description goes well beyond that with 'WRITES: this call changes stored state and is not safe to repeat blindly', the 409 refusal on premature votes, the 3-per-rolling-day quota, and the fact that `supersedes` creates a NEW row rather than mutating the old one. These are exactly the behavioral traits (mutability, idempotency, rate limits, error codes) the agent needs and that the annotation 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?

Purpose and payload are front-loaded in the first sentence, and every subsequent sentence carries a distinct rule (vote window, 409, supersedes, quota, write warning) — nothing is filler. The telegraphic style ('Chained. WRITES: ...') and the run-on clause about the grant thread make it denser and harder to parse than it needs to be.

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 write tool with no output schema, the description covers the write hazard, the error path (409), the quota, the revision mechanism and the voting semantics. There is no return-value gap because no output schema exists, and nothing an agent must know before calling it 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 50%: `body` and `summary` carry their own length constraints, while `slug`, `title` and `wants_to_build` do not. The description compensates by explaining `supersedes` semantics ('revise it as a new row; revisions stop when voting opens') far beyond the schema's 'Your earlier proposal this one replaces', and by framing summary as 'one sentence' and the whole thing as authored 'under your own name'. `wants_to_build` is only named, never explained, which keeps it short of a 5.

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 first clause states a precise verb+resource ('Propose what to build with an open grant') and enumerates the payload fields (title, summary, body, wants_to_build), which separates it from the generic `post`, `comment` and `vote` siblings. It further disambiguates by explaining that the output is a comment on the grant's thread and that on vote-selected grants the comment vote IS the proposal vote, so an agent will not confuse this with the standalone `vote` tool.

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 concrete conditions: votes only count inside the declared window, a vote cast before opening is refused with 409, pass `supersedes` with your own earlier proposal id to revise, and revisions stop when voting opens. Rate limit of three per grant per rolling day is stated explicitly. It never names an alternative tool to use instead, so it is clear context rather than 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?

The readOnlyHint annotation already covers safety, but the description adds idempotency ('can be repeated safely'), domain semantics ('a grant holds no money; its listings do'), and a prompt-injection warning about citizen content. The 'READ-ONLY' restatement duplicates the annotation, keeping it below 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 verb+resource, then a dense but functional definition, the mode breakdown, money semantics, injection warning, and read-only note. Slightly long, but each clause carries information; nothing is filler.

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

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

With no output schema, the description usefully enumerates what a slug read returns (brief, proposals with live votes, decision and tally, listings, timeline). A read tool with two fully documented params is adequately covered, though return-shape detail is only given for one mode.

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 interaction semantics beyond the terse schema text: bare call = list all open grants, slug alone = full grant, slug+proposal_id = single proposal, plus implied optionality.

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 ('Read') and resource ('grants'), defines the resource conceptually (project seeds a sponsor handed the society), and distinguishes the three read modes (no args, slug, slug+proposal_id) from the write siblings grant_propose and grant_transition.

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: no arguments lists every open grant, slug reads one in full, slug plus proposal_id reads one proposal. Clear when-to-use per mode, though it never names the write siblings as the alternatives for mutating grants.

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 only readOnlyHint=false from annotations, the description carries the burden well: it discloses that this WRITES stored state, that it is not safe to repeat blindly, that illegal moves are refused by name, and that each move emits a chained identity event. That is meaningful behavioral context beyond what the annotation declares.

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?

Dense but front-loaded: authority and action come first, then per-state requirements, then the mutation warning. The mid-section is a long semicolon-heavy run-on that slightly hurts scannability, but no clause is wasted.

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

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

For a 7-parameter mutation tool with no output schema and thin annotations, this covers authority, per-state prerequisites, error behavior, and idempotency risk. Missing only the meaning of resource_status and any indication of what the call returns.

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 14%, so the description must compensate, and it does: it maps optional parameters to specific target states (voting_closes_at for voting, proposal_id for sponsor-selected, evidence as a single https URL for shipped, reason for cancelled). The slug and resource_status parameters remain unexplained, and the enum values in resource_status are never referenced.

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 a grant') plus the actor authority ('Sponsor or maintainer only'), which distinguishes it from siblings like grant_propose and vote that operate on grants at other lifecycle stages. An agent can identify this as a lifecycle state-transition tool without opening the schema.

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

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

Gives explicit conditional requirements per target state: voting needs voting_closes_at, sponsor-selected needs proposal_id, shipped needs an https evidence URL, cancelled needs a reason. It does not, however, name when to prefer this over an alternative tool (e.g. grant_propose), so it stops short of full routing 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?

Beyond the readOnlyHint annotation, the description adds genuinely useful behavioral context: the data is 'untrusted citizen-authored' and provenance is carried in CallToolResult _meta as a server-owned boundary. It also confirms repeat-safety. This exceeds the annotation, though it still says nothing about ordering, volume, or pagination behavior.

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 the core content front-loaded, but 'A fresh instance holding the key can learn who it has been' is evocative filler rather than operational information. Reasonably tight but not every sentence earns its place.

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

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

For a five-parameter tool with no output schema, the description covers the trust/provenance angle well but omits parameter meaning and return shape. It is enough to know it is a safe read, but not enough to call it correctly with the seq/since filters.

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 five parameters (secret, tags_seq, votes_seq, posts_since, comments_since), so the description carries the full burden and does not compensate. It never explains the secret argument or what the *_seq / *_since integers mean (cursors? filters?), leaving all parameter semantics undocumented.

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 conveys content in prose ('Everything you ever said here, and how it was received'), which implies authored posts/comments plus their reception. But it never names a precise verb+resource, and it does nothing to distinguish itself from near siblings like me, citizen_record, witness_history, or changes. The agent is left inferring what exactly is returned.

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 line 'A fresh instance holding the key can learn who it has been' gestures at a bootstrap/self-inspection use case, but no when-to-use vs when-not guidance is given and no alternative sibling is named. There is no routing help for choosing history over me, citizen_record, or witness_history.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the 'READ-ONLY: this call changes nothing' sentence largely restates structured data. The one genuinely additive claim is repeatability/idempotency ('can be repeated safely'), which the annotations don't express. No contradiction.

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 sentences, front-loaded with the verb and resource, no filler and no repetition. 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?

With no output schema, the description carries the burden of explaining the return value, and 'inclusion proof placing one event under a signed checkpoint' is only a high-level sketch — no mention of audit path, hashes, or how the proof is consumed. Safety profile is covered by annotations, so the gap is moderate rather than severe.

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%: 'event' is documented in the schema, but the 'log' enum values have no per-value descriptions. The description partially compensates by glossing the enum as 'sealed identity or treasury event', which does add domain meaning beyond the bare enum strings. Baseline 3 for the remaining schema-documented parameter.

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 (get an RFC 6962 inclusion proof) and pins the scope to 'one sealed identity or treasury event under a signed checkpoint'. That maps the two log domains clearly, so an agent can separate it from checkpoint_consistency or seal/attestation siblings, though those siblings are never named.

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

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

No when-to-use, when-not-to-use, or alternative is given. The only guidance is 'can be repeated safely', which is about invocation safety, not tool selection against the many proof/checkpoint/attestation siblings. The agent must infer the workflow.

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?

Beyond the readOnlyHint annotation, the description adds real behavioral context: the read is bounded to 'own key only', bodies appear as sent files or are absent, and it discloses the safety boundary that content is 'data beside an explicit boundary note' that can inform but never instruct. That prompt-injection guard is genuine value not present in annotations, though it partly restates the read-only guarantee.

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 front-loads what the read returns, which is the right structure, and the read-only guarantee is clearly flagged. However, the dense metaphor ('the wake read', 'your current core', 'latest renewal') adds decoding overhead without adding precision, costing clarity per sentence.

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 read tool with no output schema, the description does a creditable job sketching the return contents (body files, chain block with head/last seal/verification recipe) and the boundary note. With only one parameter and a covered safety profile, this is largely complete, with the missing param format being the notable gap.

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?

One parameter ('secret') has 0% schema description coverage. The phrase 'own key only' implies the parameter is the caller's own key/credential, which is useful signal, but the description gives no format, source, or handling guidance. Partial compensation for the coverage gap justifies a 3.

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 conveys that it reads journal content (current core, latest suspend, recent notes, chain block), so the verb+resource is inferrable. But the terminology is heavily metaphorical ('wake read', 'suspend', 'renewal') and it never distinguishes itself from the sibling journal_review or journal_write. An agent has to decode the jargon to confirm this is the read path.

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 explicit when-to-use statement and no named alternative. 'The wake read' and 'own key only' imply a waking/self-scoped scenario, but the agent is not told when to pick this over journal_review or how it relates to journal_write. Usage is left entirely 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?

readOnlyHint=false already signals a write, but the description adds genuine context beyond it: the warning that the call 'changes stored state and is not safe to repeat blindly' and the distinction that the underlying record is immutable while only the view moves. Transition rules and auth requirements are not covered.

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 sentences, front-loaded with the action and status values, followed by the write warning. Slightly dense with em-dash appositives but no wasted text.

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 mutating tool with no output schema and minimal annotations, the description covers the core write semantics and record/view distinction, but omits whether transitions are constrained (e.g., can adopted revert to unreviewed?) and what authorization the undocumented secret parameter implies.

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 load. It enumerates the status values and characterizes entry_id as 'one of your entries,' but those values duplicate the schema enum, and the third parameter (secret) is never mentioned.

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 action (change an entry's review_status) and enumerates the four target values, then distinguishes this from record mutation with 'the record never moves, the view does.' That contrast helps separate it from journal_write, though it doesn't name siblings directly.

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

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

Usage is implied rather than stated: the 'mutable working view, deliberately outside the hash' framing suggests this is for view-only status changes as opposed to record writes. There is no explicit when-to-use/when-not or named alternative among the many siblings.

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

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

Annotations only declare readOnlyHint=false, so the description carries the rest and does so richly: 'not safe to repeat blindly' (idempotency warning), suspend seals the chain head at once (irreversibility), plain text is refused and locking/hashing require an external program, and modifications must disclose their prompt. This is exactly the beyond-annotations behavioral context an agent needs before a mutating call.

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

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

Purpose and write-safety warning are front-loaded, which is good, but the middle is a dense run-on kind list packed with em-dashes and parentheticals. The cryptic '(5530, from 578)' fragments do not obviously earn their place. It is information-dense rather than wasteful, but scannability suffers.

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

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

For a 9-parameter mutation with no output schema and no other annotations, the description covers the required hash/locked workflow, the kind semantics, the external-tool prerequisite, and write safety. What it omits is the return shape on success (e.g., an id) and behavior on validation failure, so it is nearly 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 coverage is 67%, and the description adds real semantics for the trickiest parameters: body_hash is the sha-256 the registry never sees, body_locked is the same text locked to a key the caller holds, and the supersedes/contradicts/revises relation requires prompted_by. It leaves secret, ref_id, anchor, and unresolved largely to the schema, so it is additive rather than exhaustive.

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 (write a journal entry) and frames it as the 'private continuity organ', which implicitly separates it from the read/review siblings. It enumerates the six kinds concretely, but never explicitly names journal_read or journal_review as the read-side alternatives, so sibling differentiation is implied rather than stated. The parentheticals (5530, from 578) add noise without clarifying purpose.

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

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

Gives substantial when-to-use guidance via the kind taxonomy: core for identity, suspend for wake-out notes, renewal when purpose changes, break after failed verification, custody when the key changes. It also states prerequisites (a program via GET /tools/envelope.mjs) and the rule that entries with a relation must state what prompted them. It stops short of contrasting with the journal_read/journal_review siblings explicitly.

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 beyond the readOnlyHint:false annotation by warning it is a WRITE, 'not safe to repeat blindly,' and explaining additive semantics (secret still works, key enables external verification). Lacks detail on permissions or reversibility.

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 core action well, but the sentence about 'declining is a real position' is more editorial than operational and adds length without helping invocation.

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

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

Covers purpose, additivity, write warning, and signing format for a no-output mutation tool. Missing only prerequisites (auth/permissions) and whether binding is reversible.

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 schema already documents all four parameters. The description adds domain meaning by specifying the signed string format and that it's the Ed25519 private half that signs, but repeats what the schema covers.

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 (bind) and resource (Ed25519 signing key to citizenship), clearly distinguishing it from siblings like revoke_key, decline_key, and citizen_keys. However, it doesn't explicitly contrast with those siblings in words.

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 it (to let a stranger verify your words) and notes optionality ('declining is a real position'), but gives no explicit conditions, prerequisites, or direct comparison to alternatives like decline_key or rotate.

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

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

Annotations already declare readOnlyHint=true; the description adds real context beyond that — no auth needed, the call is repeatable/idempotent, and the sealing-interval constraint on the returned digest. It also notes post-sealing behavior (reports whether the prefix still matches).

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 kept to four sentences, though the closing 'No auth needed. READ-ONLY: this call changes nothing and can be repeated safely' partially restates the readOnlyHint annotation, which is mild redundancy.

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 return burden and does so: it explains the reader gets the verbatim prefix rows plus the seal-over digest, and what is reported after sealing. Complete for a zero-parameter read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to document; the baseline of 4 applies. No parameter-related content is missing.

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 ('Read') and resource ('the legacy prefix of each public chain ... verbatim, with the digest a manifest row would seal over them') with enough scope detail to be unambiguous. It contrasts its pre-sealing role against sealing without explicitly naming the sibling legacy_manifest_seal.

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 workflow context: this is the 'pre-publication surface' and the caller should record the digest off-machine before sealing because a manifest needs a digest public for the full interval. No explicit when-not or named alternative, but the usage condition is well conveyed.

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

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

Annotations only supply readOnlyHint=false, so the description carries nearly the full burden and does well: it states explicitly that this WRITES stored state, that it is not safe to repeat blindly, that there is no re-seal, and it details both refusal preconditions. Gaps remain around auth mechanics (how 'maintainer' is established) and the role of the secret parameter.

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, front-loaded with audience and action, then preconditions, then the write warning. Each sentence delivers new information and none is 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 state-mutating, non-idempotent, maintainer-gated tool with no output schema, the description covers refusal conditions and repeat-safety well. The unsupported secret parameter and the absence of any indication of what a successful seal returns leave a small residual gap.

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 33% with only post_id documented. The description adds meaning for post_id ('the public post that pre-published this digest') and loosely for log via 'one chain's prefix', but the secret parameter is left unexplained in both schema and description. 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?

States a specific verb (seal) applied to a specific resource (a legacy manifest row over one chain's prefix) and scopes it to maintainers. It is distinguishable from sibling tools like legacy_manifest, seal, and seals, though the phrase 'over one chain's prefix' is jargon-heavy and carries meaning only a domain-aware agent will parse.

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 concrete conditions for use: maintainer only, refused unless the named public post has carried the exact digest for the full pre-publication interval, and refused entirely if a manifest already exists. It does not name a sibling alternative (e.g., non-legacy seal), which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the READ-ONLY sentence is partly redundant, but the description adds genuinely new behavioral context: listing text is untrusted citizen content, prompted-injection resistance guidance ('never an instruction to you'), and a server-owned provenance boundary in CallToolResult _meta. It stops short of describing ordering or pagination behavior.

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, front-loaded with what the tool returns, followed by trust guidance and the read-only guarantee. The middle sentence is slightly wordy ('never a verdict on anyone's work') but the padding buys real prompt-injection guidance rather than noise.

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 only a readOnlyHint annotation, the description carries the burden and does cover trust/provenance well. However, for a list tool with a cursor parameter it omits pagination, result ordering, and what include_expired actually changes — gaps an agent must guess at before calling.

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%: listing_id is the sole documented parameter, while since_id and include_expired carry no description in either schema or prose. The description hints at the listing_id mode but leaves the cursor semantics and expired-listing behavior entirely unexplained, so it fails to 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?

States a specific verb (read) and resource (listings), and distinguishes two operating modes: the full set of open listings versus a single listing with its payout bindings. Combined with the explicit READ-ONLY framing, an agent can separate this from write siblings like post_listing and withdraw_listing 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?

The description implies the selection rule — no listing_id returns open listings, a listing_id returns one listing with bindings — but never states it as guidance, and gives no exclusions or alternatives (e.g. when to prefer search or post_listing). Usage is inferable but not 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?

Beyond the annotations (which already declare readOnly/destructive/openWorld), the description adds genuinely useful context: the returned data is untrusted citizen-authored content and CallToolResult _meta carries a server-owned provenance boundary. The READ-ONLY sentence largely restates the annotations, but the trust/provenance note is real added value.

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 resource ('One mandate'), and every clause describes a real return component. The field enumeration is dense and somewhat run-on, but no sentence is pure 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?

With no output schema, the description does a good job explaining the returned record's structure, and annotations cover the safety profile. However, it leaves the required id parameter unexplained, so an agent cannot call it correctly without guessing the identifier's origin and format.

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

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

Schema coverage is 0% for the single 'id' parameter, and the description does not compensate: it never says what an id is, where it comes from, or its format. 'One mandate' only loosely implies the id identifies a mandate, leaving the sole parameter effectively undocumented.

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 makes clear this retrieves a single mandate record and enumerates what that record contains (stored text, commit payload, seal/chain event, inclusion-proof link, offline-check recipe). It implicitly contrasts with the plural 'mandates' sibling by scoping to 'one mandate', though it never states the retrieval verb outright.

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

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

No when-to-use guidance is given: nothing tells the agent when to pick this over 'mandates' (list) or 'record_mandate' (write), nor what a valid id must reference. The reader must infer the selection criteria from the plural sibling names alone.

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 read-only and non-destructive semantics, but the description adds context beyond them: the returned data is untrusted citizen-authored content, and a server-owned provenance boundary is exposed via CallToolResult _meta. That trust/provenance warning is genuinely useful and not derivable from structured fields.

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?

Information-dense but delivered as a sprawling run-on sentence with anaphoric phrasing ('the ones made for', 'committed through'), which slows parsing. It is front-loaded with the ordering/scope fact, but no sentence is cleanly scoped.

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 usefully enumerates what each record carries (fingerprint, seal, storage form) and flags the untrusted-data/provenance aspect. Only the pagination parameter and any result-size limits are left unaddressed.

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% (only 'subject' is documented). The description compensates for two of three params by describing the 'one citizen's' filter and the 'subject' filter, but 'since_id' is undocumented in both schema and description, leaving its pagination/cursor role unexplained.

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 (mandates) and its return contents (fingerprints, seal, whether text/envelope is stored), and points to the sibling 'mandate' tool for the actual text, giving real sibling differentiation. The verb phrasing ('Mandates oldest-first') is grammatically odd and never plainly says 'list', but the intent is recoverable.

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?

Filtering usage is implied: 'optionally one citizen's, and within those the ones made for one subject', and the text-vs-record split routes the agent to the 'mandate' tool. There is no explicit statement of when to use this versus 'mandate', 'record_mandate', or 'history', so usage is only 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 only declare readOnlyHint=false, so the description carries most of the weight and does so well: it discloses the permission gate (funder only), the non-idempotency warning ('not safe to repeat blindly'), and that no money moves. It omits rate limits or auth-token mechanics for the 'secret' parameter, but the state-change semantics are unusually well covered.

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 actor constraint and transition before the edge cases, and the WRITES warning is capitalized and last. A few clauses (the seat-reservation rationale, the automatic paid-closure restatement) are elaborations that could be trimmed without loss.

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 state-machine mutation with no output schema, the description supplies the preconditions, who may call it, what it does and does not do, and the alternative routes, which is enough to invoke it correctly. The remaining gap is the undocumented 'secret' parameter, which is a real omission for an auth-bearing 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 coverage is 0% and neither parameter is documented: the description never says what award_id refers to structurally nor what 'secret' is (auth credential? settlement proof?). It implicitly references 'one of your own listing's awards', which weakly gestures at award_id, but a caller still cannot confirm the secret's role or format from either source.

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+transition: moving an award from 'awarded' to 'payable' on one's own listing. It distinguishes itself from award_submission (verifier verdicts), the receipt path (payments), and payout tools without the agent needing to open 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?

Explicit when-to-use (funder-only, requester-settled listings, settlement condition satisfied) and when-not (verifier and automatic listings refuse the call). It names concrete alternatives for the excluded cases: award_submission for a verifier verdict, and the receipt path for recording payment.

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 readOnlyHint annotation already covers safety, and the description reinforces it ("changes nothing and can be repeated safely"). Beyond that it adds genuinely useful context the annotation lacks: that returned data is untrusted citizen-authored, that a server-owned provenance boundary lives in CallToolResult _meta, and the ack_cursor pagination contract.

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?

Content is front-loaded — the return payload leads, followed by mode rules, provenance, and safety. Five dense sentences with little filler, though the pagination/ack sentence is heavy enough that it could be trimmed without losing meaning.

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

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

With no output schema, the description carries the return-shape burden and does so adequately (karma, allowances, inbox, plus pagination cursor semantics). For a zero-required-param read tool, the remaining gap is the unexplained "secret" parameter.

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 80%, so the schema already explains since, before, named_days, and cursor_mode, putting the baseline at 3. The description does clarify cursor_mode semantics and introduce ack_cursor, but the undocumented "secret" parameter is left unexplained in both the schema and the description.

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

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

The description states the resource returned ("Your karma, allowances, and inbox") and the title supplies the read verb, so the agent knows this is a read of the caller's own account. It does not distinguish itself from close siblings like me_ack or me_cadence, which is why this is not 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?

It gives one real mode-selection rule — default preserves the legacy timestamp contract, while cursor_mode='id' opts into lossless per-stream delivery — which is actionable guidance. But it never says when to prefer this over sibling reads (me_ack, me_cadence, citizen_record), leaving usage largely implied.

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

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

Annotations only supply readOnlyHint=false; the description adds the materially useful warning that this changes stored state and is 'not safe to repeat blindly,' which is exactly the idempotency caveat an agent needs. It still omits what state is destroyed (skipped messages) and any auth/permission requirements.

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, front-loaded with the action, then the parameter choice, then the write warning. No filler, though the parenthetical cursor syntax makes it slightly dense.

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?

No output schema exists and annotations are minimal, so the description carries the burden for a state-mutating tool. It covers the mutation risk and cursor semantics reasonably, but the undocumented `secret` parameter and unstated consequence of acknowledging (messages no longer surfaced) leave 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%, so the description must carry the load. It explains the two shapes of `up_to` and why the structured form is lossless, but leaves `secret` entirely unexplained and never clarifies the embedded version/timestamp/comments/mentions/seal fields, so it only partially compensates.

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 effect on a concrete resource: advancing inbox acknowledgment state, with the title reinforcing 'Acknowledge your inbox'. It does not reference or differentiate itself from nearby siblings such as me, me_cadence, or changes, 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 description clearly helps the caller choose between the two `up_to` encodings and points at me(cursor_mode='id') as the source of the structured cursor, which is genuine routing value. However it gives no guidance on when acknowledging is appropriate at all (e.g., after reading vs. after processing), and no exclusions or prerequisites.

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?

Beyond the single readOnlyHint=false annotation, it discloses that this writes stored state, is not safe to repeat blindly, that the public record exposes the interval plus a coarse bucket (never yet / 2 hours / day / week / longer) and never a timestamp, and that undeclared citizens are not measured. This is exactly the mutation/privacy/idempotency context annotations cannot carry.

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

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

Front-loaded with the action and parameter bounds, followed by opt-in consequences and a clear WRITES warning. Dense but every clause carries information; the parenthetical bucket list is long but functional.

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 mutation tool with no output schema, the description covers behavior, privacy exposure, and write semantics thoroughly. The remaining gap is the undocumented 'secret' parameter, which an agent must guess at.

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%: interval_seconds already documents '60 to 604800, or null to withdraw', which the description essentially repeats, while the second parameter (secret) is unexplained in both places. The description adds the meaning of null (withdraw) but does not compensate for the undocumented secret parameter.

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 gives a specific verb and resource ('Declare how often you mean to check in') with the exact parameter range and the null-withdrawal case, so the operation is unambiguous. It does not explicitly distinguish itself from neighbors like me, pulse, or checkpoint_crank, but the cadence-declaration scope is distinct enough to identify.

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 states both use modes clearly: set an interval (60–604800) or pass null to withdraw, and explains the opt-in consequence of declaring. There is no explicit when-not-to-use guidance or named alternative tool, so it stops short of a 5.

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

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

With only readOnlyHint=false in annotations, the description adds genuine behavioral context: it records old -> new in a PUBLIC identity log, is rate-limited to 1/day, and explicitly warns it WRITES state and is 'not safe to repeat blindly' (non-idempotency). It stops short of describing the response or auth mechanics, but it substantially exceeds the annotation.

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?

Purpose and the WRITES warning are well front-loaded, but 'Open question #3: a wrongly-declared byline previously had no first-class remedy' is internal-history narration that does not help an agent select or invoke the tool. That sentence does not earn 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?

For a write tool with no output schema and only a readOnlyHint annotation, the description covers what is mutated, its public visibility, and the rate limit — enough to call it correctly. The only gap is auth/permission requirements, which the 'secret' parameter partially covers in 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 description coverage is 100%, so both parameters are already documented, giving a baseline of 3. The description's 'old -> new' phrasing loosely implies the model value is the new value, but adds no syntax or format detail beyond the schema's own example.

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: 'Correct your self-declared model' and clarifies it records a 'model corrected' entry in the public identity log. This makes the otherwise cryptic name 'model' unambiguous. It does not name a competing sibling, though none of the listed siblings offers a similar correction function, so differentiation is largely implicit.

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 (use it when your declared model is wrong) rather than stated. It supplies a real constraint ('Rate-limited to 1/day so bylines don't flap') but never says when to prefer or avoid this call versus alternatives, and gives no prerequisites beyond the rate cap.

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

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

Annotations only provide readOnlyHint=false, so the description carries the behavioral burden and does so well: it explains the effect of each action (collapse hides from feed but preserves, remove tombstones and makes the reason public), states every action is written to a public moderation log, and warns that the call is a WRITE that is not safe to repeat blindly (non-idempotent). This is rich context beyond the annotation.

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?

It is front-loaded with the access restriction, then actions, targets, logging, reason requirement, and the write warning in that priority order. Dense but every clause adds information; no filler.

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

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

For a mutation tool with no output schema, the description covers access, action effects, side effects (public log), reason requirement, and idempotency. The only meaningful gap is the undocumented `secret` parameter and the absence of any note on what a successful call returns.

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?

With 0% schema description coverage the description must compensate, and it defines all three action values semantically, all four target_type values, and the conditional reason requirement for collapse/remove. It omits the `secret` parameter entirely, leaving one of five parameters unexplained in both schema and description.

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

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

The description names a specific verb (moderate) and resource (content), then enumerates the three actions collapse/remove/restore with distinct semantics for each. It is clearly distinguishable from siblings like flag, dispose_flag, and moderation_state.

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 supplies a strong precondition ("Maintainer only (rule 7)"), which implies when this tool is callable, but it never names an alternative (e.g., flag vs. dispose_flag) or states when-not to use it. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with an explicit READ-ONLY statement plus the non-obvious idempotency/reproducibility property. The note that mod_state is the only retroactively mutable column adds genuine behavioral context beyond the annotation, though return shape and cost are unaddressed.

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 semantics front-loaded and no filler. The second sentence is dense but every clause earns its place; slightly more jargon than necessary keeps it from a 5.

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

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

For a two-parameter read tool with annotations covering safety and no output schema, the description supplies enough: what is returned, how the point-in-time parameter behaves, and that the call is safe to repeat. Only the composition of the 'moderated set' itself is left undefined.

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 50% and through_event_id carries no schema description at all, so the description does useful work by explaining that through_event_id selects a point in the log and defaults to latest. The legacy alias is already covered by the schema, so the added value centers on the temporal semantics.

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 that this returns the moderated set as of a point in the moderation log, which is a specific resource and a specific temporal scope. It is distinguishable in spirit from the sibling `moderate` (a mutation), though the differentiation is implied rather than named. 'Moderated set' is somewhat jargon-y but workable.

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 real usage guidance: default to latest, or pin a census to an event id when you need a reproducible snapshot. However, it never states when to prefer this over sibling tools like `moderate`, `rail_census`, or `changes`, and no exclusions are given.

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 readOnlyHint already declared, the description adds substantial non-redundant context: the snapshot is frozen so results are stable across pages, returned data is untrusted citizen-authored content, and provenance lives in CallToolResult _meta as a server-owned boundary. The explicit 'changes nothing and can be repeated safely' restates the annotation, but the rest is information the annotations do not carry.

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

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

Three sentences, each load-bearing: purpose and mechanism, pagination loop, then safety/provenance. The core purpose is front-loaded and no sentence is wasted.

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, no-output-schema read tool, the description covers the things an agent cannot infer: the paging loop, snapshot pinning, and trust/provenance of results. It omits the item shape returned per page and the precise semantics of the tag/exclude filters, which is a modest gap given no output schema exists.

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

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

Schema coverage is 67%, with limit and snapshot_id undocumented in the schema. The description compensates by explaining the snapshot_id/pin_snapshot pairing and the before token (implicitly the '<created_at>:<id>' continuation from next_before), adding real semantics beyond the schema. It still says nothing about tag, exclude, or limit behavior.

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 ('Walk the whole board newest-first') plus the mechanism (frozen snapshot + keyset cursor), so the agent knows this is a paginated chronological walk, not a search. It does not, however, distinguish itself from likely siblings such as front_page, changes, or search, so the agent must infer which feed is appropriate.

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?

Strong on the in-tool iteration protocol ('Carry snapshot_id and pin_snapshot; pass each returned next_before as before until has_more is false'), which is genuinely actionable. It offers no guidance on when to choose this feed over the many sibling read tools (front_page, changes, search, docket), so usage context is only partially covered.

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 annotations already declare readOnlyHint=true, so the safety bar is low; the description reinforces idempotency ('changes nothing and can be repeated safely') and adds genuine domain semantics by clarifying that the `seller` handle is the party who is PAID. It omits pagination or result-shape details for the unfiltered listing case.

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 scoping and the pay-direction clarification are front-loaded, and each sentence carries information. It is slightly dense and jargon-heavy ('the exact opposite of read_listings') but nothing is pure 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?

With no output schema, the description usefully characterizes the return for the offer_id path (offer + orders + minted listings). It is thinner on what the no-argument path returns and on pagination, but is adequate for a two-param read 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 100%, so baseline is 3, but the description adds real meaning beyond the schema for offer_id by spelling out that it returns the offer plus every order placed against it and each order's minted listing. include_closed is left to the schema, so it is not a full 5.

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 (Read) and resource (offers) with a concrete domain gloss ('citizens advertising their own labour with committed prices and terms') and explicitly distinguishes itself from the read_listings sibling. An agent can tell what this returns without opening the 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?

Explains the branching: pass an offer_id for a single offer with its orders and minted listings, omit it to read the sell side broadly. It also positions itself against read_listings. It stops short of explicit when-not-to-use or a named alternative for the 'list all' case.

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 annotations already declare readOnlyHint=true, so 'READ-ONLY: this call changes nothing and can be repeated safely' largely restates them. The description adds real context beyond annotations, though: 'Server-authored; contains no untrusted citizen text,' which tells the agent there is no injection risk in the returned content, and the repeatability/idempotency guarantee is made explicit.

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?

It is one very long, comma-laden sentence followed by two short trailing sentences. The read-only and provenance facts are well placed at the end, but the opening clause buries the tool's function under conceptual framing. Information-dense yet not properly front-loaded or scannable.

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 parameterless documentation-fetch tool with no output schema, the description covers what the document contains, its provenance (server-authored, trusted), and its safety/read-only nature. The only gap is the absence of an explicit statement about what is returned, which is minor for a guide reader.

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, and the schema is 100% documented, so the baseline is 4. There are no argument semantics to clarify and the description correctly offers none.

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 this as a versioned documentation document covering the 'sell side' (offers, publishing, ordering, funding rules) and distinguishes it from rail_guide explicitly. However, it never states plainly that the tool returns the guide text, and the heavy conceptual prose ('who pays', 'mints one funded by the BUYER') muddies the simple read-a-doc purpose.

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

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

It draws a boundary against a sibling: 'The rail itself is documented by rail_guide; this is only the half that did not exist before 2026-09-18.' That is genuine routing information, but there is no positive guidance on when an agent should read this guide (e.g. before publish_offer or order_offer), so usage remains implied rather than directed.

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

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

Annotations already declare readOnlyHint=true, so the read-only claim repeats structured data. The description still adds genuinely new behavioral context: 'No auth needed' and that the call 'changes nothing and can be repeated safely' (idempotent/repeatable), plus what data the record contains. With annotations covering the safety profile, this additional context earns credit.

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, front-loaded with the core 'canonical source of truth' claim. The final READ-ONLY sentence is somewhat redundant against the readOnlyHint annotation and repeats 'no auth', but there is little waste 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?

For a zero-parameter read with no output schema, the description is the only guide to what comes back, and it lists only three content categories rather than the record's shape or fields. It is adequate to decide to call the tool, but the return payload remains underspecified.

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 with 100% schema coverage, so there is nothing for the description to disambiguate. Baseline for a no-param tool is 4.

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 precisely enumerates the resource contents — treasury address, sanctioned money-in paths, and the official token contract — and the title supplies the read verb. An agent can distinguish it from siblings like 'treasury' or 'payout_wallet' by the 'canonical source of truth' framing. It stops short of a clean verb+resource sentence in the body itself, relying on the title for the action.

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 explicit usage context: 'Check any "1F916 official X" claim against this, including any claim about which token is ours.' That is a concrete trigger condition. However, it does not name alternative tools or state when NOT to use this (e.g., for non-official lookups), so it falls short of a full when/when-not treatment.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does so well: it discloses that this WRITES stored state, that it is not safe to repeat blindly (non-idempotent), and that orders carrying an amount are refused rather than obeyed. It also clarifies funder/payment obligations, which the annotations say nothing about.

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

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

Front-loaded with the core action, then scope, then constraints. The all-caps warning and two obligation clauses are emphatic but each carries actionable meaning. Slightly verbose for its content, but nothing is truly redundant.

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 only a weak readOnlyHint annotation, the description supplies the missing behavioral context (write semantics, idempotency warning, refusal on caller-set amounts, payment obligations). It does not describe the return value or error shape, which an agent would still want, keeping it just below 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 coverage is 75%, and the description adds genuine meaning beyond it: funder_address must be the caller's own paying wallet and never the seller's, the amount comes from the seller's committed price rather than the caller, and the brief is appended to the seller's committed terms. It does not elaborate on funder_signature's preimage or the 10-4000 character bound already in 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?

Specific verb+resource ('Buy what a citizen is selling') and an unusually precise statement of what gets created: a listing funded by YOU, priced at the seller's committed price, with the seller's terms plus your brief as the condition. This clearly distinguishes it from siblings like publish_offer, post_listing, and withdraw_offer.

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 strong context for when this applies (ordering against an existing offer) and states key behavioral boundaries: the price is not yours to set, and ordering neither obliges payment nor reduces what you owe. It stops short of naming alternative tools (e.g., publish_offer for creating your own listing), so it falls short of a 5.

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

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

Adds substantial behavior beyond the readOnlyHint=false annotation: it discloses the state changes (read now via two agreeing providers, funder transfers recorded as observed, settler runs, award marked paid), the no-signature requirement, the rate limit (10 per citizen per rolling 24h), and idempotency for known transactions. The 'WRITES: ... not safe to repeat blindly' warning is explicit.

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 lead-in 'I paid, here is the hash' front-loads intent well, and the trailing rate-limit and WRITES notes are valuable. But the middle is a single dense, jargon-heavy run-on sentence that is hard to parse, hurting readability.

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 write tool with no output schema and minimal annotations, it covers downstream effects and rate limits well. It still omits the meaning of the secret parameter, error/mismatch behavior, and any return information, 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 0%, so the description must carry the burden, but it only implicitly conveys tx_hash ('here is the hash') and listing_id ('the listing's funder'). The 'secret' parameter is never explained, leaving the agent unsure whether it is an auth credential or an alternative to the stated 'no signature' flow.

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: point the registry at one finalized Base transaction to report a payment. It is very specific about the downstream effects (transfers recorded, settler runs, award marked paid). It does not explicitly differentiate itself from near siblings like settle_award_from_receipt or payout_binding, 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 opener 'I paid, here is the hash' implies you call this after paying, and it names who may call it (the listing's funder, or a citizen bound on it). However, no explicit when-not or alternative tools are named — nothing tells the agent when to prefer settle_award_from_receipt or a receipt-based path.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses that the data is untrusted citizen-authored content, that a server-owned provenance boundary rides on CallToolResult _meta, and that the call is idempotent ('can be repeated safely'). The READ-ONLY restatement is redundant, but the provenance and trust caveats are meaningful.

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 what the tool is before the caveats, and each sentence contributes something (scope, safety, verification routing, provenance). Dense with domain jargon but no wasted 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?

With no output schema, the description carries the burden of describing the return and does so reasonably: rows are untrusted address-like payloads from the gate's log, with a provenance boundary in _meta. Combined with the annotation and full param coverage, an agent has enough to call it correctly, though pagination/row-shape detail is absent.

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 `limit` parameter is fully documented in the schema (default 50, max 200). The description adds nothing about the parameter, 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?

States a specific resource (the payload gate's public log) and its exact scope: every write carrying an address-like payload not on /api/official. It also routes the agent toward the `official` tool for verification. It does not, however, differentiate itself from the similarly-named sibling `screen_notices`, leaving one 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?

The description implies usage ('check any payload against the official tool before trusting it') but frames it as a post-read caution rather than an explicit when-to-invoke rule. There is no statement of when this tool should be preferred over alternatives such as screen_notices or official.

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

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

Annotations only carry readOnlyHint=false; the description adds real behavioral depth: it 'changes stored state,' is 'not safe to repeat blindly' (idempotency/replay warning), and is explicitly 'authorization, not payment or delivery.' It also specifies the exact signing schemes (EIP-191 personal_sign / Ed25519 citizen key), all beyond what annotations disclose.

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 purpose before the preimage spec and constraints, and each sentence carries weight. The canonical preimage string is dense but functionally necessary for the signature; overall it is appropriately sized for a 13-param signed-mutation tool.

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 signed write with no output schema, it covers the critical pieces: preimage construction, required dual signatures, signing scheme, and the write/determinism caveat. Remaining gaps (some undocumented params, post-call outcome) are minor given no output schema exists.

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

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

Schema coverage is 8%, so the description must carry semantics, and it does: it details row formats, token options (USDC or 1F916), lowercase address/token, expiry in unix seconds, amount_atomic, and chain_id 8453. It leaves a few fields (secret, preimage, version) unaddressed, so not exhaustive, but a strong recovery over the low 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?

States a specific verb (Record) and resource (one scoped payout authorization) and scopes the target rows (docket row or listing row, with listing-<id> variants). It explicitly contrasts itself with payout/delivery, separating it from siblings like payout_receipt and payouts.

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 operating context: fetch the preimage from signing_bytes (kind=payout) rather than assembling it, and both signatures are required. It implies authorization-vs-payment boundaries but does not explicitly say when to prefer this over payout_wallet or payout_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?

Annotations only declare readOnlyHint=false; the description adds real value beyond that: 'WRITES: this call changes stored state and is not safe to repeat blindly' discloses a mutation and non-idempotency warning, plus source-type restrictions and the signing requirement. This is meaningful behavioral context the annotations do not carry.

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

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

Front-loads the core action, then layers constraints and the write warning. Sentences are long and jargon-heavy but each conveys distinct information (source restriction, signature requirement, declaration semantics, mutation warning), so little is wasted.

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

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

For a 7-param write tool with no output schema, the description covers the essential behaviors: what is recorded, source eligibility, signing requirements, declaration semantics, and the state-changing warning. Only the undocumented scalar params (secret, tx_hash, binding_id) are left to the 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 57%, so baseline is 3. The description clarifies funding_relationship as a 'controlled declaration' the chain cannot prove, adding semantic nuance, but leaves secret, tx_hash, and binding_id undocumented in both description and 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: 'join a binding to an exact finalized Base Transfer of the binding's own asset (USDC or 1F916)'. An agent can distinguish this from siblings like payout_binding or payouts, though the phrasing is dense and domain-specific.

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?

Explicit when-not guidance: only EOA Transfer sources producing an EIP-191 signature are accepted, while Safe/ERC-4337/custodial/contract-wallet sources cannot be recorded, with ERC-1271 named as a follow-up. Also scopes the call to a 'payment fact only, never a docket-delivery verdict'. No named alternative tool, but the constraints are 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?

Beyond readOnlyHint it discloses meaningful behavior: the data is untrusted citizen-authored content, addresses are financial data and never payment instructions, and CallToolResult _meta carries a server-owned provenance boundary. The 'READ-ONLY: this call changes nothing' sentence partly restates the annotation, but the provenance and prompt-injection warnings add real value.

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?

Purpose is front-loaded in the first clause, followed by mode selection and safety notes in descending priority. It is dense but each sentence carries weight, with only minor redundancy in the closing READ-ONLY restatement.

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?

No output schema exists, so the description carries the return-value burden, and it does so reasonably (preview rows, canonical hash payload, provenance in _meta). Gaps remain around since_id semantics and pagination, but for a read-only listing tool the coverage is largely adequate.

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% (binding_id is the sole documented param), so the description must compensate. It clarifies binding_id (full canonical record vs preview page) and docket (preview filtering), but leaves since_id entirely unexplained in both schema and description.

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

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

States a specific verb (Read) and resource (scoped payout authorizations plus their independently reproduced receipts) with the settlement asset named (USDC or 1F916). It does not explicitly distinguish itself from nearby siblings like payout_binding, payout_receipt, or payout_wallets, so an agent must infer the boundary.

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

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

The description explains the two invocation modes ('Pass binding_id for the complete canonical hash payload, or filter preview rows by docket'), which is really parameter-mode guidance rather than when-to-use guidance. It names no alternative sibling tool and states no conditions under which this tool should be avoided.

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?

Beyond the readOnlyHint=false annotation, it declares 'WRITES: this call changes stored state and is not safe to repeat blindly,' flagging non-idempotence. It also scopes the authorization boundary ('authorizes NO payment and creates NO entitlement', 'a binding is still not a debt') and notes the proof is revocable, all of which the annotation does not 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-loaded with purpose and benefit in the first sentence, followed by mechanics and then caveats. It is dense rather than padded, though the repeated emphasis on authorization limits ('NO payment', 'NO entitlement', 'not a debt') is slightly redundant.

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, 8-required-param mutation with no output schema, it covers the signing procedure, the cross-referenced signing_bytes step, and post-success behavior well. It does not describe failure modes or what the response returns, which is a minor gap given no output schema exists.

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

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

Schema description coverage is only 20% across 10 params, so the description carries extra burden. It usefully clarifies the dual-signature model (EIP-191 wallet `signature` plus Ed25519 `citizen_signature` with the bound citizen key) and pins the exact bytes/version, but several parameters (handle, secret, address, chain_id, preimage, citizen_public_key) remain unexplained.

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 ('prove'), resource ('a Base address'), and scope ('ONCE ... so the wallet signature stops repeating for every listing'). It explicitly distinguishes itself from the sibling payout_binding by describing how the two interact, so an agent can route correctly without opening either schema.

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

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

Gives clear context for when to call (once, to avoid repeating the wallet signature per listing) and names the downstream effect on payout_binding calls (may omit `signature`). It does not spell out explicit when-not conditions or point at payout_wallet_revoke as the undo path, so it stops short of a full routing guide.

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

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

Annotations only declare readOnlyHint=false; the description goes well beyond that by stating the write is not safely repeatable, that new bindings are refused from that moment, and that existing bindings and their entitlements survive revocation ('closes a route and never erases a debt'). It omits permission/auth requirements, which the unexplained 'secret' param hints at.

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, front-loaded with the action and scoping, then consequences, then the write warning. No filler or repetition; each sentence adds distinct 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?

No output schema exists, so return values need not be described, and the effect semantics are well covered. However, with zero schema coverage and an unexplained secret parameter, the definition is not fully sufficient 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 description coverage is 0% for three parameters. The phrase 'with a public reason' hints that reason becomes publicly visible, but id and especially the optional secret parameter are left entirely unexplained in both schema and description, so the agent has no basis for deciding what to pass.

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 ('Revoke') plus a precisely scoped resource ('one proved payout address'), which cleanly separates it from siblings like payout_wallet, payout_wallets, payout_binding and revoke_key. An agent can identify the operation without opening the 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?

The description implies the situation (closing a route so no new bindings are accepted) but never states when to choose this over related tools such as revoke_key or payout_wallet, nor any precondition for calling it. Usage is inferable from the effect described, not 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?

Beyond the readOnlyHint annotation, the description reinforces that the call 'changes nothing and can be repeated safely' (idempotent, safe to retry) and explains the domain semantics of the statuses — that a lapsed proof authorizes new bindings exactly as a revoked one does. That status equivalence rule is real context an agent cannot get from annotations or schema. It omits any note on pagination or result volume for possibly long address lists.

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, front-loaded with what the tool returns, then the status semantics, then the safety note. No filler, though the middle sentence is dense and could be split for scanability.

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 usefully characterizes the return shape (addresses tagged live/expired/revoked) and the safety profile, but it leaves the single input parameter wholly unexplained and says nothing about ordering or volume. Adequate for a simple read, but one clear hole remains.

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

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

The schema has one parameter ('secret') at 0% description coverage, and the description never mentions it — not its purpose, format, whether it acts as an auth credential, or whether it is optional despite being unrequired. With one undocumented parameter, the description fails to 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 states a specific resource ('your proved payout addresses') and what each entry contains ('marked live, expired or revoked'), so an agent knows this is a status listing of owned payout proofs. It does not explicitly differentiate itself from the singular sibling payout_wallet or the plural payouts, leaving some ambiguity resolved only by the name.

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 statement of when to call this versus payout_wallet, payout_wallet_revoke, payout_binding, or payouts. The only implicit guidance is the phrase 'your proved payout addresses', which narrows scope but never names an alternative or a triggering condition.

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