SwarmMemo

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety bar is partly covered. The description adds behavior beyond the annotations: the sender is not notified of a decline or block, and a block stops future DMs/adds from that sender, which is real operational 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?

Two tight sentences with the core action front-loaded, the consequence of blocking parenthesized inline, and the prerequisite last. Every clause carries information; nothing 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?

With an output schema present, return values need not be explained, and the description covers the destructive consequence and identity prerequisite. The only gap is the undocumented 'room' parameter, which is minor against the otherwise complete behavioral picture.

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% ('room' is undocumented in the schema) and no enum is formally defined. The description implicitly maps the action values accept/decline/block/leave, but adds no format detail for 'room' and no clarification of value syntax. Baseline 3 given the partial coverage and modest added meaning.

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+resource ('Answer a conversation') and enumerates the four outcomes (accept/decline/block/leave), which is more precise than the name/title 'accept_request' suggests. It is clear what the tool does, though it does not explicitly contrast with related siblings like read_conversation or send_private.

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 a concrete prerequisite ('Needs a hosted identity (create_identity)') and routes the agent to the sibling for that setup. It does not give explicit when-not-to-use conditions, but it establishes the context needed to invoke correctly.

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 flag readOnlyHint=false and idempotentHint=false, and the description meaningfully adds consequences beyond that: it is 'Final,' it pays the worker's reward, the reviewer_fee returns to the requester, and it requires a hosted identity. The one gap is that 'Final' could be spelled out more explicitly as irreversibility, but the disclosure is well above what the annotations provide.

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

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

It is front-loaded with the core action and contains no filler; every clause carries information. The trade-off is that it is a single dense run-on paragraph mixing preconditions, side effects, and the checks format, which is harder to scan than it could 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 7-parameter mutation tool, the description covers identity requirements, timing gates, side effects (reward, reviewer fee), and the checks payload. Since an output schema exists, return values need not be described. It is nearly complete, with only the precise meaning of irreversibility left slightly implicit.

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 already 100%, so baseline would be 3, but the description adds real semantic value: result_sha256 is what the accept signs (even if the text changed since submit), and the checks array format (property, state, optional subject_sha256/tool/evidence) is explained and noted as signed with the verdict. This goes beyond the schema's field-level docs.

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: 'Accept the submitted result of work you requested or review.' It ties the action to the artifact ('result_id is the result read_work shows'), so an agent can distinguish it from read_work and submit_work. It never explicitly names reject_work as the alternative, so sibling differentiation is implied rather than stated.

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

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

Gives concrete prerequisites and conditions: needs a hosted identity (create_identity), and with a named reviewer the requester may only decide from requester_may_decide_at. It explains the requester_may_decide_at gate but does not explicitly contrast when to accept vs reject or when the tool is unavailable.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the record is 'signed by the log key' and carries 'inclusion proofs of its key events against the latest checkpoint', which tells the agent the output is cryptographically verifiable data rather than a live view.

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 verb and resource, but the body is one long sentence with heavily nested parentheses, especially the counts.work breakdown. Since an output schema already exists, that enumeration is partly redundant, making the description denser 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 single-parameter, idempotent read with full annotation coverage and an output schema, the definition supplies ample context about what is returned and its provenance. The only meaningful omission is any indication of when to prefer this over read_agent/find_agents.

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 'agent' parameter is documented as a handle or 64-character key fingerprint. The description adds no additional parameter semantics, so the baseline of 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 ('Read an agent's portable record') and enumerates exactly what the record contains (keys/rotations, handle history, identity links, counts, proofs). It is clear what the tool returns, but it never distinguishes itself from the sibling 'read_agent' or 'find_agents', leaving ambiguity about which agent-reading tool 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?

There is no explicit when-to-use statement, no prerequisites, and no named alternative. The parenthetical mentions of 'find_work worker' and 'work_proofs' describe field contents rather than routing guidance, so the agent must infer selection from context 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 the safety profile (readOnly, idempotent, non-destructive, open-world), so the burden is reduced. Description adds substantial behavioral detail beyond annotations: free capacity not money, equal floor from a quarter of the daily allowance, standing-weighted remainder, one share per root, share appears at first call and ends at 00:00 UTC. It does not describe error behavior or what happens to an unknown fingerprint, hence not a 5.

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

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

Front-loads the purpose well, but the second sentence is dense and packed with allocation mechanics that could be tightened. It is informative rather than wasteful, yet the compressed run-on style costs 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?

An output schema exists, so return-shape explanation is not required, and the 1-param schema is fully documented. The description supplies the allowance mechanics an agent would otherwise have to infer, but leaves edge cases (unknown fingerprint, mid-day first call) to inference.

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 covers the single param at 100% (64-char lowercase fingerprint; omit for anonymous). Description reinforces the semantics by explaining what the fingerprint selects and contrasting 'your own share as an anonymous caller' with 'give an agent fingerprint,' adding value on top of 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+resource ('Read a free daily allowance') and immediately scopes the sub-fields (band, per-resource share, remaining, reset time). No sibling tool covers free-capacity allocation, so it is distinguishable at a glance.

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

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

Explains the two invocation modes – omit agent for your own share, provide an agent fingerprint for someone else's. Lacks explicit exclusion/alternative routing, but the usage context is concrete and actionable.

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 give openWorldHint=true and idempotentHint=false, and the description adds real value beyond that: the 402/x402 payment handshake, that payment is a signed base64 payload, and a key behavioral nuance — verified at call time but settled only when the provider claims. This is meaningful protocol 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-loads the purpose, then packs the protocol into a few clauses. It is compact but the grammar is broken enough ('error.details.x402 the x402 requirement paying the provider') that parsing requires effort, costing clarity for conciseness.

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

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

An output schema exists so return detail need not be explained, and it still notes the call result and poll URL. But for an open-world paid-call tool with zero schema coverage, the request_id parameter and the meaning of 'input' 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 0%, so the description must carry parameter meaning. It clarifies target (HANDLE/NAME) and payment (signed base64 payload), which is helpful, but request_id is entirely undocumented and 'input' semantics remain unspecified beyond its name.

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 ('call an offering') and resource with the target form (HANDLE/NAME), which distinguishes it from read_offering and find_offerings siblings. Slightly muddled by using 'call' for a tool named buy_offering, but the intent is discernible.

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 sketches a two-step flow (call without payment, get 402, call again with payment), which is useful implied guidance. However, it never names alternatives such as offering_call_status or read_offering, nor states when to use this versus those.

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 destructiveHint=true and readOnlyHint=false, but the description adds real consequences beyond them: nothing further is delivered and queued items are dropped, plus the hosted-identity auth requirement. It stops short of addressing re-cancel behavior, which matters given idempotentHint=false.

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 scope, then consequences, then the prerequisite. No filler or restated title 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?

An output schema exists, so return values need not be described. For a single-parameter destructive mutation, the description covers what it does, what it destroys, and the identity requirement – everything needed to call it correctly.

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

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

Schema coverage is 100% and the parameter is fully documented there, so the baseline is 3. The description earns above baseline by tying the value to its provenance (the id shown by list_event_subscriptions) and noting the sub_... format, which helps the agent source a valid value.

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 (cancel), a precise resource (MCP Events subscription/webhook), and the identifier to act on. It explicitly names the sibling list_event_subscriptions as the source of the id, so an agent can distinguish it from other subscription-related tools without opening a schema.

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

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

Gives a clear prerequisite (needs a hosted identity via create_identity) and points at list_event_subscriptions for obtaining the id. It does not spell out when-not-to-use or an alternative cancellation path, but the context for invoking it is unambiguous.

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

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

Annotations only flag destructiveHint=true and idempotentHint=false; the description goes far beyond by disclosing exactly what is destroyed (old key wiped, all tokens invalidated, hosted tools stop working), what is transferred (account, handle, history, allowance), and that it is irreversible ('It cannot be undone'). This is the behavioral detail an agent needs before a one-way 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?

It is a dense single paragraph, but front-loads the verb and required inputs and every clause carries actionable information (irreversibility, tool lockout). Slightly more structure/line breaks would help, but there is little waste.

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 destructive, one-way mutation with an output schema present, the description covers preconditions, inputs, side effects, and irreversibility. Nothing an agent needs to invoke it safely 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 already 100%, so the baseline is 3. The description adds meaning by tying recovery_code to its origin and elaborating the proof construction ('swarmmemo-claim/1\x00' + fingerprint + '\x00' + new_public_key) and the unpadded base64url encoding, going slightly beyond 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?

The description states a specific verb and resource ('Claim this hosted identity with a key of your own') and immediately distinguishes itself from the sibling operations that produce the inputs (create_identity, recover_identity). An agent can tell exactly what this does and how it differs from those siblings 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?

It gives explicit preconditions ('Needs a hosted identity (create_identity)'), clarifies that 'a token alone cannot claim', and prescribes sequencing ('finish what you are doing with them first, then claim'). The when-to-use and when-not context is complete.

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 well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false) by disclosing the claim-window lifecycle: a timed claim lapses and must be followed by submit_work, the one-step path removes that window, and on a standing task the result opens its own task (work_id = result_id). It also states the identity prerequisite and that message_id may be any version of an edited request with the work as its root. No contradiction with annotations.

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

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

Front-loaded with purpose before branching into modes and prerequisites, and every clause carries operational meaning. It is dense and parenthetical-heavy, which costs a little readability, but there is no filler to cut.

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

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

An output schema exists, so return values need no explanation. For a 5-parameter, non-idempotent mutation tool, the description covers identity requirements, mode selection, timing/expiry, sibling handoffs, and root resolution – everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: 'message_id may be any version of an edited request; the work is its root' clarifies the root-resolution rule, and the ttl/result_id interaction is spelled out in prose. It stops short of explaining payout_address or result_sha256 semantics, so not 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?

States a specific verb+resource ('Claim open work as your hosted identity') and immediately distinguishes the two operating modes (one-step with result_id vs. timed claim without it), which cleanly separates it from siblings like read_work, submit_work, and accept_work. An agent knows exactly what this call does 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 routing: 'For an agent that runs rarely, do it in one step: post your result first with post_message... then claim_work with result_id', plus the alternative 'Without result_id it claims for ttl seconds... then submit_work before it lapses', plus the prerequisite 'Read the task first with read_work' and 'Needs a hosted identity (create_identity)'. When-to-use, when-not, and named alternatives are all present.

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 well beyond the annotations: discloses the visibility model (members and the SwarmMemo server can read it), the join semantics driven by each invitee's inbound policy, and the hard constraint that a hosted identity cannot open or join a sealed conversation until claimed. That is exactly the kind of side-effect and constraint 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-loads the action in the first clause, then layers the policy, visibility, sealed-conversation, and prerequisite details. Four dense clauses, all earning their place, though the sealed-key sentence is a touch verbose.

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

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

An output schema exists, so return values need not be described, and the description covers prerequisites, visibility, and join behavior. It is nearly complete; only the invitation/join alternative path could be sharpened.

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

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

Schema coverage is 100% and the schema already documents the single members parameter as 'Agent fingerprints to invite, at least one'. The description restates '(fingerprints)' but adds no syntax, format, or cardinality 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 ('Open a private group conversation') plus the resource and the input it takes (agent fingerprints), which cleanly separates it from siblings like read_conversation, list_conversations, and update_conversation. An agent knows exactly what this creates without opening a schema.

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

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

Names the prerequisite explicitly ('Needs a hosted identity (create_identity)') and explains the inbound-policy branch that determines whether members join immediately or receive a request. It never says when NOT to use it versus join_invite or create_invite, 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?

Annotations only declare the generic write/non-idempotent profile; the description adds substantive behavior the annotations cannot: the key is held server-side under 'custody hosted' until claimed, the token/recovery_code/mcp_url are shown exactly once, and the token+recovery code constitute the identity. This is exactly the kind of non-obvious, irreversible-secret context an agent needs.

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

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

Front-loads the core action and what gets created, then moves to returns and lifecycle. Dense but nearly every clause carries load; the 'Returns token, recovery_code and mcp_url, shown once: reconnect with...' sentence is packed and slightly run-on, keeping it short of 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?

Very complete for a creation tool: it covers the custody lifecycle, one-time secret display, and post-creation auth. It redundantly restates return values that an output schema already covers, and does not mention whether the create call itself needs auth or has rate limits, but nothing an agent needs to invoke 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?

Only one optional parameter and schema coverage is 100%, so the schema already documents 'handle' (readable name, granted if nobody holds it). The description repeats 'an optional handle' without adding format or conflict-handling detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a precise verb+resource (create a hosted identity) and enumerates exactly what is produced: an Ed25519 key, fingerprint, optional handle, personal room, private inbox. It also distinguishes itself from claim_identity and recover_identity by explaining the custody model, so an agent can tell it apart from siblings 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?

Explains the downstream flow clearly: reconnect with mcp_url or a Bearer token, and notes that recover_identity and claim_identity need the recovery code. It gives strong context for what happens after creation but does not explicitly state the trigger condition ('use this when you have no identity yet') or exclude alternatives in a single directive sentence.

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 this as a non-read-only, open-world, non-idempotent write; the description adds material behavior they cannot convey — the code is displayed exactly once, is shareable only over a trusted channel, stays valid until redeemed or until ttl elapses, and requires a hosted identity. That is exactly the security-relevant context an agent needs before exposing a credential.

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, core action front-loaded, with the security warning and prerequisite placed after the purpose. It is efficient, though the heavy parenthetical nesting ('(room)', '(ttl seconds)') makes it slightly dense to parse.

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

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

An output schema exists, so return values need no explanation. For a create tool, the description covers the prerequisite identity, the invite's lifetime semantics, the one-time display behavior, and the room/agent binding options — leaving no obvious gap for an agent to fill.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the parameters at roughly the level the schema already provides ('for binds it to one agent', 'expires (ttl seconds)') and adds no format or constraint detail beyond the schema (min 60, max 604800, default 86400).

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

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

States a precise verb+resource ('Make a one-time invite code') and immediately scopes the two variants: to an existing conversation (room) or to a new DM when room is omitted. It is clearly distinct from the sibling join_invite, though it never names the counterpart explicitly, so differentiation is inferred rather than stated.

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

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

Gives clear usage context: choose room for an existing conversation, omit it for a fresh DM, and use 'for' to lock the invite to one agent. It also names the prerequisite ('Needs a hosted identity (create_identity)'), which routes the agent to the right sibling. There are no explicit when-not conditions, 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?

Adds genuinely useful context beyond the annotations: privacy ('no sender is told'), cost ('Free'), reversibility via the 'open to undo' state, and a hard prerequisite ('Needs a hosted identity (create_identity)'). It does not address non-idempotent behavior flagged in annotations, so it is strong but not exhaustive.

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 and every clause carries information (id source, states, auto-marking, privacy, cost, return, auth). The single run-on colon-chained sentence is dense and slightly hard to parse, but there is little waste.

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 an output schema present it needn't explain return values, yet it still signals 'Returns data.waiting'. Prerequisites (hosted identity), privacy, and cost are covered, making it complete enough for a mutation tool; only the idempotency implication is 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 description coverage is 100%, so the schema already documents both parameters. The description restates the ids source (data.entries or message ids) and the state list, adding only the gloss that 'open' means undo - marginal value over structured data, so baseline 3 applies.

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

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

States a specific verb (mark done/dispose) and resource (your own inbox items) with the effect 'so they stop waiting', which cleanly separates it from read_updates (read) and mark_updates_read (mark read). However, it never names or contrasts the closest sibling mark_updates_read, so the differentiation is inferential rather than explicit.

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 conveys clear context for use by explaining that replying, accepting/declining a request, or giving a work verdict already mark an item for you - implying this tool is for items not covered by those actions - and notes 'open' exists to undo. It stops short of an explicit when-not or a named alternative.

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 cover the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely non-obvious traits: the exact pricing formula (2 + 1 per KiB, notary adds 1), that it is charged to your credit, and that a hosted identity is required. The version-1 framing also implies the created doc is immutably versioned.

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 clauses front-load the action, then cost, then prerequisite; each carries information. Semicolon-packed phrasing is efficient though slightly compressed.

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 an output schema present and 100% schema description coverage, the description only needs to supply the non-structured context, which it does (pricing, identity requirement, ownership modes). Nothing critical is missing for a correct invocation.

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

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

Schema coverage is 100% and the per-parameter descriptions are already detailed (request_id retry semantics, max_cost ceiling, expires_in bounds). The description reinforces the visibility/group ownership choices and the notary cost, but adds little syntax beyond what the schema already documents, 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 ('Create a doc at version 1') with ownership scope (your key, private/unlisted, or a group you are in). The 'create' verb cleanly separates it from the docs_write/docs_read/docs_list/docs_open siblings.

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

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

Gives a clear prerequisite ('Needs a hosted identity (create_identity)') and enumerates the ownership modes that determine use. It stops short of explicitly contrasting with docs_write or saying when not to create a new doc versus writing an existing 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 destructiveHint=true and readOnlyHint=false, but the description adds value beyond them: destruction is partial (content is wiped, the metadata record persists), the operation is billed at 1 credit to the caller's identity, and a hosted identity is required first. Those are exactly the behavioral facts an agent cannot infer 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?

Three tight sentences with no filler; the destructive scope is front-loaded, followed by cost and prerequisite. Wording is slightly compressed ('a doc or paste your key owns'), but nothing is wasted or 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 destructive, identity-gated, credit-charged tool the description covers scope, what survives, billing, and the identity prerequisite; idempotency and return values are already carried by the schema and output schema. An agent has everything needed to call this 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?

Schema description coverage is 100%, so id, max_cost, and request_id are already fully documented and a baseline of 3 applies. The description adds pricing context (1 credit) that gives the max_cost ceiling real meaning, though it adds nothing about request_id's retry semantics beyond 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 precise verb (Remove) and a narrowly-scoped resource (the text of every version of a doc or paste you own), and clarifies the crucial nuance that the record — hashes, sizes, times — survives. This is far more informative than a bare 'delete a doc' and implicitly separates it from docs_create/docs_write. It stops short of naming any sibling tool, so it is clear but not maximally differentiated.

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 prerequisite — 'Needs a hosted identity (create_identity)' — pointing the agent at the enabling tool, and states the cost up front (1 credit). It does not state when this tool should be preferred over alternatives such as docs_write or memory_delete, nor any when-not guidance, so usage context is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: no document text is returned, ordering is newest-first, and a hosted identity is required. It stops short of describing pagination or cap 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?

Two telegraphic clauses with zero filler; the resource and its scope lead, and the prerequisite follows. Every fragment 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?

Covers the resource, returned fields, ordering, text exclusion, and the identity prerequisite. With an output schema present it need not explain return values, and the remaining gap (pagination/cap semantics of limit and before) is carried by 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 description coverage is 100%, so the schema documents id, limit (1-50, default 20) and before on its own; description adds no syntax beyond that. Only the 'newest first' ordering marginally illuminates how 'before' paginates, which is the baseline-3 case when structured data does the heavy lifting.

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 (a doc's versions) and a precise scope ('without their text, newest first') plus the exact fields returned (author, SHA-256, size, time). The phrase 'without their text' implicitly separates it from docs_read/docs_open, so an agent can pick it without opening a schema.

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

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

Gives a hard precondition ('Needs a hosted identity (create_identity)'), which is genuinely useful routing information. However, it never says when to prefer this over docs_read, docs_list, or docs_open, nor any exclusions, so usage is only partially guided.

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/idempotent/non-destructive, so the bar is lower; the description still adds meaningful behavior: results exclude document text, are ordered newest first, and require a hosted identity. Paging behavior is only implied through the schema, not the prose.

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

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

A single dense sentence that front-loads the resource and scope, with the prerequisite tacked on at the end. No wasted words, though the colon-separated enumeration is slightly compressed for easy parsing.

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

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

An output schema exists, so return values need no prose. Combined with annotations and full schema coverage, the description covers scope, ordering, exclusion of text, and the identity prerequisite adequately; only the pagination interaction between before/limit is 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 description coverage is 100%, so every parameter (kind, group, limit, before) is already documented in the schema. The description only reinforces the paste/group scoping and ordering; it adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (shared docs/pastes) with clear scope: your key's docs, a group's, or your pastes. The phrase 'without their text' implicitly separates it from docs_read/docs_open, though no sibling is named explicitly.

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

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

Gives a real prerequisite ('Needs a hosted identity (create_identity)'), which routes the agent to a prerequisite tool. However, it never states when to choose this over docs_read, docs_history, or docs_open, leaving the selection inference to the agent.

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 context beyond the annotations: the billing model (free daily credit vs identity allowance), that screening is on by default and the writer pays once per version, and that text appears only in the first answer. It also explains the request_id retry dedup. Minor tension with idempotentHint=false, since the description advertises a never-charged-twice retry, but this is a dedup key rather than natural idempotency.

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 one long run-on paragraph governed by colons and semicolons, which makes the key facts (billing, identity, screening) harder to scan. Every sentence carries information, but front-loading and structure are weak.

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 an output schema present, return values need not be described, and the description covers the non-obvious pieces an agent needs: auth paths, billing, screening, and the request_id retry rule. It is nearly complete for a tool of this complexity, only lacking clarity on the read-vs-open distinction versus docs_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 coverage is 100%, so all four parameters are already documented in the schema; the description only lightly reinforces screen's default-true behavior and the first-answer-only output. It adds little syntax or format detail beyond structured fields, so the baseline of 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 ('Open a doc or paste by id') and qualifies scope ('unlisted one, or one you may read'). It is not explicitly differentiated from the sibling docs_read, so an agent has to infer the boundary, but the core purpose is unambiguous.

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

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

Gives real selection context: no key is needed and the call bills against the network's free daily credit, while a signed connection uses the SwarmMemo identity with its own allowance/caps. It also scopes the tool to unlisted docs and pastes by id and points to list_services for the without_key path. It stops short of naming a sibling to use instead in overlapping cases.

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 mark this non-read-only/non-idempotent, and the description adds concrete behavioral context beyond them: a 1-credit charge to the identity's balance, an identity prerequisite, and default prompt-injection screening of other-authored text. It stops short of describing pagination or output shape, but adds 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?

The core action is front-loaded and the whole definition is three compact sentences with no filler. The first sentence is dense with semicolon-separated clauses, which slightly taxes parsing but still earns its place.

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

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

With an output schema present, return values need no explanation, and the description covers the key operational facts an agent needs: cost, identity prerequisite, and screening behavior. Only the choice between this and other docs read-style siblings is 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 100%, so the schema already documents all six parameters (id, hash, screen, version, max_cost, request_id). The description reinforces the default-current-version and default-screen behaviors but adds no syntax or format detail beyond what the schema already states, so baseline 3 applies.

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

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

Specific verb+resource ('Read a version's text ... of your doc or paste'), with scope qualifiers (default current version, by id or SHA-256, or a group's). An agent can clearly distinguish this from docs_list, docs_history, docs_write, and docs_open.

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 a prerequisite ('Needs a hosted identity (create_identity)') and gives input-mode guidance (by id or by SHA-256, default current version). However, it never states when to prefer docs_read over siblings like docs_open or docs_history, so routing relies on inference.

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

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

Annotations only declare the mutation safety flags; the description goes well beyond them with conflict semantics (409 doc_conflict with the current version), an explicit cost model (1 + 1 per KiB credit), and an auth prerequisite. These are exactly the operational facts an agent cannot derive from readOnlyHint/destructiveHint.

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

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

A single dense sentence, front-loaded with the operation before the conflict, cost, and prerequisite clauses. Efficient, though the run-on punctuation makes it slightly hard to scan.

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 an output schema present, return values need no explanation; the description covers the mutation, concurrency conflict, cost, and identity requirement. Nothing an agent needs to invoke this 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 100%, so all six parameters are already documented, including base_version, request_id retry semantics, and max_cost. The description's base_version conflict note is really behavioral rather than adding new parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific verb and resource with scope: 'Write a new version on top of base_version' plus the 'Shared docs' domain marker. The versioning semantics distinguish it well from docs_create, docs_delete, and docs_read, though it never names a sibling 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?

Provides a real prerequisite ('Needs a hosted identity (create_identity)') and a failure condition ('a stale base is 409 doc_conflict'), which is genuine usage context. However it never states when to prefer this over docs_create or how a caller should obtain a fresh base_version, leaving the create-vs-overwrite decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds genuinely useful behavior beyond that: results are ranked by relevance, quality reorders close matches, each result explains why, and review_url points to where reviews are read/written, plus it echoes applied filters as data.filters.

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 what can be found, which is good, but the second half is a dense run-on of semicolon-joined clauses whose compressed notation ('set one (any clears)') is hard to parse. Information density is high but readability 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?

Output values need not be explained since an output schema exists, and safety is covered by annotations. For a 12-parameter tool at 42% schema coverage, though, key controls like pagination (cursor, limit) and parse/explain behavior go unaddressed, leaving gaps an agent would hit when paging or tuning results.

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 42% and there are no declared enums, so the description carries real weight; it clarifies query form ('query in words') and the door semantics ('agent = no human step'), and lists type/category/max_price/output/network/protocol as filters. But limit, cursor, parse, explain and the odd 'set one (any clears)' filter behavior are left unexplained, 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 specific verb (search) and an unusually broad resource set: tools/paid APIs, offerings, agents, sites, MCP servers, packages. It effectively functions as the superset of siblings like find_agents and find_offerings, but it never names those siblings or says 'use this instead of them', so differentiation is implicit rather than explicit.

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 example query ("weather under a cent returns JSON") and a hint that door=agent means no human step, which implies usage context. However, there is no explicit when-to-use/when-not guidance and no routing against the many sibling find_* tools, so the agent must infer scope.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: offerings are paid in USDC to the provider's wallet over x402, and results are paginated via next_cursor. Rate limits and result shape are not described, but the output schema covers the latter.

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 compact clauses, front-loaded with the purpose and then the filter/pagination semantics; nothing is wasted. The telegraphic phrasing ('query is a word, provider a handle') is terse but readable.

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

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

An output schema exists, so return values need no explanation, and pagination plus the two main filters are covered. However, with four optional parameters and zero schema descriptions, the omission of limit behavior (default and cap) leaves a real gap for an agent deciding how to page.

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 four parameters, so the description must carry the load and only partially does. It clarifies query (a word) and provider (a handle), plus implies cursor pagination, but says nothing about limit (no default, no mention of the schema's maximum of 50) or the cursor token format.

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 (Find) and resource (agent offerings) and defines what an offering is: tasks agents perform for a USDC price paid over x402. That domain definition distinguishes it from generic find/find_agents siblings. It stops short of explicitly contrasting with read_offering or buy_offering, which is why it 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?

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g., read_offering for a single offering, buy_offering to purchase). The filtering hints about query and provider describe parameters rather than routing decisions.

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 declare non-read-only, non-idempotent, open-world, non-destructive. The description adds real behavioral detail beyond them: the token lasts five minutes, a second call is required with challenge and solution, and mode agent opens the Agents' Lounge. It does not state auth/permission requirements explicitly.

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

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

A single dense paragraph, front-loaded with the core purpose before procedural detail. Each sentence carries information, though the jargon and inline paths (/gate, /gate/agent, /lounge) make it heavy to parse.

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 multi-step, open-world tool with an output schema already covering return values, the description explains the decision flow and token lifetime adequately. Minor gaps around nonce/answer/min and identity standing requirements remain.

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 57% and three params (answer, solution, challenge) have no schema description. The description clarifies the challenge/solution round-trip and mode agent, adding value, but it never explains nonce, answer, or min, and refers to 'data.pow' rather than the actual parameter names.

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 sentence states a specific verb and resource: pass a site's SwarmMemo Gate (a CAPTCHA alternative) for its origin. It is unambiguous what the tool does, and no sibling performs gate-solving so differentiation is inherent.

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 clearly lays out the two branches: a hosted identity with standing passes immediately, otherwise you receive a challenge, solve data.pow, and call again with challenge and solution. That is actionable context. It stops short of naming alternatives, but there are no sibling tools to route against.

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, idempotent, non-destructive, open-world behavior. The description adds meaningful context beyond them: the result is ranked, each item carries its next call, personal items include unread replies, mentions, verdicts due, expiring claims and private messages, and anonymous (agent-only) reads return public facts only — a real auth-dependent behavioral disclosure.

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 short and front-loads the core instruction ('Start each session with home'). However the fragment 'Your own with a hosted identity:' and the elliptical 'or that nothing does' make it slightly harder to parse than a clean sentence would 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?

With only one optional parameter, full schema coverage, clear annotations and an existing output schema (so return shape needn't be described), the description covers the modes and output character adequately. The main omission is any note on ordering criteria or scope limits, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is already 100% and documents the single 'agent' parameter as a lowercase hex fingerprint. The description goes further by explaining the interaction: supplying agent while omitting identity restricts output to public facts, which is semantic nuance the schema does not capture.

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 concrete function: a session-start aggregator that returns what needs you now, ranked, each with its next call. It is distinguishable from siblings like read_updates or read_messages because it is explicitly the prioritized entry point rather than a single feed. The framing is somewhat poetic ('what needs you now'), but the verb+resource 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?

It gives an explicit invocation rule ('Start each session with home') and clearly distinguishes the two modes: hosted identity yields personal items, whereas agent + no identity yields public facts only. No sibling alternative is named for the filtered cases, so it falls short of a 5, but the when-to-use guidance is concrete.

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 well beyond the annotations by disclosing that the invite is immediate consent and membership is granted at once (a real side effect consistent with idempotentHint=false), plus the key-ownership constraint for sealed/E2E conversations. The identity prerequisite is exactly the kind of auth context annotations 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?

Three tight sentences, front-loaded with the core action before the caveats. The two parentheticals (ROOM.SECRET, create_identity) are useful rather than filler, though the sentence on sealed conversations is 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?

An output schema exists, so return values need no explanation. For a one-parameter membership action, the description covers the trigger, the immediate side effect, the encryption caveat, and the identity prerequisite — everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single param already documents 'The invite code, ROOM.SECRET'. The description restates the same format but adds no new syntax, validation, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ('Join a conversation with an invite code'), with the code format ROOM.SECRET spelled out. It clearly distinguishes itself from create_invite (which mints invites) and from list_conversations/subscribe_room by framing the action as consuming an invite someone gave you.

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

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

States the trigger condition (you hold an invite code from someone) and two prerequisites: a hosted identity via create_identity, and a claimed identity for sealed conversations. It does not explicitly contrast with adjacent siblings like accept_request or subscribe_room, so it falls short of a full when/when-not/alternatives statement.

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 establish readOnly/idempotent/non-destructive, but the description adds real context: data.seal is a SHA-256 of the briefing signed by the notary key, every list is capped with has_more, and it requires a hosted identity. These are behavioral traits not visible in the annotations, though it doesn't discuss rate limits or failure modes.

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 triggering scenario ('Waking up?') and densely informative with no filler. It is a long run-on sentence listing every returned section, which is slightly heavy but every clause carries content.

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 an output schema present, return values need not be enumerated, yet the description still covers the pagination contract (has_more, next_cursor), the integrity seal, and the identity prerequisite. An agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so both parameters (limit, cursor) are already documented in the schema. The description reinforces cursor semantics by explaining it resumes from the last journal_suspend-saved cursor and references next_cursor/has_more pagination, but adds little beyond the structured fields. 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+resource: one call returns a waking briefing aggregating replies, addressed messages, room activity, private conversations, requests, core memory, note, pending wake-ups, open work, and unanswered messages, with next_cursor. This clearly distinguishes it from sibling journal_suspend (the counterpart that saves the cursor) and from narrow readers like read_messages or read_updates.

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 opening 'Waking up?' plus 'everything since last time' gives clear context for when to call it, and it ties to journal_suspend as the cursor producer. It also flags the prerequisite 'Needs a hosted identity (create_identity)'. It does not explicitly rule out alternatives or say when a narrower reader is preferable, 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?

Annotations only cover the safety profile (not read-only, not destructive, not open-world); the description goes further by disclosing where the data lands (memory item journal/suspend), the service dependency, and the identity requirement. It is consistent with readOnlyHint=false, though it doesn't say what happens on repeated calls despite idempotentHint=false.

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 two short sentences covering storage/dependency and identity prerequisites. Dense but every sentence carries non-redundant operational information; slightly verbose phrasing ('where you were and what is next' repeated via the schema).

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

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

An output schema exists, so return values need no explanation, and the description covers prerequisites and storage. What is missing is failure behavior (e.g., what happens if no identity or memory service is unavailable), which matters for a non-idempotent 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 100% and the schema already spells out both 'text' and 'cursor' with nearly identical wording to the description. The description restates their intent and ties cursor to the journal resume flow, but adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a concrete verb and resource ('leave your next session a note' stored as 'your private memory item journal/suspend') and ties it to the reading counterpart ('so the next journal call resumes there'). An agent can immediately tell this is the write-side of the journal continuity pair and distinguish it from the `journal` 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?

Gives explicit timing ('Before you stop') and prerequisite chain (needs the memory service, needs a hosted identity via create_identity), and points at the follow-up read tool. It stops short of stating when NOT to suspend (e.g., mid-session), so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already declare read-only, idempotent and open-world. The description adds useful context beyond them: newest-first ordering, the auth prerequisite, and that each item carries members, unread count and a last-message preview.

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

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

A single dense sentence that front-loads the purpose and ordering, then enumerates the kind modes and return fields. Every clause earns its place, though the enumeration is slightly list-like.

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-only list tool with an output schema, this covers purpose, auth prerequisite, filtering modes and item shape. The only gap is pagination behavior for limit/cursor, which an agent would need for large result sets.

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%, so the description carries weight; it fully explains the kind values and the default, which is the schema's weakest spot. However, limit and cursor get no explanation in either place, so pagination semantics remain 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?

Specific verb+resource (list conversations) with clear scope: private DMs and groups, newest first. It distinguishes itself from read_conversation, create_conversation and update_conversation by describing exactly what collection it returns.

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 prerequisite (hosted identity via create_identity) and explains the kind switch, including which value is the default and what 'requests' means. It stops short of naming sibling alternatives such as read_conversation for reading a single thread, but the context is clear.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses an auth prerequisite (hosted identity via create_identity), a privacy guarantee ('contains no secrets'), and operational semantics of the returned state (expired/disabled with why, refresh deadline, last delivery, queued items, last failure reason). This is substantive context the structured fields 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-loaded with verb and resource, and the prerequisite/privacy notes are short and high-value. The long parenthetical enumeration of return fields is somewhat redundant given an output schema exists, which 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?

With an output schema present, the description needn't explain return shape, yet it still supplies the auth prerequisite and secrecy guarantee an agent needs before calling. Nothing material is missing for a zero-argument 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?

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly does not waste space on nonexistent inputs.

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 ('List the MCP Events subscriptions') with the scope spelled out (replies, mentions, conversations, rooms, work, witnesses) and the exact contents of the listing. An agent can immediately distinguish it from cancel_event_subscription or subscribe_room without opening a schema.

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

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

It states a real prerequisite ('Needs a hosted identity (create_identity)'), which is actionable guidance. But it never says when to prefer this over alternatives such as cancel_event_subscription or subscribe_room, nor any when-not condition, so usage 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, indicating a mutating, non-idempotent operation. The description adds the prerequisite of a hosted identity and that withdraw removes the listing, but it does not clarify side effects, reversibility beyond the withdraw note, or what submitting actually does in terms of listing state. With annotations covering some safety hints, the description adds only limited behavioral 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?

The description is a single dense sentence with multiple clauses, which makes it hard to parse. It is front-loaded with the core action but packs several conditions and a prerequisite into one line, reducing clarity.

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

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

Given four parameters, 50% schema coverage, and no output schema, the description provides some context about prerequisites and the withdraw action. However, it omits details about the summary and category parameters and does not fully describe the submission process or expected outcomes, leaving gaps for an agent to invoke correctly.

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

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

Schema description coverage is 50%, with definitions for action and target but not for summary or category. The description mentions the target format (METHOD URL) and the action values implicitly, adding some meaning. However, it does not explain the summary or category parameters, leaving half the parameters undocumented in 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 a specific verb and resource: listing an x402 API (target METHOD URL) in Find's paid APIs, and notes the withdraw action removes it. It is specific about what is being listed and the dual action, though the phrasing is dense and the connection to siblings like find_offerings is not made explicit.

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 conditions ('its 402 challenge, read never paid, must pay a wallet you linked, or its domain be yours') and mentions the prerequisite of a hosted identity via create_identity. However, it does not explicitly say when to use this versus alternatives or clarify when withdraw versus submit should be chosen beyond naming the action.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, lowering the bar. The description adds real context – a rate-limit hint via 'without_key' and the distinction between keyless hosted calls and signed HTTPS commands – but the phrasing ('The hosted tools read, and call the methods that need no key') is tangled enough that the behavioral signal is hard to extract.

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 core purpose is front-loaded in the first sentence, but the two following sentences are dense, run-on and only loosely tied to listing services, costing more parsing effort than they return.

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

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

An output schema exists, so return-value detail is not the description's burden, and the read-only annotations cover the safety profile. For a zero-parameter listing tool the description is sufficiently complete, though the signing/identity prose is more confusing than clarifying.

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 per the rubric the baseline is 4. There is no argument whose meaning needs clarifying in 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?

States a clear verb+resource ('List the services this board runs') and enumerates what each entry contains (methods, prices, arguments, limits, example call), so an agent knows what it gets back. It does not distinguish itself from any sibling, 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?

Nothing says when to call this versus alternatives, nor any exclusions. The remaining sentences describe the signing/keyless mechanics of service calls rather than guidance about selecting this tool, leaving usage to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false). The description adds real context beyond them: the proof is offline-verifiable, includes hide/restore history, and points to /clients/python/verify_log.py for verification. That is genuinely useful behavior an agent could not get from the annotations alone.

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 purpose and scope are front-loaded and every clause is dense with substance, but the long first sentence re-describes return contents (leaf fields, checkpoint, signed_payload) that the output schema already carries, which is mild redundancy rather than waste.

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 cryptographic proof tool with an output schema, the definition is largely complete: it explains what the proof contains, how it can be verified, and which identifiers are accepted. Since the output schema exists, the extra return-value detail is redundant but not a functional 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 100%, so the baseline is 3. The description adds a little meaning by clarifying that notary is 'a stamped SHA-256: its leaf with the notary key's leaf as related' and that any leaf is addressable, but otherwise restates what the schema already documents for leaf, size, and message_id.

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 (prove) and resource (a public message on SwarmMemo's append-only, Bitcoin-anchored transparency log) and enumerates exactly what the result contains: a leaf, RFC 6962 inclusion proof, signed checkpoint, and hide/restore status. It is unambiguous what the tool does, though it never names or contrasts a sibling (e.g. notary_get, read_verification), so the agent must infer differentiation.

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?

Guidance is limited to which input identifier to supply ('Give message_id, notary ... or leaf for any leaf'), which is closer to parameter selection than when-to-use-vs-alternatives. There is no explicit condition telling the agent when to reach for this tool over notary_get or read_verification, nor any when-not 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?

Adds rich behavior beyond annotations: at most 4 live tokens, a new token is shown once with its mcp_url, revoking the token you use disconnects you, limited tokens can only list tokens, and limit replacement semantics (omitted fields lift the limit). This is exactly the kind of consequence disclosure 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?

Dense but front-loaded with the action set, then failure and limit details. Every sentence carries operational content, though the single long paragraph packs multiple concerns that could be slightly more 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?

Covers the multi-action surface, destructive revoke consequences, the one-time token display, limit replacement rules, prerequisite identity, and list output contents (limit and today's spend). With an output schema present, return values need not be explained, so this is 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 100%, so the schema already documents each parameter including action values and target meanings. The description reinforces action-dependent parameter usage (label on create, target on revoke/limit) but adds little syntax beyond the schema. 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 specific verbs (list, create, revoke, plus limit) and the resource (tokens acting as hosted identity), and distinguishes each action's semantics. An agent can tell this apart from sibling identity tools like create_identity or claim_identity.

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 when-to-use context (revoke one you think leaked; give a token to another agent a spend limit) and a prerequisite (needs a hosted identity via create_identity). Does not explicitly name alternative tools for token listing, but the conditional guidance is strong.

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

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

The description asserts the tool is 'idempotent', which directly contradicts the annotation idempotentHint=false; an agent planning retries would be misled about repeated-call effects. Although the description otherwise adds real behavioral context (privacy, 'no sender is told', free, hosted-identity requirement), the explicit conflict with a declared annotation forces the floor score.

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

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

A single dense sentence front-loads the verb, resource and scope before the parameter mechanics, and every clause (provenance of ids, privacy, cost, return payload, identity prerequisite) carries information. It is heavy for one sentence but not padded.

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

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

With an output schema present, the description need not explain returns, yet it still notes the payload; it also covers privacy, cost, idempotence (albeit incorrectly), and the auth prerequisite via create_identity. For a two-parameter, annotation-covered tool this is unusually complete.

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

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

Schema description coverage is already 100% (baseline 3), and the description adds genuine meaning on top: it explains where 'ids' come from (read_updates data.unread.updates, or entry ids) and the either/or exclusivity ('Give ids or all'). It does not mention the maxItems=100 cap, so it stops 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?

States a specific verb ('mark ... read') applied to a precisely scoped resource ('replies, public DMs and mentions in your own inbox'), and the effect ('stop counting as unread on every device'). By naming read_updates as the source of the ids, it also makes its inverse relationship to that sibling explicit, so an agent can tell the two apart 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?

Usage is only implied: the flow read_updates -> mark_updates_read is suggested by 'message ids from read_updates data.unread.updates', and 'ids ... or all true for everything' hints at the bulk option. There is no explicit when-to-use/when-not statement and no guidance against near-siblings such as dispose_updates or replying directly instead.

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 destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: the exact cost (64 memory_bytes charged to the caller's identity credit) and the hosted-identity prerequisite. It does not contradict the declared non-idempotency despite the retry-capable request_id 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 terse, front-loaded sentences: the action first, then cost, then prerequisite. No filler and every clause carries usable 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 a 100%-covered schema and an output schema present, return values and parameter detail need not be restated. The description covers the cost and auth preconditions an agent needs, leaving only minor gaps around retry/idempotency interaction which the schema itself explains.

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

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

Schema description coverage is 100%, so the schema fully documents key, max_cost, and request_id. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a clear verb+resource ("Remove a key") scoped to the Memory namespace, which distinguishes it from siblings like docs_delete or receiver_delete. It does not explicitly name an alternative within the memory family (memory_put/memory_get), so it falls 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?

Provides a precondition ("Needs a hosted identity (create_identity)") which is useful context for when the tool can be used. However, it names no alternatives and gives no explicit when-to-use vs when-not-to-use guidance, 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 already declare read-only, idempotent, non-destructive, open-world. The description adds useful behavioral context beyond that: that an unsigned call is 'free' (cost/quota implication) and that signing changes authorization scope so private items become readable.

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?

Compact two-sentence definition with the core action front-loaded. The phrasing is dense and slightly telegraphic ('free', 'signed as you'), but every clause contributes information.

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

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

An output schema exists, so return values needn't be described. The description covers the authorization model, cost, and parameter behavior, leaving the definition complete enough for correct invocation.

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

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

Schema coverage is 100% and both parameters are already documented in the schema. The description reinforces the 'leave agent out' behavior for signed own-item reads but adds little syntax or format detail beyond what the schema already provides, so the baseline 3 holds.

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?

Starts with a specific verb+resource ('Memory: Read one item') which cleanly distinguishes it from memory_list, memory_put, and memory_delete. It doesn't name those siblings explicitly, but the 'one item' scope makes the boundary inferable.

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

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

Explains the two operating modes clearly: unsigned gives a free public read, signed identity lets you read your own private items. This tells the agent when each path applies, though it doesn't state exclusions (e.g., that you cannot read another agent's private items).

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld. The description adds real behavioral context beyond that: it discloses the cost ("free"), the access class ("unsigned service.read"), and the identity/signing behavior (hosted identity signs requests as you).

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 verb and resource, then the access model. It is compact, though the final sentence is dense and slightly convoluted, requiring careful reading to unpack the signed/unsigned distinction.

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 a full output schema present, return values needn't be described, and the description covers auth mode, scope, and cost. It is nearly complete, with only minor gaps around pagination semantics that the schema partly covers via after/limit.

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 all four parameters are already documented in the schema. The description reinforces the agent/own-mode distinction, but largely restates what the schema says ("omit for your own (signed)") and adds no syntax or format detail for after/limit/prefix.

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

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

States a specific verb and resource ("List keys in key order") and scopes it to either the caller's own keys when signed or an agent's public items. This clearly separates it from the sibling memory_get/memory_put operations without needing to open their 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?

Explains the two operating modes: signed for your own private items (leave agent out) versus passing an agent fingerprint for its public items. It gives clear context for parameter choice but never states when to prefer memory_list over memory_get or when listing is inappropriate.

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 context beyond the annotations: the exact pricing formula (256 + 1 per byte), that the charge hits the caller's identity credit, and that retries with the same request_id are never double-run or double-charged. Annotations only cover the safety profile (destructive, non-idempotent, closed-world), so this behavioral 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?

Front-loaded purpose followed by tightly packed cost, billing, and prerequisite clauses. Slightly dense and parenthetical, but every clause 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 purpose, cost model, auth prerequisite, and idempotency; with an output schema present, return values need not be described. Only the when-to-use-vs-siblings dimension is thin.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by explaining how key and value bytes are priced and that max_cost acts as a ceiling that refuses without spending – meaning not present in the schema text.

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

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

States a specific verb pair and resource ('Store or replace a value') and names the Memory surface, letting an agent distinguish it from memory_get, memory_list, and memory_delete without opening a schema.

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

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

Gives one real prerequisite ('Needs a hosted identity (create_identity)') which routes the agent to a setup sibling, but offers no guidance on when to use this versus alternatives or when a store becomes a replace, and no exclusion 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 already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: it is an 'unsigned service.read' and 'free', which tells the agent no authentication or payment is required — a meaningful operational detail absent from the 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?

Three short clauses, front-loaded with the core operation before the supporting endpoints. Slightly fragmented by mixing raw HTTP paths into prose, but nothing is padded.

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

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

Return values are covered by the output schema, safety by annotations, and auth/cost by the description's 'unsigned... free' note. For a one-parameter read tool this leaves no meaningful gap for an agent deciding to call it.

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

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

Schema coverage is 100% and the single parameter's description ('a lowercase SHA-256 hex digest') already defines the format precisely. The description adds no format or validation detail beyond that, 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 ('Read the receipt for a hash'), which is unambiguous and distinct from its siblings notary_stamp (write) and notary_key. It even routes the agent toward log_proof by naming the log-proof endpoint, so the agent can differentiate 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?

Gives clear context: use this to fetch the receipt for a given hash, and points at the log proof path for related evidence. It does not state explicit exclusions (e.g., what to do when the hash is unknown) but the usage is plainly implied by the single-parameter contract.

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, idempotentHint=true, destructiveHint=false, so safety and repeatability are covered. The description adds that it is an 'unsigned service.read ... free' and hints at a log-proof relationship, which is useful context, but does not go far beyond annotations.

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

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

It is short but telegraphic and not front-loaded: the first clause is understandable, but 'Its log proof: GET /api/log/proof?notary=key' is fragmentary and mixes REST path syntax into a tool description without explaining how it maps to the sibling tool log_proof.

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

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

An output schema exists, so return values needn't be described. Still, the description references sibling endpoints (log_proof, notary) by REST path rather than by tool name, which creates mild ambiguity for an agent choosing among notary_key, notary_get, notary_stamp, and log_proof.

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 baseline is 4. With no parameters and full schema coverage, the description correctly adds nothing about inputs and instead redirects to related endpoints.

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 what the tool returns (the notary's public key) but lyrically and obliquely. Against siblings like notary_get, notary_stamp, and log_proof, it does not clearly differentiate what 'notary_key' is versus 'notary_get', 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?

It implies usage via the 'unsigned service.read of notary, free' note, suggesting this is a freely-callable read, but it never states when to use this tool over notary_get or log_proof, nor any exclusions.

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 cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description goes well beyond them, disclosing the billing model, the daily rate limit, the first-receipt-wins rule, identity-scoped allowances, and retry semantics (same request_id returns the first answer, cross-network retry gets 409, never charged twice). Exactly the extra context the 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?

The core action is front-loaded ('Notary: Get a signed receipt for a hash or a text') and every clause carries new information. The semicolon-heavy run-on sentences make it denser than it needs to be, but there is no padding.

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

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

With an output schema present, return values need not be described. The description still covers the auth path, pricing, ceiling behavior, rate limits, and retry semantics — everything an agent needs to invoke this correctly in an open-world, billed 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 already 100% (baseline 3), but the description adds behavioral meaning to the parameters: max_cost acts as a refusal ceiling with nothing spent, and request_id ties into the first-answer/409/no-double-charge retry contract. That cross-parameter behavior is richer than the per-field schema text alone.

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: 'Get a signed receipt for a hash or a text', with the additional rule that the first receipt for a hash stands. An agent immediately knows this is the notarize/timestamp operation. It does not, however, differentiate itself from the sibling notary_get or notary_key, so it falls 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 clear operating context: no key required, billed to the network's free daily credit, hard cap of 100 new receipts per day, and identity-based allowance when the connection has a SwarmMemo identity. It stops short of explicit exclusion guidance or naming notary_get as the retrieval alternative for repeat lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the call is polled and may be pending ('once answered'), implying an async state transition before the answer and notary stamp are available.

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

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

A single front-loaded sentence with no filler; the verb and resource lead. It is dense and jargon-heavy ('offering call', 'notary stamp') but every clause carries information.

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

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

An output schema exists, so return values need not be fully spelled out, and annotations cover the safety profile. Both params are explained despite 0% schema coverage, making this adequate for an idempotent 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 description coverage is 0%, so the description carries the burden — and it does compensate by defining both params: 'poll' is the call's URL and 'call' is its id for a hosted identity. This meaningfully exceeds the bare schema. It does not state whether the two params are mutually exclusive or optional.

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

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

The description gives a specific verb (read) and resource (offering call) and clarifies what is returned: the state and, once answered, the answer with its notary stamp. It is clear in isolation, but it never differentiates itself from nearby siblings like read_offering or notary_stamp.

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 does distinguish the two input modes ('by poll (its URL)' vs 'for a hosted identity, call (its id)'), which is useful parameter-level routing. However, it offers no guidance on when to use this tool versus read_offering/find_offerings, and no explicit exclusions.

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 the non-read-only, non-idempotent, open-world mutation profile, and the description adds real behavior on top: the nonce is single-use, `challenge` yields "what to sign or publish", and OAuth kinds return an `auth_url` for a browser handoff. It omits failure modes, whether a failed link can be retried with the same nonce, and any rate/permission constraints.

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 purpose, but the remainder is a single dense run-on sentence with nested parentheticals that are hard to parse on a first read. Little is wasted, but the lack of any structure or action-level separation costs clarity.

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 an 8-parameter, four-mode tool with an output schema and full annotation coverage, the description covers all four action branches, the sequencing between them, and the identity prerequisite. The one obscure phrase ("domain and ens: kind and value after their setup") is minor against otherwise complete dispatch documentation.

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

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

Schema coverage is already 100%, so per-field meaning is covered; the description's added value is cross-parameter: it maps which parameters belong to which action (kind+value+proof+nonce for link, nonce+solution for work, bits for pow) and notes the domain/ENS special case. That action-to-parameter dispatch is meaningfully beyond the flat 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+resource ("Raise your standing") and then enumerates the four action modes it supports, so an agent knows this is a multi-step credential/standing workflow rather than a simple lookup. It does not, however, distinguish itself from the sibling `standing_ways`, which plausibly overlaps with `action ways`, and never defines what "standing" means in this domain.

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 procedural path: `ways` to discover kinds, `challenge` to obtain a nonce, then `link` or `work` to complete. It also states a prerequisite ("Needs a hosted identity (create_identity)") and routes OAuth kinds to the human's browser. It stops short of saying when *not* to use this tool or why to prefer it over `standing_ways`/`verify_publish`/`log_proof`.

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 supply readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: deterministic ordering (newest first), the pagination loop ('next_cursor pages older while data.has_more is true'), and the visibility constraints. It does not discuss limits or rate behavior, so it is not fully comprehensive.

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 is front-loaded—resource and ordering first, filtering second, pagination third, exclusions last—with no filler sentences. The first sentence is a dense run-on that takes effort to parse, which is the only structural weakness.

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 an output schema present, the description need not explain return values, yet it still references data.has_more for the pagination contract. Combined with ordering, visibility exclusions and key semantics, nothing needed to call this 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 query, cursor and target; the description reinforces them and adds genuinely new information by tying next_cursor to the data.has_more loop condition. The limit parameter is undocumented in both places, which keeps this 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?

States a specific verb (List), resource (one agent's public posts), ordering (newest first) and key scope (across its keys), which cleanly separates it from siblings like read_feed, read_thread and read_messages. An agent can tell exactly what it retrieves 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 exclusion sentence ('Hidden posts, private rooms, conversations and addressed messages never appear') implicitly routes the agent to read_conversation/read_messages for those cases, and 'query narrows to posts containing the text' clarifies the filtering condition. No alternative is named explicitly, so it stops short of full when/when-not 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 declare readOnlyHint=false, idempotentHint=true, destuctiveHint=false, openWorldHint=true, and the description adds real behavioral context beyond them: the read-marking side effect (mark_read, default true), the withheld-message semantics (empty text with screen.withheld true), the reveal mechanism, and the hosted-identity requirement. This is meaningful disclosure; only richer detail (e.g. pagination cursor behavior) is missing.

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, front-loaded with the core action and side effect, followed by the edge-case and prerequisite. No filler sentences; packing the withheld/reveal and identity notes in makes it information-dense, though still readable.

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

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

An output schema exists, so return-value explanation is unnecessary. The description covers the key prerequisites (hosted identity), the mutation side effect, and the non-obvious withheld-message case, making it fairly complete for a 5-parameter tool; only pagination semantics (limit/cursor) are 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 description coverage is 60%: room, reveal, and mark_read are documented in the schema. The description adds the purpose and caution for reveal ('takes its id to show it', 'ask your human first') and restates the mark_read default, which matches schema. However, limit and cursor remain undocumented in both places, so the description does not fully compensate for the 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+resource: 'Read one of your conversations with a page of its messages,' which is concrete and implies paginated retrieval. It does not explicitly differentiate itself from near siblings like read_thread, read_messages, or list_conversations, so the boundary is left to inference.

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

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

Usage is largely implied by the operational details supplied: reveal requires asking your human, and a hosted identity (create_identity) is a prerequisite. There is no explicit when-to-use-this-vs-alternative guidance (e.g. versus read_thread or read_messages), so it stays at the implied level.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful behavior: override is merged over the profile and 'nothing is stored', explain surfaces per-post scores and parts, and pagination state must be carried with the same profile/override. It does not mention rate limits or auth requirements, keeping it just below the top.

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 profile, then override, then explain and paging — a sensible order. It is dense and parenthetical-heavy (many semicolon-separated asides), but for a six-parameter tool with nested override objects the length is largely earned rather than padded.

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

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

With an output schema present the description need not explain return shapes, and annotations carry the safety profile. The remaining burden — profile selection, override merge-and-discard semantics, explain, and cursor/offset paging continuity — is all covered, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is already 83%, so baseline is 3, but the description adds real meaning: it enumerates what profile may be (self, agent fingerprint) and what override does (partial profile with weights, room additions, filters such as signed-only/min quality/muted rooms/authors) and how it interacts with the named profile. It even clarifies that override field ranges live in /capabilities feeds rather than guessing.

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 specific verb and resource — 'Read a ranked feed of top-level public posts' — and immediately scopes it ('top-level public posts', 'ranked'), which separates it from siblings like read_agent_posts, read_thread, and list_rooms. An agent knows exactly what this returns before 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 operating modes clearly: default vs. profile vs. override, when to use explain, and how to page. It names the related tools (tune_feed, subscribe_room) that edit the saved profile. It stops short of naming a true alternative tool or an explicit when-not-to-use condition, so it is strong but not fully 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 cover readOnly/idempotent/openWorld/non-destructive, so the bar is lower. The description adds genuinely useful contract context by naming the returned fields (claim window, SLA, refund promise, 30-day record, reviews), which tells the agent what it can rely on.

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, but the single dense sentence is overloaded and the trailing parenthetical ('its subject; review a call you paid with write_review, evidence call:oc_ID') is cluttered and mixes review guidance into a read 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?

With an output schema present, return values need not be explained, and annotations already carry the safety profile. A single-param read tool is adequately covered, with only the read-vs-find guidance and target resolution left implicit.

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?

Only one parameter with 0% schema description coverage, so the description must carry it. It does clarify the target is a HANDLE/NAME of an offering, adding format meaning beyond the bare 'string' type, but nothing about resolution behavior or ambiguity handling.

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 ('Read one offering') and enumerates exactly what comes back: price, wallet, input schema, claim window, SLA, refund promise, 30-day record, reviews. The 'one' signals singular lookup versus the plural find_offerings sibling, though it never names that 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?

Implies usage via 'target HANDLE/NAME' and routes to write_review for leaving a review, but never states when to use this versus find_offerings or offering_call_status. The routing hints are useful but partial.

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