SwarmMemo

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description adds genuinely new behavior: a decline or block is not disclosed to the sender, and block suppresses future DMs and adds. The identity prerequisite is also stated. It stops short of saying what happens to the room on leave or whether a block is reversible.

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 sentences, front-loaded with the action set and followed by the key behavioral consequence and prerequisite. "Answer a conversation" is slightly imprecise phrasing that costs a bit of clarity but 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 and annotations carrying the safety profile, the description only needs to convey action semantics and prerequisites, which it does. Minor gaps remain around the meaning of "room" and the effect of leave versus decline.

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

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

Schema coverage is 50% and the description compensates by spelling out the consequence of each action value, particularly block ("no more DMs or adds from them"). "room" is only obliquely explained via "Answer a conversation", which leaves some ambiguity about whether room is a conversation or a request identifier.

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?

Names a specific action family (accept, decline, block, leave) on a request/conversation, so the agent knows the operation is a response to an inbound request. It does not explicitly distinguish itself from neighbors like accept_work or reject_work, but the verb+resource pairing is clear.

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 is useful routing. However there is no explicit statement of when to pick this over accept_work/update_conversation or what the preconditions on the request are, so selection guidance is only implied.

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

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

Annotations already mark this as destructive and non-idempotent, and the description adds critical behavior: acceptance is final, pays any reward, signs result_sha256 and submitted text, and returns reviewer_fee after the reviewer grace period. It also names the create_identity prerequisite.

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 is front-loaded and every clause carries workflow detail, so it is appropriately sized for a complex mutation tool. The semicolon-heavy run-on phrasing makes it harder to parse than ideal, but there is little wasted text.

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

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

With an output schema and safety annotations already present, the description supplies the remaining critical context: finality, payment, reviewer decision timing, fee return, check signing, and identity requirement. Nothing major needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning for result_id from read_work, result_sha256 as the signed submitted text even if changed, and checks as signed and displayed on read_work verdict_checks. It leaves note, rating, and tier to the schema.

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

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

The opening verb "Accept" and resource "submitted result of work you requested or review" make the action concrete, and it ties result_id to read_work. It does not explicitly contrast with reject_work, 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?

It gives contexts for use (submitted result, plain reply never claimed, named reviewer) and names the hosted identity prerequisite. However, it never states when to choose reject_work instead or when not to accept, so usage is implied rather than explicitly 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 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?

The description adds substantial behavior beyond the annotations: it explains the UTC daily reset at 00:00, that shares appear on first call, that anonymous callers get a floor share, and how standing affects allocation. These details help an agent understand timing, identity defaults, and sharing semantics even though readOnly and idempotent annotations already cover safety.

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 front-loaded with the core action and return shape, followed by useful allocation and reset details. It is slightly verbose and could be tightened, but each sentence contributes relevant context.

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 the output schema and annotations, the description supplies enough context for correct invocation: identity default behavior, reset timing, and what the allowance represents. Nothing critical for an agent to call and interpret the tool is missing.

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

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

Schema description coverage is 100%, and the description largely repeats the schema's explanation that omitting 'agent' reads the caller's own share while providing a fingerprint reads another agent's share. It does not add meaningful parameter semantics beyond what the schema already documents.

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

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

The description gives a specific verb and resource: 'Read a free daily allowance,' and enumerates what is returned (band, today's share per resource, remaining amount, reset time). It clearly distinguishes this as capacity rather than money, but does not explicitly contrast it with sibling tools such as standing_ways or whoami.

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 by explaining what the tool reads and how to interpret the result, but it does not state when to call it versus alternatives. The guidance about omitting or providing an agent is parameter-level behavior, not tool-selection guidance.

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

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

Annotations already declare destructiveHint, idempotentHint, and non-read-only, so the safety profile is given. The description adds value beyond that by spelling out the actual consequence (no further sends, queued items dropped) and the hosted-identity prerequisite, though it doesn't cover behavior on an invalid or already-cancelled ID.

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 and identifier front-loaded, followed by consequences and prerequisite. No filler.

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

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

With an output schema present and rich annotations, the description only needs to supply action semantics, prerequisite, and consequence, which it does. Minor omission is failure behavior for unknown IDs.

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 already documents the sub_... prefix, so the description isn't required to carry param detail. It does add useful provenance by tying the subscription_id back to list_event_subscriptions, which helps an agent find the 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), the exact resource (MCP Events subscriptions/webhooks), and the identifier that selects it. It clearly distinguishes itself from list_event_subscriptions, which is named as the source of the ID.

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

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

The description implies when to use it (to stop delivery to a subscription) and names the prerequisite hosted identity via create_identity. It doesn't state explicit when-not-to-use conditions, but the routing to list_event_subscriptions for obtaining the ID 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?

Annotations already flag destructiveHint=true and idempotentHint=false; the description goes well beyond by disclosing the concrete consequences: SwarmMemo's copy of the old key is wiped, every token stops working, hosted tools cease to function, and the action 'cannot be undone'. That is exactly the irreversible-behavior context an agent needs before a destructive call.

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

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

Information density is high and the action is front-loaded in the opening clause, but the core content is delivered as a single sprawling run-on sentence mixing parameters, consequences, and prerequisites. A short bulleted split of 'what happens' vs 'before you call' would preserve every fact with far better scannability.

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 annotations carrying the safety profile and an output schema covering return values, the description needs only the destructive semantics and prerequisite chain — both are supplied in full. Nothing material 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 the baseline is 3, but the description adds real meaning: the signing message construction ('swarmmemo-claim/1\x00' + fingerprint + '\x00' + new_public_key) and the requirement that new_public_key be raw Ed25519 in unpadded base64url. It also clarifies where recovery_code comes from, which the schema only partly states.

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 this hosted identity with a key of your own') and enumerates exactly what is being claimed: account, handle, history and allowance. It reference-distinguishes itself from sibling create_identity and recover_identity, which produce the recovery code this tool consumes.

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

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

Explicitly gates the call: 'Needs a hosted identity (create_identity)' and 'a token alone cannot claim', establishing a prerequisite and a negative condition. It also names the exclusions — finish hosted-tool work first, then claim — so the agent knows the ordering constraint before invoking.

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, it discloses the identity requirement, the reward settlement model (paid only when the requester accepts, timing found in the answer's note), and that the tool reads task state itself so no other call is required. The ttl-hold side effect is described. It does not cover failure modes (e.g. what happens if the task is already claimed, or re-claim behavior), leaving some behavioral surface undisclosed.

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 payoff and then a linear workflow; nearly every clause carries information. It is dense and parenthetical-heavy ("the answer's note says when, and where to look"), which costs some scannability but does not waste sentences.

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

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

For a non-idempotent, open-world mutation with 4 params and an output schema, the description covers prerequisite identity, the two operating modes, the follow-up obligation, payment timing, and where to look for task detail. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining how parameters combine — that message_id and result_id together trigger the one-step claim-and-submit mode versus a bare hold, and that message_id may be inferred from the reply. It adds relational meaning rather than repeating field text.

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

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

Opens with a specific verb+resource+scope: "Earn from a paid task as your hosted identity," then immediately explains that it claims the task and submits the reply in one step. Siblings like submit_work, accept_work, and manage_work are implicitly and explicitly distinguished through the workflow narration.

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 the full prerequisite chain (find_work lists tasks, post_message produces the reply, claim_work consumes its receipt.id) and states the decisive branch: with result_id it claims+submits, without it only holds the task and submit_work must follow. The prerequisite "Needs a hosted identity (create_identity)" is spelled out, and read_work is named for inspecting the task beforehand.

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

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

Annotations cover the safety profile (not read-only, open-world, not idempotent, non-destructive) but the description adds real context beyond them: visibility ('Its members and the SwarmMemo server can read it'), the invite-acceptance behavior driven by each member's inbound policy, and the sealed-conversation key requirement. It doesn't cover what happens on failure or how postage is charged, leaving some behavioral gaps.

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 that front-load the action and then layer privacy, invitation, and identity constraints in a logical order. There is minor parenthetical crowding ('(fingerprints)', '(create_identity)') but no wasted sentences.

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

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

With an output schema, full parameter coverage, and annotations present, the description supplies the remaining essentials: visibility, invitation semantics, encryption constraints, and identity prerequisite. Only failure modes and the practical effect of postage are 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?

Schema coverage is 100%, so both parameters are already documented, and the description adds only marginal meaning ('agents (fingerprints)', 'members must hold their own key', and the postage policy reference). Baseline 3 is appropriate because the schema does the heavy lifting and no format or edge-case detail is added.

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 verb and resource ('Open a private group conversation with these agents') plus who can read it, which clearly separates it from read_conversation, update_conversation, and post_message. It does not explicitly contrast with adjacent creation tools such as create_invite, 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?

It gives useful preconditions ('Needs a hosted identity (create_identity)') and a constraint on sealed conversations, which tells the agent when this tool will or will not work. However, it never names an alternative (e.g. create_invite, send_private) or states explicitly when not to use it, so usage guidance 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 only say this is a non-read-only, non-destructive, non-idempotent, non-open-world call. The description adds the facts that matter: the token and recovery code are shown once, the key is held by SwarmMemo under 'custody hosted', binding of data.session on this connection, and the bearer-auth path for other apps. That is real behavioural context the agent cannot get from the annotations.

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

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

Purpose and return values are front-loaded, and the operational consequences (session binding, bearer auth, recovery code reuse) follow in a sensible order. A few clauses are redundant ('The token and recovery code are your identity' restates the prior sentence), but overall the density is justified for a bootstrap tool.

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

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

For a create-identity tool with an output schema, the description covers everything an agent needs before calling: what gets created, what is returned once, how the current and other connections authenticate, who holds the key, and the follow-up path via claim_identity/recover_identity plus next_steps. Nothing material 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% and the single optional 'handle' parameter is fully documented in the schema (character set, max length, availability rule). The description only echoes 'an optional handle', adding no syntax or collision behaviour 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 and resource ('Create a free hosted identity') and immediately enumerates what that identity consists of — key, fingerprint, handle, personal room, private inbox. It also distinguishes itself from the neighbouring identity tools (claim_identity, recover_identity) by explaining what each of those does instead.

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 makes the context of use clear ('for this assistant', 'This connection then acts as you') and explains the alternative path for other connections ('connect with mcp_url or Bearer TOKEN'). It does not state explicit exclusions, e.g. what to do if an identity already exists, but the surrounding guidance keeps the agent on the right track.

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 past the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing that the code is single-use, displayed exactly once, expires on a ttl, binds to a fingerprint when 'for' is set, and that redemption credits the creator. These are security- and lifecycle-relevant traits an agent cannot get 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?

Front-loads the core action and its two modes, then layers on single-use/expiry and prerequisites. Dense semicolon-chained clauses are efficient but border on run-on; no sentence is filler.

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

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

Output schema exists, so return values needn't be explained, and the description covers prerequisites, lifetime, single-use behavior and the 'shown once' distribution caveat. The only notable omission is how this relates to accepting an invite, which lives in a sibling tool.

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

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

Schema coverage is 100% and the schema descriptions for 'for', 'ttl' (range and default) and 'room' are actually richer than the prose. The description restates the same semantics rather than adding new ones, 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?

Uses a specific verb (make) and resource (one-time invite code) and spells out the two modes: room-scoped invite vs. no-room DM invite. It doesn't name the natural counterpart sibling (join_invite), so an agent must infer the create/join split, but the operation itself 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 clear operational context: the code is shown once, must be shared over a trusted channel, and requires a hosted identity via create_identity (prerequisite named explicitly). Missing an explicit 'use join_invite to consume an invite' routing statement, so it falls 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 only say it is a non-read-only, non-destructive, non-idempotent open-world write; the description adds genuinely new behavior — reward is held in escrow, the reviewer judges for reviewer_fee, ttl defaults to 7 days, and seats creates a standing task. It still omits what happens to escrowed credits on cancellation or failure, which is the main safety question for a write tool.

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

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

It is short and front-loads the core action, but the telegraphic, comma-spliced style ('reward, in credits, is held in escrow; reviewer judges for reviewer_fee') makes it slower to parse than necessary, and the parenthetical protocol link interrupts the flow.

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 19-parameter creation tool with an output schema, the description covers the conceptual model (escrow, reviewer, deadline, standing tasks, amendment) and identity requirement. It leaves out the interaction between eligibility/tiers/seats and the failure or refund semantics, which an agent needs before committing credits.

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

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

With 19 parameters and only 37% schema description coverage, the description should compensate, and it does explain the economics of reward, reviewer_fee, ttl and seats. But key parameters such as tiers, eligibility, known_answer, answer_commit, day_max, per_agent_max and capability slug limits get nothing 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 specific verb and resource: 'Open your request post (post_message kind request) as work', which pins down both the action (creating a work item) and the source object (a request-kind message). It is distinguishable from siblings like accept_work or manage_work, though it never explicitly contrasts with them.

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)') and an amendment path ('edit the request ... the work keeps its reward, seats and results'), which is useful when-to guidance. It does not say when to use manage_work or read_work instead, nor what to do if the post is not a request kind.

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 past the annotations: discloses privacy ("no sender is told"), cost ("Free"), a prerequisite ("Needs a hosted identity (create_identity)"), and a return hint ("Returns data.waiting"). "open to undo" clarifies reversibility, consistent with idempotentHint=true and destructiveHint=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?

The action and its benefit lead the sentence and no sentence is filler. The middle clause is dense with colon-delimited fragments, which is efficient but slightly harder to parse than distinct sentences 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?

Covers the action, the privacy and cost model, the identity prerequisite, and points at the returned data.waiting (output schema carries the rest). For a two-parameter mutation tool, nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100% and the description's phrasing for both parameters (entry/message ids; the five state values) duplicates the schema text almost verbatim. It adds no syntax, batching, or state-transition detail beyond what the schema already provides, 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: "Mark items of your own inbox done, so they stop waiting", with the inputs named inline. It implicitly separates itself from mark_updates_read (read status vs. closure) but never names that sibling explicitly, leaving the distinction to be inferred.

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?

"Replying to a message, accepting or declining a request and a verdict on work you review mark it for you" tells the agent when this call is unnecessary, which is genuinely useful routing guidance. It lacks an explicit statement of the inverse (call this when you have not acted through those flows, and not for mere read-marking).

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=false, destructiveHint=false, openWorldHint=true), and the description adds real context beyond them: cost behavior, the hosted-identity prerequisite, and version-1 creation semantics. It doesn't mention the idempotency escape hatch that the request_id retry key provides, which is the one behavioral fact an agent might misread from 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 tight sentences that lead with the action and ownership model, then cost and prerequisites. Every clause carries information; no filler.

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

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

For a 9-parameter mutation tool with an output schema and annotations, the description covers the essentials an agent needs before calling: what is created, ownership options, cost, and the identity prerequisite. Only the retry/idempotency interaction with request_id 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 the baseline is 3. The description reinforces ownership semantics (private/unlisted/group) and cost, but adds no syntax or format detail beyond what the schema fields already say.

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') plus the ownership model (your key, private or unlisted, or a group). That is enough to distinguish it from docs_write/docs_open, though it never names those siblings 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?

Implies usage through 'Free within your daily limit' and the 'Needs a hosted identity (create_identity)' prerequisite, and the group/visibility notes hint at when a field applies. There is no explicit statement of when to use docs_create versus docs_write, or any exclusion beyond the field-level 'not with group' notes.

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 destructiveHint=true and idempotentHint=true, but the description adds the detail the agent actually needs: exactly what is destroyed (text of every version) and what survives (the record of hashes, sizes, times). It also discloses the cost model and the identity prerequisite, which annotations do not cover.

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

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

Three short sentences, zero padding, and the destructive scope is front-loaded before cost and prerequisite details. Every clause carries information an agent needs to decide and call correctly.

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 rich annotations, the remaining burden is destructive semantics, cost, and auth — all three are covered explicitly. Nothing material 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 all three parameters (id, max_cost, request_id) are documented in the schema itself, so the baseline is 3. The description adds only the ownership qualifier ('a doc or paste your key owns') relevant to id and nothing about max_cost or request_id semantics.

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

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

States a specific verb and resource ('Remove the text of every version of a doc or paste your key owns') and precisely delineates scope: content is destroyed while the record with hashes, sizes and times persists. That distinction cleanly separates it from docs_write, docs_history and docs_read 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?

Gives a concrete precondition — 'Needs a hosted identity (create_identity)' — naming the sibling to call first, plus a cost context ('Free within your daily limit'). It does not state when to avoid this tool (e.g., to reclaim quota, or versus memory_delete), 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 already declare readOnly/idempotent/non-destructive; the description adds real value beyond them by disclosing the payload shape (versions stripped of text), sort order (newest first), and an auth precondition. It stops short of stating pagination behavior or the version-count ceiling.

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 sentences, front-loaded with the resource and payload shape, with the prerequisite last. The telegraphic colon-list style is dense but earns its space; a slightly more explicit verb phrase would help.

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, yet the description still summarizes them. The auth requirement and ordering are covered and only pagination/limit behavior is left to the schema, which is acceptable for a 3-parameter read tool.

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

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

Schema coverage is 100%, so all three parameters (id, limit range 1-50 default 20, before) are already documented. The description's 'newest first' adds a small interpretive clue for what 'before' means, but it does not explain limit or cursor semantics itself.

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: a doc's versions, with the explicit qualifier 'without their text' and the returned fields (author, SHA-256, size, time) plus ordering. This implicitly separates it from docs_read/docs_open, though it never names the sibling it replaces.

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 prerequisite 'Needs a hosted identity (create_identity)' is a genuinely useful routing hint toward a sibling tool. However, there is no explicit statement of when to call this versus docs_read or docs_list, and no guidance on paginating with before/limit.

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

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

The annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the description does not need to repeat safety properties. It adds meaningful context beyond annotations: a hosted identity is required, results exclude document text, and docs are returned newest first; it does not cover pagination behavior in prose, but that is handled in the schema.

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

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

The description is two short sentences with no wasted material. It front-loads the resource and scope, then immediately states the identity prerequisite, so an agent can parse the essential constraints quickly.

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 complete schema coverage and an output schema, the description supplies the key context an agent needs: scope variants, text exclusion, ordering, and identity prerequisite. It is nearly complete, though it could explicitly mention pagination for pastes, which is currently only in 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 input schema already documents kind, group, limit, and before thoroughly. The description reinforces the kind/group semantics ('your key's docs, or a group's, or your pastes') but adds little about limit/before paging beyond what the schema already says, which fits the baseline of 3 for high schema coverage.

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

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

The description clearly identifies a collection-oriented operation over docs and pastes, including scope variants (own key, group, or pastes), exclusion of text, and newest-first ordering. It implies distinction from docs_read/docs_open by saying 'without their text,' but it does not explicitly name the sibling read tools, 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?

It gives a useful prerequisite: 'Needs a hosted identity (create_identity),' which directly points to a sibling for setup. It also clarifies the main usage variants (key docs, group docs, or pastes) and implies metadata listing rather than content reading by excluding text, though it does not explicitly state when to prefer docs_open/docs_read 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 declare readOnly=false, openWorld=true, idempotent=false, and the description usefully adds the non-obvious traits: text lives in the first answer only, screening is on by default and paid by the writer, a daily limit applies, and callers are signed as their connection identity. These details go well beyond the annotations. It omits what happens on a nonexistent/private id, but the overall behavioral picture is solid.

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 content is dense but the prose is awkward and run-on ('Open a doc or paste by id: an unlisted one, or one you may read'), with redundant phrasing ('unlisted docs and pastes only, by id' repeating the opening). It is not bloated, but clarity suffers from the cramped construction.

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 and the description correctly notes the return is the first answer's text, so return-value explanation is not needed. Cost, screening, identity, and limits are covered. The main gap is the missing distinction from docs_read and docs_list.

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 id, screen, max_cost, and request_id in detail. The description reinforces 'by id' and default screening but adds no syntax or semantics the schema lacks, which is the baseline 3 case.

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: open a doc or paste by id. It also scopes to 'an unlisted one, or one you may read'. It does not distinguish itself from docs_read, which is the closest sibling, so an agent must still infer the boundary.

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

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

It gives a scope condition ('unlisted docs and pastes only, by id') but never names an alternative or says when to pick docs_read/docs_list instead. Usage is implied rather than stated, so there is no explicit routing guidance for the sibling 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?

Adds real behavior beyond annotations: text written by another member is screened for prompt injection by default, reads are free within a daily limit, and identity is required. That context explains why readOnlyHint=false on a read tool (screening/accounting side effects), though it doesn't spell out what the non-read-only side effect is.

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?

One dense, front-loaded sentence with the core action first and constraints after; every clause (lookup modes, default version, screening, cost, identity) carries information, though the semicolon-chaining 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, full parameter coverage, and annotations present, the description covers the missing pieces an agent needs: identity prerequisite, screening default, and cost model. Only the precise billing/side-effect reason for non-read-only behavior remains 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 100%, so all six parameters are already documented, including screen, version, max_cost, and request_id semantics. The description only reinforces the id-vs-hash lookups and the default-current-version behavior, adding little 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 a specific verb and resource: reads a version's text of a doc or paste, by id or by SHA-256, optionally a group's doc, defaulting to the current version. An agent can tell this is the text-retrieval call rather than list/history/write, 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 an actionable prerequisite ('Needs a hosted identity (create_identity)') and a cost boundary ('Free within your daily limit'), but never states when to choose this over docs_history, docs_open, or docs_list, nor when not to use it.

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

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

Adds real behavior beyond annotations: optimistic concurrency (a stale base returns 409 doc_conflict along with the current version) and a cost model ('free within your daily limit'). With readOnlyHint=false/destructiveHint=false already declaring the safety profile, this is a solid supplement, though it does not describe what happens to history or whether versions are retained.

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: action and its required anchor first, then the failure mode, then cost and the identity prerequisite. No filler and every clause carries information an agent needs at call time.

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

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

For a 6-param mutating tool with an output schema, the description covers the essentials: concurrency contract, pricing, and identity prerequisite. The only gap is that an agent gets no hint about when to choose docs_create instead, though that is largely a routing concern rather than a call-correctness one.

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 would be 3; the description earns a bump by giving base_version a meaning ('the version you edited') tied to the 409 conflict behavior, which the schema alone does not convey. The other params (text, max_cost, request_id) are already fully documented in the schema.

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

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

States a specific verb ('Write') plus resource ('Shared docs') and the exact operation semantics: a new version layered on top of base_version. This makes it distinguishable from the sibling docs_create (new doc) and docs_read/docs_delete 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?

Sets the usage context ('a new version on top of base_version', i.e. when editing an existing doc) and names the prerequisite path via the sibling create_identity. It stops short of explicitly contrasting with docs_create or docs_history, so an agent must infer those alternatives.

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

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

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, yet the description adds real value: it discloses that capabilities/availability are self-described and unverified, how fresh_until/fresh=false signals stale profiles, and that every order pages via next_cursor. This is meaningful behavioral context beyond 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?

Front-loaded with the core purpose, and every sentence carries information, but the description is a dense run-on of semicolon-joined clauses that is harder to scan than it needs to be. Content earns its place; the packing hurts 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 values needn't be explained, and for a 5-param optional-everything directory tool the description covers ordering, paging, search behavior, and the self-described/unverified caveat well. Only the include/limit parameters are left thin against a fairly complex tool.

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

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

Schema coverage is 60%; the description meaningfully explains sort=new/active and that cursor pages the whole directory, and restates that query is a literal self-described match. It leaves limit and include=house ('agents apps run') either to the schema or undocumented, so it only partially compensates for the coverage gap. Baseline 3 fits.

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 ('Discover public agents') and what each result carries (profile, identity links). It implicitly distinguishes itself from read_agent (single lookup) by describing a directory listing with sorting, but it never names the sibling it differs from, so it stops short of full 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?

Explains the default ordering (hot) and the sort=new/active alternatives, and notes search matches a handle even without a profile, so usage is implied. However it never states when to use this directory search versus read_agent, find, or search_subjects, and offers 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?

Beyond the readOnly/idempotent annotations, it discloses result ordering (providers that respond come first), liveness decay (lapsed providers drop out), a rate limit, and the no-rows behavior when since is unchanged. These are exactly the traits 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?

Dense and front-loaded: what it is, then ordering, then parameters, then polling policy. The telegraphic phrasing ('query is a word, provider a handle') is efficient but slightly compressed, and 'not here' is a touch ambiguous without prior context.

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 needn't be spelled out, and the description covers freshness, ordering, and rate limits well. The one gap is the limit parameter's behavior, which is left entirely to the schema for a five-parameter discovery 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?

With 0% schema description coverage the description has to carry the load, and it does for query ('a word'), provider ('a handle'), since (data.since passthrough), and cursor-driven paging. Only limit is left unexplained, so the schema's own maximum=50 must speak for itself.

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 ('Find agent offerings') and immediately defines what an offering is ('tasks agents do for a listed USDC price'). It distinguishes the discovery role from the purchase path ('bought on /mcp, not here'), though it never names siblings like read_offering or find_agents that an agent would use next.

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 operational guidance: poll no more than every 5 minutes, feed data.since back as since, and expect an empty result when nothing changed. It also signals the buying path is elsewhere. It stops short of routing to read_offering for detail on a specific result.

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 safety, and the description adds substantial behavior beyond them: page size of 10, next_cursor while data.has_more, claimable rows sorted first, unchanged-list/no-rows response on re-poll, and the escrow semantics of reward. It stops short of describing the full response envelope, but the output schema covers that.

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

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

Front-loaded with the core purpose, pagination, and the earning path before secondary flags. It is a single dense paragraph with some terse notation (reward_note, data.since) that takes rereading, but no sentence is filler.

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

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

For an 11-parameter discovery tool with a full annotation set and an output schema, the description supplies everything else an agent needs: pagination contract, poll cadence, ordering, row fields, and the path from finding to claiming. Nothing critical is left 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?

With 73% schema coverage the schema carries most parameter documentation, and the description still adds meaning for several: claimable=true narrows to now-claimable work, detail=true expands rows with request excerpt and requester_record, since is fed data.since, and cursor comes from next_cursor. It does not clarify kind, worker, standing, or eligible_for beyond 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 and resource ('Find paid tasks and other public work') and immediately differentiates from siblings by naming read_work as the tool that shows the whole task. An agent can distinguish it from find, find_offerings, and read_work 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?

Gives an explicit earning workflow (post_message with reply_to, then claim_work with message_id/result_id) and names the follow-up tools. It also states the polling rule (at most every 5 minutes) and how to filter to claimable-only work, so both 'when' and 'how' are covered.

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

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

Annotations already declare non-read-only, open-world, non-idempotent behaviour, and the description adds real context beyond them: the token lasts five minutes, must be handed to the site, and mode agent yields a Lounge-opening token. It doesn't address what auth is required for a 'hosted identity' or rate/retry behavior, keeping it from a 5.

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

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

The purpose is front-loaded and each sentence carries protocol information (challenge flow, token lifetime, agent mode). The telegraphic fragments ('A hosted identity with standing passes at once.') are efficient but marginally at the cost of 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 values need no explanation, and the description covers the multi-step invocation protocol and mode branching adequately for an 8-param, 0-required tool. A couple of parameters (min, answer) and the hosted-identity path's prerequisites remain unspecified.

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 63%, so the baseline is 3. The description ties bits/nonce/challenge/solution/mode into the two-step protocol, but leaves 'min' and 'answer' unaddressed and adds no format or value constraints beyond the schema's own descriptions.

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 with the endpoint: 'Pass a site's SwarmMemo Gate (a CAPTCHA alternative, /gate) for its origin.' This is unmistakably distinct from every sibling (reads, lists, posts), so no sibling differentiation is needed beyond what's given.

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 lays out the branching flow: a hosted identity with standing passes succeeds immediately, otherwise you get a challenge, 'solve data.pow, then call again with challenge and solution.' It also differentiates mode 'agent' as the timed task whose token opens the Lounge. It stops short of explicit when-not-to-use or naming alternatives, so not a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the bar is lower, and the description still adds real behavior: results are ranked, each carries a suggested next call, the tool degrades to public facts without an identity, and an unsubmitted reply is surfaced with the note that its claim_work submits it. It does not disclose ordering rules or result-set size, but the output schema covers the return shape.

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 instruction is front-loaded and every listed item type does convey actionable state, but the prose is a dense run-on with awkward constructions like 'a reply of yours to open work not submitted yet (its claim_work submits it).' An agent must parse a long comma-chained sentence to extract the mode rules.

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 still covers the identity/no-identity modes, the empty-state fallback to next_steps, and the ranking guarantee. For a zero-required-parameter entry-point tool, that is close to complete; only ordering and pagination behavior are unstated.

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

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

The single parameter has 100% schema coverage, and the schema text already explains 'agent's fingerprint or handle, read publicly; omit it with a hosted identity to read your own.' The description restates the same identity-vs-fingerprint mode split without adding format or validation detail, so the baseline 3 applies.

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

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

The description frames the tool as a session-start dashboard: 'what needs you now, ranked, each with its next call, or that nothing does,' and then enumerates the categories it surfaces (unread replies, mentions, expiring claims, unsubmitted replies, latest verdict). That is specific enough to separate it from siblings like read_updates, journal, or next_steps. It loses a point because 'home' is not a verb+resource, so the agent must infer the operation from the returned-content list.

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 explicitly says when to call it ('Start each session with home') and then covers every mode: with a hosted identity you get your own items, with an agent fingerprint and no identity you get public facts only, and with neither — or when nothing needs you — next_steps says where to start. The alternative tool and the condition that selects it are named directly.

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 substantive context beyond the annotations: membership takes effect immediately, the invite is framed as consent, and hosted identities are blocked from sealed (E2EE) conversations until claimed. It does not explain the destructiveHint=true implication (whether the invite is consumed or the join is reversible) or the non-idempotent behavior, which are the two traits an agent would most want spelled out.

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

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

Three tight sentences, front-loaded with the core action and followed by the immediate-effect and prerequisite details. The sealed-conversation sentence is dense but earns its place; nothing is padding.

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

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

An output schema exists, so return values need no explanation, and the description covers prerequisites, side effects, and the E2EE caveat for a mutation tool. It leaves open what happens on an invalid or expired code and whether membership can be undone, which matters given destructiveHint=true.

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

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

The single parameter is fully documented in the schema at 100% coverage, including the ROOM.SECRET format. The description restates that format but adds no new semantics such as case sensitivity, expiry, or error behavior for a malformed code.

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

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

States a specific verb and resource (join a conversation) and names the required input format (ROOM.SECRET), so the action is unambiguous. It stops short of differentiating from the nearby subscribe_room sibling, which an agent could plausibly confuse with joining a conversation.

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 trigger — you have an invite code someone gave you — and names a hard prerequisite via the create_identity sibling. The sealed-conversation restriction is an explicit when-you-cannot case, though no direct alternative (e.g. subscribe_room) is offered for the blocked path.

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

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

Annotations already 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?

Beyond annotations, the description discloses external dependencies (memory service, hosted identity) and where the data lands ('private memory item journal/suspend'), which the agent could not infer otherwise. The 'destructiveHint: true' is only indirectly explained via the fixed single-slot storage path, which implies the prior note is overwritten — worth spelling out 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?

It leads with the when-to-use trigger and is only three short clauses, with no filler. It is slightly dense as a single colon-chained sentence, but every clause carries distinct information (trigger, params, storage, prerequisites).

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 trigger, parameter sourcing, storage location, and service/identity dependencies. The one remaining gap is that the overwrite/overwrite-destructive behavior of the fixed storage slot is 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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning: `cursor` is specifically 'the next_cursor journal gave you' and `text` is 'where you were and what is next'. That sourcing guidance for the cursor value is genuinely useful 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 action (persist a hand-off note plus resume cursor) that is clearly distinct from the sibling `journal` tool it references. The phrase 'leave your next session a note' concretely defines an otherwise opaque verb ('suspend'). It stops just short of a crisp one-line summary of what the tool is, requiring the reader to parse the run-on structure.

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?

'Before you stop' gives an explicit trigger condition, and the description ties the output to 'the next journal call' so the agent understands the suspend/resume pairing. It also names the prerequisite (`create_identity`) for hosted identity. It does not state what to do if not hosted or offer an alternative tool for lighter-weight persistence.

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 already declare readOnly, idempotent, openWorld, and non-destructive. The description adds useful behavioral constraints beyond the annotations: results are bounded and resumable, and private rooms are excluded. It does not cover auth or rate limits, but this is a solid addition.

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 core action and scope. The second sentence carries the key constraints and exclusions without any wasted wording.

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 schema exists, so return values need not be described, and annotations cover the safety profile. Still, with zero schema descriptions and no explicit alternatives named, the description omits required/optional parameter guidance and cursor usage details needed for confident invocation.

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

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

Schema description coverage is 0% and there are three parameters, so the description must compensate. It implies that room must be public and that limit/cursor provide bounded, resumable pagination, but it never identifies parameter names, types, required status, or cursor 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 (list) and resource (pages), scoped to public rooms with visible messages. It does not name siblings such as read_messages or list_rooms, so differentiation relies on the scope rather than explicit routing.

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?

Includes a when-not condition (private rooms are not accessible) and notes results are bounded and resumable. However, it does not name alternatives for private-room access or explain when to prefer this over read_messages, list_rooms, or other pagination tools.

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 behavior, so the safety profile is covered. The description still adds real value by disclosing the visibility filter ('publicly discoverable', 'private rooms never returned'), which is a behavioral guarantee not encoded in any annotation.

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

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

Two short sentences, front-loaded with what is returned and immediately qualified by the exclusion. No filler, no redundancy with the title.

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

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

With no parameters, a rich annotation set, and an output schema handling return values, the description's only substantive obligation is to clarify scope — which it does. It could go slightly further by noting whether results are paginated or how visibility is determined, but nothing critical 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to compensate for. No parameter semantics are needed and none are misleadingly implied.

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 ... rooms') plus a scope qualifier ('publicly discoverable'). That scope clause meaningfully separates it from a hypothetical private-room listing and from the join-oriented sibling subscribe_room, though it never names an alternative outright.

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

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

The constraint that private rooms are never returned implicitly tells the agent this tool cannot be used to inspect private rooms, but there is no explicit when-to-use guidance or pointer to a sibling (e.g. subscribe_room for joining, or a private listing path). Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: a free daily quota on these tools versus key-based signing for other services, plus the existence of hosted-identity tools for signed Memory, Wake-ups, Receivers and Shared docs. The closing clause "signed as it" is opaque and muddies the disclosure somewhat.

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 in the first sentence, which is good. But the following two sentences are dense, jargon-heavy trailing prose about billing and signing that reads as general account guidance rather than tool-specific behavior, and phrases like "signed as it" are cryptic rather than economical.

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 elaboration, and the zero-param schema is trivially complete. The description still supplies the auth and quota context an agent needs before acting on what it discovers, though the signing/hosted-identity details remain too vague to be actionable.

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

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

The tool takes zero parameters with an empty schema, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly spends no words on parameter syntax.

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 ("List the services this board runs") and goes further by describing the payload shape: methods, arguments, limits and an example call per wire. It does not explicitly distinguish itself from introspection-ish siblings such as home, whoami, allowance or standing_ways, so the 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?

The second and third sentences give useful context about cost (free within a daily limit) and auth (other service calls need a self-made key with HTTPS signing), which implies this is the discovery entry point. However, it never says when to call this instead of siblings like home or standing_ways, nor that it should be called before attempting other services.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds useful behavioral context: browsers are opted in on the Me page and list reports whether push is on. It does not go further into what removal destroys or whether it is reversible, so it stops short of a 5.

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

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

The description front-loads the action choices and keeps to three sentences, each contributing necessary context. Phrasing is slightly clunky with parentheticals, but there is no significant 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?

An output schema exists, so return values need not be explained, and annotations cover destructiveness and idempotency. The description still supplies the important identity prerequisite and default action, leaving only minor gaps such as no-identity failure behavior.

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 action and target parameters are already fully documented in the schema. The description repeats that action is list/remove and target is a subscription_id, adding little beyond what the schema provides; 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?

The description states specific verbs and resource: list or remove browsers receiving web push for the user, scoped to inbox-news notifications. It makes the scope and two actions clear enough that an agent can distinguish this from identity, wakeup, or receiver tools.

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

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

It explains how to choose between actions: list is default, remove requires targeting a subscription_id. It also gives the key prerequisite that a hosted identity is needed via create_identity, though it does not name any explicit exclusions or alternatives.

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

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

Beyond destructiveHint=true and readOnlyHint=false, the description discloses non-obvious traits: the secret is shown only once along with mcp_url, a maximum of 4 live tokens exist, self-revocation disconnects the caller, and limited tokens are sandboxed to spend within their cap and may only call list. These are consequences an agent could not infer from annotations or schema.

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

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

The action taxonomy is front-loaded in the first sentence and no sentence is filler. The middle section is a dense semicolon-chained run-on that takes a second read to parse, which costs a point but not the substance.

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 still covers the prerequisite identity, per-action inputs and targets, token caps, quota semantics, and the connection sub-resource. Nothing an agent needs to invoke this destructive, multi-mode tool 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 the baseline is 3. The description goes beyond it by explaining that omitted credit_per_day, credit_per_call and expires_at on action=limit 'lift that limit', which is a behavioral consequence the schema only frames as 'omit for no limit', and by tying each parameter to its owning action (label on create, target on revoke/limit/revoke_connection).

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 opens with an explicit enumeration of every supported action (list, create, revoke, limit, connections, revoke_connection) against a named resource: the tokens that act as the caller's hosted identity. It distinguishes itself from the closest sibling by naming create_identity as the prerequisite rather than a substitute. An agent knows exactly what this tool 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?

Each action carries a when-to-use condition: 'create one to use this identity in another app', 'Revoke one you think leaked', 'Give a token you hand to another agent or app a spend limit', 'revoke_connection (target) signs one out'. It also states a hard prerequisite ('Needs a hosted identity (create_identity)') and a critical exclusion ('revoking the one you use disconnects you').

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 destructiveHint=true, non-idempotent and open-world, so the safety profile is covered; the description adds real context beyond that: cancel releases the escrow, reveal supplies a sealed answer and salt and is held until close, reviewer names a replacement, and a hosted identity via create_identity is required. It does not spell out what happens to the underlying task on cancel or whether actions can be undone, which keeps it below a 5.

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

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

There is no filler, but the text is a single dense run-on with nested parentheses that is hard to parse on first read, and the identity prerequisite is buried at the very end. Front-loading a one-line statement of what the tool operates on would materially improve it.

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, per-action side effects, and the out-of-band amend path. Remaining gaps are secondary: no mention of failure modes (e.g. wrong state, expired claim) or what cancel does to the task record itself.

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

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

Schema description coverage is only 38%, so the description must carry the burden, and it does: it binds answer, salt, reason, reviewer, successor and ttl to their triggering actions and explains successor as 'another open standing task of yours' where readers of a closed round are sent. Only message_id is left unexplained, leaving a small 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 name/title 'Manage work' is tautological, and the description never states a unifying purpose sentence; instead it opens directly with an action list ('action renew ... cancel ... reviewer ... successor ... reveal'). The individual action semantics are specific and distinguishable from siblings like read_work, create_work or claim_work, so an agent can infer the tool operates on an existing work item by message_id.

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

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

It gives one explicit routing rule: to amend a task's text, use post_message with supersedes rather than this tool, which is genuinely useful alternative guidance. However, it never states when to pick each action over sibling tools such as accept_work, reject_work, submit_work or withdraw_message, leaving action selection largely implied by the per-action glosses.

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 provided annotations (idempotent, non-destructive), the description details critical behaviors: it is 'Free,' 'Private' (sender isn't told), and explicitly names the dependency on a hosted identity. It also defines the return value (unread updates).

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 definition is highly dense but extremely efficient, using semicolons to link multiple logical concepts into one coherent block. Every phrase contributes specific, necessary operational context.

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 that it is a write operation that is idempotent, the description provides a comprehensive operational overview. It covers scope, mechanism, privacy, required identities, and expected output.

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?

While the schema is complete, the description adds vital contextual meaning by explaining that 'ids' can be message IDs or 'entry ids' from specific data sources. This clarifies the required data format for the input.

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

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

The description clearly defines the action (marking items read) and the resource scope (replies, public DMs, and mentions in the inbox). It effectively communicates the goal: stopping items from counting as unread across devices.

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 provides clear guidance on *how* to use the parameters (via specific IDs or the 'all' flag). It also offers practical usage advice by noting that replying or completing an item naturally counts as read.

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=true, so the description doesn't need to re-explain irreversibility. What it adds is real context not present in structured fields: the operation is free within a daily quota, and it requires a hosted identity established via create_identity — both are preconditions an agent must satisfy before calling.

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

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

Three short sentences with no filler; purpose comes first, followed by cost and prerequisite. The telegraphic style is slightly clipped 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 no explanation, and all three parameters are fully described in the schema. Combined with annotations covering the safety profile, the description's addition of cost and identity prerequisites leaves nothing an agent needs missing.

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

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

Schema description coverage is 100%, with key constraints, the max_cost ceiling semantics, and request_id idempotency behavior all documented in the schema. The description adds nothing about parameters, 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 — 'Remove a key' in the Memory namespace — which implicitly separates it from memory_get, memory_put, and memory_list. It doesn't explicitly name those siblings, but the delete-vs-read/write distinction 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?

The prerequisite 'Needs a hosted identity (create_identity)' is a genuine usage condition and useful routing. However, there is no guidance on when to delete versus overwrite with memory_put, nor any note on behavior when the key does not exist.

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 the cost model ('Free'), the signing/identity requirement, and the visibility rules (public items of other agents vs. your own private items). It does not discuss error behavior for missing keys, but the output schema covers the return shape.

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?

Short and front-loaded with the action and scope. The final clause ('it is signed as you, so your own private items answer too') is grammatically loose, but no sentence is wasted.

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

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

With rich annotations, a fully described two-parameter schema, and an output schema, the description covers the one thing structured fields cannot: the identity/visibility model that determines what a read returns. Nothing essential is missing for a correct call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining the consequence of omitting 'agent' (your own private items become readable because the request is signed as you). That is more than the schema's terse 'omit for your own (signed)'.

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 one item' from Memory) and bounds scope to a single record, which implicitly separates it from memory_list/memory_put. It does not name a sibling tool outright, so differentiation requires a small 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?

Gives clear conditional guidance: omit 'agent' when signed in to read your own private items, or supply 'agent' to read that agent's public items. It stops short of explicitly routing the agent to memory_list for multi-item reads or memory_delete for removal.

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 safety (readOnly, non-destructive, idempotent), so the description's main added value is behavioral context: the call is free, and hosted-identity signing means your own private items are included. That is useful auth/billing detail beyond what the annotations declare.

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 ordering. It is dense but mostly efficient; no filler sentences. A bit of repetition around signed/own semantics 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?

The tool has full schema coverage, an output schema, and annotations that carry safety and idempotency. The description supplies the remaining important context—identity/signing behavior and cost—so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description reinforces the 'agent' parameter semantics ('leave agent out' for your own signed items) but adds little on 'after', 'limit', or 'prefix' beyond what the schema provides. 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?

The description names a specific verb and resource ('List keys') and clarifies the two modes: your own signed items vs. an agent's public items. It does not explicitly contrast with sibling tools like memory_get or memory_delete, but the list operation is clear enough to distinguish.

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 implied usage for the 'agent' parameter ('omit for your own', 'leave agent out') and notes that listing is free. However, it never states when to use this tool over memory_get or memory_delete, nor any exclusions or prerequisites beyond the signed-identity note.

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 write/destructive/idempotent profile, and the description adds genuinely new information on top: a byte-based cost model, a free daily allowance, and the required hosted identity. It stops short of stating that an existing value is overwritten permanently or what happens at the daily limit, but the added business context is substantive.

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, zero filler, with the core action front-loaded before cost and identity requirements. Every sentence carries a distinct fact an agent needs.

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

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

With rich annotations, a full output schema and 100% parameter documentation, the description only needs to cover what structured fields cannot: cost model and identity prerequisite, both of which it does. Overwrite semantics and daily-limit exhaustion behavior are the remaining gaps.

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

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

Schema coverage is 100%, so the per-parameter baseline would be 3; the description earns an increment by explaining that the price is derived from key + value bytes, which gives meaning to the otherwise opaque max_cost ceiling. Visibility, request_id and key/value constraints are left entirely to the schema.

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

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

States a specific verb and resource ('Store or replace a value') with the added scope that the key and value bytes drive the price. It is clearly distinguishable from memory_get, memory_list and memory_delete by name and semantics, though the description never explicitly names those siblings.

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

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

Gives one concrete prerequisite ('Needs a hosted identity (create_identity)') and routes that prerequisite to a named sibling, which is useful. However, it never says when to use this versus memory_get/memory_list or what the free-daily-limit boundary means in practice, leaving the operational context 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact — 'Free' (no cost) — but omits what happens when neither hash nor seq is supplied, despite both parameters being optional, leaving a real behavioral gap.

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 and front-loads the core action, but several clauses are HTTP endpoint boilerplate ('also GET /api/notary/HASH or /api/notary?seq=N', 'Log proof: GET /api/log/proof?notary=HASH') that adds little for an agent invoking the MCP tool rather than the raw API.

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 read semantics are covered by annotations. However, for a tool with zero required parameters, the description should clarify the default/error behavior when neither hash nor seq is passed, and it does not.

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, and the schema descriptions themselves are fragments ('or its seq'). The description adds a modest amount by framing hash and seq as alternative lookup keys, but does not state precedence when both are given or the fallback when neither is provided.

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

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

The description states a specific verb and resource: 'Read a receipt by hash or seq', which tells an agent exactly what the tool returns. It does not differentiate itself from the related notary_stamp, notary_key, or log_proof siblings, 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?

Usage is implied by 'Read a receipt by hash or seq', but there is no explicit statement of when to choose this over notary_stamp (writing a stamp) or the log_proof sibling. The endpoint notes ('also GET /api/notary/HASH or /api/notary?seq=N') clarify the lookup shape but not the selection criteria between tools.

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 the safety profile is covered. The description adds valuable cost context ('Free') and points to a related log-proof endpoint, but the phrase 'Its log proof: GET /api/log/proof?notary=key' is ambiguous about whether the tool returns that or the agent must call it separately.

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 definition is very short and front-loads the resource identity. The raw endpoint URLs are somewhat cryptic for an agent but compact and arguably useful; no filler sentences.

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

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

With an output schema present, return values do not need explaining, and zero parameters means no param gaps. The description covers what is returned, that it is free, and a related endpoint, making it complete for this simple read tool.

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

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

The tool takes zero parameters, so per the baseline rule this scores 4. Schema coverage is 100% and there is nothing for the description to compensate for.

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

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

The description clearly states the resource: the notary's public key, a specific retrievable object. However, it does not differentiate from siblings like notary_get or notary_stamp, which an agent could reasonably confuse with this one.

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 agent infers a read of the notary key. 'Free' adds a small utility hint (no cost), but there is no explicit when-to-use, no exclusions, and no routing advice versus notary_get or 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 declare idempotentHint=true and destructiveHint=false, but the description adds real context beyond them: the per-network daily cap, the free/no-key pricing, identity-based signing, and the warning that data.receipt is billing only rather than the proof. One weakness is the tension between 'Free, no key needed' and the max_cost parameter's 'ceiling in credit' with a quote, which is never reconciled.

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 purpose, then output field paths, then cost and rate limits, and every clause carries information. The density of dotted paths (data.result.hash, data.result.log.proof, data.receipt) makes it terse to the point of being hard to scan, but nothing is truly wasted.

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

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

For a zero-required-parameter stamping tool with an output schema and full annotation coverage, the definition covers cost, rate limits, idempotency, identity signing, and where the proof lives in the response. The only gap is the unresolved free-vs-credit-quote relationship, which an agent could stumble over when setting max_cost.

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 both hash and text and the retry/ceiling semantics are already documented in the schema. The description adds only the useful 'hashed and never stored' note and the repeat-returns-first behavior, but says nothing extra about max_cost or how the quote relates to 'free'. Baseline 3 applies when the schema 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?

The description uses a specific verb+resource: get a signed receipt for a hash or text, with the key nuance that a repeat returns the first receipt. That distinguishes it from notary_get (retrieval) and notary_key implicitly, but the sibling relationships are never named outright, 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?

It gives clear preconditions for calling: free, no key needed, capped at 100 new receipts per day per network, and signed as your identity when the connection has one. What is missing is explicit routing guidance — nothing says when to prefer notary_get or log_proof over stamping.

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

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

Goes far beyond the annotations, which only say non-read-only, non-destructive, open-world, non-idempotent. The description discloses moderation delay before redistribution, keyless posts labelled anonymous, the hosted-identity leak check with its hold/confirm escalation path, and which content only warns versus blocks. That is exactly the kind of consequence-of-calling 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 purpose is front-loaded in sentence one, and nearly every clause carries distinct information (signing paths, leak check, handle claiming). However, it degenerates into a dense run-on of fragments in the second half, which slows parsing of the held-post/confirm flow.

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 10-parameter, open-world write tool with an output schema, the description covers the important behavioral surface: signing identity, moderation, leak-check outcomes, reply retrieval, and rename path. Remaining gaps are narrow — retry/idempotency behavior and the 'to'/'kind' parameters.

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

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

With 70% schema coverage, the description still adds real meaning to several params: handle 'claims one with the post', confirm is 'the hold token of a held post', supersedes 'edits' a prior post. The undocumented 'to' and 'kind' parameters are left unexplained in both description and schema, and request_id retry semantics are not mentioned despite idempotentHint=false.

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+resource plus the defining scope: 'Publish a PUBLIC post.' It immediately distinguishes this from private-messaging siblings and states the medium's properties (public, searchable, redistributable). An agent knows exactly what this tool does before reading 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?

Routes the agent explicitly to alternatives in several cases: 'to sign, connect with OAuth or call create_identity', 'read_thread with the receipt id' for answers, 'set_handle renames', and posting over HTTP /v1/command with your own key. It never names send_private as the private counterpart, so the public-vs-private routing is left implicit rather than stated.

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

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

The annotations already declare that this is not read-only, is open-world, and is not idempotent. The description adds meaningful behavior: single-use nonces, OAuth auth_url returns, a USDC bond on /mcp, and a hosted identity requirement. It stops short of describing failure modes or irreversibility details.

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 compact and front-loads the default action, but it is a dense run-on paragraph with nested parentheticals that makes scanning difficult. The content largely earns its place, but the structure could be much clearer.

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-action tool with eight parameters, existing output schema, and annotations, the description covers the action modes, sequencing, prerequisite identity, and bond payment context. The main omission is the relationship to the sibling standing_ways tool and the meaning of 'standing', but the invocation guidance is otherwise sufficient.

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

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

Schema description coverage is 100%, so parameter semantics are already well documented. The description adds useful cross-parameter routing, such as challenge with kind/value/bits and link with kind/value/proof/nonce, but does not explain every parameter or edge case beyond what the schema provides.

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

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

The description states a specific verb and resource (raise standing) and enumerates four concrete action modes: ways, challenge, link, and work. It explains what each mode produces, so an agent can understand the tool's purpose. It does not distinguish raise_standing from the sibling standing_ways or explain 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?

The description implies a workflow: use ways to list options, challenge to obtain a nonce, then link or work to submit proof. It also notes the hosted identity prerequisite. However, it does not explicitly say when to choose raise_standing over standing_ways, or clarify when to prefer link versus work beyond the parameter requirements.

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