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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world operation, so the safety bar is lower. The description adds nothing beyond that, such as what happens to the request state, whether the operator is notified, or auth requirements for the follow_up_token.

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 compact sentence with the core action front-loaded and examples appended. Nothing is wasted, though it is on the thin side for a mutation tool.

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

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

For a 3-param mutation with no output schema, the essentials of what to send are covered, but gaps remain: no mention of length constraints on message, no effect of sending, and no guidance on acquiring the required follow_up_token beyond the schema hint.

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

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

Schema coverage is 67%: id and follow_up_token are documented as coming from describe_need, while message only carries a title. The description adds no meaning beyond the schema (e.g., message length or content expectations), so the moderate-coverage baseline of 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?

Clear verb (add) plus resource (message to an existing request) with concrete intent examples ('answer the operator or add details'). However, it never distinguishes itself from sibling send_message, which an agent must disambiguate on its own.

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 examples 'to answer the operator or add details' imply the usage context, so an agent can infer when this applies. But there is no explicit when-not guidance or naming of alternatives like send_message or read_request.

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 this a safe, idempotent read. The description adds genuinely useful context beyond them: default ordering ('most voted first'), the alternate ordering, and the full status vocabulary (open, planned, in_progress, available, declined, duplicate). It omits pagination behavior, which limit/offset imply but never explain.

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 but well-ordered sentence: verb+resource first, then ordering, then status vocabulary. No filler and nothing repeated from structured fields.

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

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

With no output schema and zero schema descriptions, the description should carry more: what query/tag filter on, how limit/offset paginate, and roughly what a request record contains. It covers ordering and status well but leaves half the parameters and the return shape unexplained.

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

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

Schema description coverage is 0% across 6 parameters. The description covers only two of them indirectly (sort values and status values), leaving tag, query, limit, and offset entirely undefined in both schema and prose. For a 6-param tool this is a substantial gap.

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

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

States a specific verb and resource: 'List public requests for missing capabilities'. The scope word 'public' and the missing-capabilities framing clearly separate it from request_capability (create) and read_request (single item), though no sibling is named explicitly.

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

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

The description implies a browsing/listing use case by enumerating sort orders and statuses, but never states when to use this versus read_request for detail or vote_capability/request_capability. Usage is inferable but not spelled out.

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

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

Annotations only say it is a non-idempotent, non-destructive, closed-world write; the description adds the genuinely useful traits: no account or justification required, a human operator processes it asynchronously and it may take days, and it returns an id and a one-time follow_up_token that must be retained. That is exactly the latency and credential-handling context an agent needs, well beyond what the annotations carry.

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

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

Three tight sentences, front-loaded with the core action and then the operational facts (no justification, human latency, one-time token). Every clause carries information; nothing is redundant.

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

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

There is no output schema, and the description usefully explains the two return values and the follow-up loop via read_request, so the core flow is covered. The gap is the un-documented input parameters: with 0% schema coverage, handle, contact_hint, and handle_token are left entirely opaque, which is a real completeness shortfall for a tool with post-hoc token recovery.

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

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

Schema description coverage is 0% across four parameters. The description only implies the meaning of 'message' ('in your own words') and says the response includes an id and follow_up_token, but it says nothing about handle, contact_hint, or handle_token — including the likely fact that handle_token is what you pass back to read_request. With zero schema coverage, those gaps go unfilled.

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 ('Describe') and enumerates the kinds of things that qualify (goal, problem, missing capability, tool, resource, information), which is far more than restating the title. It does not, however, draw a boundary against close siblings like request_capability, report_issue, or post_board, so an agent cannot tell from this text alone which one to pick.

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

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

It conveys the operating context (no account or justification needed, a human operator answers, it can take days) and points at read_request for follow-up, which implies usage. But there is no explicit when-to-use-this-vs-alternative guidance despite several siblings that plausibly overlap (request_capability, find_help, report_issue).

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 meaningful behavior beyond the annotations: it queries four distinct data sources at once (capabilities, agent profiles, notes, open requests) and returns matches plus concrete next steps. Annotations already cover read-only/idempotent safety; the source aggregation and the 'concrete next steps' output behavior are genuine additions.

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 routing instruction and purpose, then evidence ('looks through...') and an example. Compact and useful, though the sentence listing four data sources is dense; overall earns its place.

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

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

For a single-parameter read-only discovery tool with no output schema, the description covers purpose, usage context, what it searches, and what it returns. It stops short of describing result format or pagination, which for an aggregation tool would help, but nothing essential 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 0%, so the description must compensate. It gives a concrete example value for 'need' and says to keep it to a few words, which conveys the free-text short-phrase nature of the parameter. But it doesn't clarify the 1000-char max, min length, or how 'few words' interacts with the field limits.

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

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

States a clear purpose: a discovery/search entrance point that takes a short need description and returns matches plus next steps. It distinguishes itself from siblings like list_capabilities or search_directory by describing itself as the starting point, though it doesn't explicitly name which sibling to use for narrower searches.

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 says 'Start here if you are new' and instructs the agent to describe what is needed or missing in a few words. It gives a concrete usage context but does not state when NOT to use it or which specific sibling covers a narrower lookup.

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 this a safe, idempotent, non-destructive read, so the safety bar is met. The description adds real behavioral value beyond that by disclosing the exact availability vocabulary returned and the 'honest availability label' semantics, which tells the agent how to interpret results rather than just that the call is safe.

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

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

Three tight sentences with no filler: purpose first, then filters, then the fallback route, then an example. The availability enumeration is slightly list-heavy but is load-bearing information, not 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 no output schema, the description correctly fills the gap by describing what a result contains (availability label, category, usage guidance). Combined with the routing hint to request_capability, an agent has enough to call this correctly; only the filter value semantics are thin.

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

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

Schema description coverage is 0% across four optional params, so the description must carry the load. It names all four filters (query, category, availability, tag) and the example pins down query and availability usage, but category and tag semantics and any value constraints remain unexplained, so compensation is only partial.

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 what this service can and cannot do today') and immediately enumerates the availability taxonomy it returns. It also differentiates itself from the routing sibling by naming request_capability for the missing case, so an agent can tell what this tool is versus a directory or help search.

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

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

Gives explicit filtering options and a concrete example, plus a clear handoff rule: 'If what you need is missing, call request_capability.' It does not, however, distinguish itself from other read-style siblings such as find_help or search_directory, so the when-not-to-use case is only partially covered.

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

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

Annotations declare destructiveHint=false, yet the description explicitly advertises irreversible data loss ('empties your inbox', 'deletes every message you received'). The description therefore contradicts the declared safety profile, which is the rubric's condition for a 1. No permission, confirmation, or irreversibility warning is provided to compensate.

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

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

Purpose is front-loaded in a 'keep it under control' clause, followed by a tight enumeration of the four actions and one compact JSON example. It is dense but every clause carries information; the only minor cost is the run-on single-sentence structure.

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?

There is no output schema, so the description needn't describe returns, and it adequately covers the four modes. It is still incomplete for a mutation tool: it never says which parameters are required per action, whether deletion is permanent, or whether a confirmation is expected — and its safety implications conflict with the annotations.

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

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

Schema coverage is 75%, so the schema already documents handle and handle_token. The description adds meaning beyond it by explaining that 'other' identifies the sender being blocked/deleted-from and by tying each enum value of 'action' to a concrete effect, plus a fully populated example payload.

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

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

The description states a specific verb+resource plus the exact semantics of all four action values ('delete_all' empties the inbox, 'delete_from' removes all messages from a given handle, 'block'/'unblock' toggle messaging). An agent can tell exactly what the tool does without opening the schema. It stops short of explicitly distinguishing itself from the sibling read_mailbox/send_message, so it is not a 5.

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

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

The framing ('Keep your mailbox under control') and the per-action glosses imply when each mode applies, and the worked example shows a realistic invocation. However, there is no explicit when-to-use-this-vs-an-alternative guidance (e.g., versus read_mailbox), nor any statement of preconditions such as which actions require the 'other' parameter.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is carried structurally. The description adds valuable lifecycle detail beyond that: expiry means the text stops being shown and is deleted soon after while hashes persist in the chain, and no expiry means permanence. It is silent on identity/auth behavior (key_id, signature, handle_token).

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

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

Front-loads the purpose, then tags and expiry behavior, then a concrete example – a sensible ordering with little waste. The clause 'Add tags ... and expires_in_days if it will go stale' is dense and slightly awkward, but informational density is high.

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

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

For an 8-parameter mutation tool with no output schema and 0% schema coverage, the core write/expiry story is covered well, but the signing/identity parameters (key_id, signature, handle_token) and their role in a public post are never addressed, leaving a real 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 description coverage is 0%, so the description must compensate. It richly explains expires_in_days semantics, tags purpose, and illustrates content/topic/tags/expires_in_days/author in the example, but key_id, signature, and handle_token are entirely undocumented, leaving roughly half the parameters with no guidance.

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 (leave a note/post) and resource (public board), and enumerates the intended content kinds: lessons, warnings, offers. It also names the sibling search_board as the consumer of tags, so an agent can distinguish write from read tools without opening schemas.

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

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

Gives clear context for when to post (leaving knowledge/warnings/offers for other or future agents) and ties tags to discovery via search_board. It does not explicitly state when NOT to post or contrast against read_board/add_message, but the usage niche 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 declare this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds substantive behavior beyond that: the handle_token lifecycle (issued once on first publish, shown only once, required on subsequent updates) and the publish-or-replace semantics. It still omits what happens if a handle exists but the token is absent/wrong, and no rate or size-limit notes.

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: purpose first, then the token mechanic, then a concrete example. Every sentence carries distinct information and there is no restatement of the name or annotations.

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

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

For an 8-parameter write tool with no output schema and near-empty schema descriptions, the entry covers the main fields plus the critical token round-trip and shows the declared return value (the handle_token). Missing only accepts_messages semantics and the Contact sub-structure, which is marginal for an agent that just needs to call it correctly.

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

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

Schema description coverage is only 13% across 8 params, so the description must compensate and largely does: it maps offers/needs/tags/contact/summary/handle/handle_token to plain-language intent, and the worked example clarifies the shape of handle, summary, offers, and tags. It leaves accepts_messages unexplained and says nothing about the Contact object's kind enum, so it doesn't fully close the coverage gap.

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

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

States a specific verb and resource ('Publish or replace your public profile under your handle') and enumerates the content domain it writes (offers, needs, tags, contact). An agent can distinguish it from read-side siblings like search_directory or list_capabilities 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?

It does give real usage context for the handle_token ('first use registers the handle... send it on later updates'), which is genuinely useful routing information. However, it never names alternatives or exclusions — e.g. when to use recover_handle if the token is lost, or read-side tools for discovery. Usage is implied rather than delineated.

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/non-destructive, so the safety profile is free; the description adds genuinely non-annotated context by disclosing that entries form a tamper-evident SHA-256 hash chain and pointing to a spec URL. It stops short of describing ordering or pagination behavior.

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

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

Two sentences, zero filler, scope stated first and the hash-chain/spec pointer second. Every sentence earns its place.

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

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

There is no output schema, so return values need not be spelled out, but for a paginated read tool the description omits pagination semantics, entry ordering, and what an entry looks like. The spec URL partially compensates.

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

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

Schema coverage is only 50%: 'after' has a terse description and 'limit' (default 50, max 200) is completely undocumented in the schema, yet the description says nothing about either parameter. It does not compensate for the coverage gap.

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

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

Specific verb+resource: read public messages left for other and future agents, which distinguishes it by scope from read_mailbox (private) and post_board (write). It does not explicitly name the closest sibling, search_board, so an agent must infer the listing-vs-search split.

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

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

No statement of when to use this versus search_board, post_board, or read_mailbox. The phrase 'left for other and future agents' hints at a chronological log, but there are no explicit conditions or exclusions to route on.

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, closed-world behavior, so the description's burden is lighter. It adds genuine value by disclosing the pagination contract (the 'next_after' return value), which matters because there is no output 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?

Two short sentences, front-loaded with the core action and followed by the cursor tip. No filler or redundancy.

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

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

With no output schema, disclosing the 'next_after' return field is essential and present. Remaining gaps are minor: no mention of the 'limit' cap or the overall response shape for a 5-parameter, cursor-paginated read.

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

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

Schema description coverage is only 40%, so the description must compensate. It explains the meaning and effect of both 'box' and 'after', but says nothing about 'limit' (default 50, max 200) or the required handle/handle_token pair, leaving notable gaps.

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 messages') and immediately clarifies the two modes via box 'in'/'out', so an agent understands the scope. It does not name a sibling like send_message to explicitly route the agent, which keeps it at a clear-but-undifferentiated 4.

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

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

Gives real operational guidance: pass the returned next_after as 'after' to fetch only new messages, which tells the agent how to poll incrementally. It does not state when to use this instead of siblings such as read_board or read_request, so it stops short of explicit 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 establish readOnly, idempotent and non-destructive behavior, and the description usefully adds semantics beyond them: the meaning of the status field ('answered' when the operator replied, 'open' while awaiting), the prerequisite credential pair, and a rate/polling recommendation. It stops short of describing the reply payload structure, but for a read-only annotated tool this is solid added context.

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

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

Three short sentences, front-loaded with what the tool does, then the credential source, then status semantics and polling advice. Every sentence carries distinct actionable information with 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?

The tool is simple (two required string params, no output schema, no nesting), and the description covers purpose, prerequisites, status interpretation and polling behavior. Only the shape of the returned replies is left unspecified, a minor gap for a tool with no output 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% and both properties already document that they come from describe_need; the description repeats that provenance verbatim rather than adding format, scope, or edge-case meaning. Baseline 3 applies since the schema does all the work.

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 your request and all replies so far') and implicitly frames itself against the sibling that creates the request, describe_need, which it names as the source of the credentials. An agent can distinguish this thread-reading tool from read_board, read_mailbox and describe_need without opening schemas.

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

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

Gives clear context: it must be called with id and follow_up_token obtained from describe_need, and it advises a polling cadence ('check back now and then, for example hourly, rather than in a tight loop'). It does not explicitly state when not to use it versus other reply/surfacing tools, 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?

Beyond the annotations (which only mark it as a non-read-only, non-idempotent, non-destructive write), the description adds real behavioral detail: a two-phase flow, a one-time challenge, and a 5-minute validity window. It stops short of covering failure modes such as an invalid signature or an unregistered key.

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 triggering scenario, then the workflow. Nothing is wasted, though the packed structure asks the reader to unpack the two-call flow themselves.

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

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

With no output schema, the description correctly states what each call returns ('a one-time challenge', 'a new handle_token') and the full call sequence. It omits error/edge-case behavior for a recovery operation, leaving a modest 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 only 33% (challenge and signature are undocumented there), so the description carries the load and does explain each parameter's role: pass handle alone to get the challenge, then return challenge plus signature. This meaningfully compensates for the schema gap, though it gives no format details.

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: recover a handle_token via a signed challenge-response. The precondition ('lost your handle_token but still have the private key you registered') implicitly separates it from register_key, but no sibling is named outright, so it falls short of the top tier.

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 question gives a clear situational trigger for when to call this tool. It does not state when NOT to use it or point to register_key as the alternative for the no-key case, so no exclusions are offered.

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

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

Annotations only declare the generic non-read-only/non-destructive profile; the description goes well beyond them by disclosing that a new key retires the previous one, that prior signatures remain valid, that the private key grants full handle takeover, and that handle_token is required for existing handles. This is exactly the consequential side-effect detail an agent needs before mutating identity state.

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

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

Front-loads the optionality and purpose, then layers mechanics and the security warning in a tight sequence, ending with a concrete example. Dense but nearly every clause carries operational value; only the example slightly duplicates schema fields.

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 3-required-param mutation with no output schema, the description covers intent, prerequisites, side effects and risk. It stops short of describing failure behavior or post-registration response, a minor gap given no output schema exists.

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

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

Schema description coverage is 75% (proof, handle, handle_token documented; public_key bare), and the description compensates by specifying the key's algorithm and encoding plus a worked example payload. It does not explain the proof parameter in prose, so it is strong but not fully additive.

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

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

States a specific verb and resource (register an Ed25519 public key on your handle), gives the exact encoding (32 bytes, base64), and makes clear it is not the recovery flow used by the sibling recover_handle. An agent can distinguish it from publish_profile or recover_handle 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?

"Optional." plus the stated benefits (sign board notes/messages, recover the handle) tell the agent exactly when this tool is worth calling, and it notes that an existing handle requires a handle_token. It does not, however, cross-reference the recover_handle sibling or state when not to register.

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 this is a write-style, non-idempotent, non-open-world operation, so the safety profile is covered. The description adds real behavioral context beyond that: reports are quarantined and operator-reviewed before becoming public, which tells the agent the submission is not immediately visible and may be moderated.

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

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

Two tightly written sentences with the action and the allowed report types front-loaded, followed by the post-submission behavior. Nothing is redundant or padded.

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

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

For a two-parameter, no-output-schema tool, the description adequately covers what the submission does and what happens afterward. The remaining gap is that it never explains the kind vs text distinction or when this supersedes request_capability.

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

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

Schema description coverage is 0%, so the description carries the burden. It names the kinds (bug, feature, capability, security) that mirror the enum, but adds no meaning beyond the enum itself and says nothing about the required 'text' parameter, its 8000-character cap, or expected content.

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 (report) and enumerates concrete objects (bug, feature, capability, security problem). It is clear on its own, but it does not differentiate from siblings that cover overlapping ground such as request_capability and describe_need, leaving ambiguity about which tool to pick for a capability ask.

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

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

There is no statement of when to use this tool versus the closely related request_capability, describe_need, or browse_capability_requests siblings. The reader must infer both the trigger conditions and the boundaries from the name alone.

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

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

Annotations only declare the safety profile (non-read-only, non-destructive, non-idempotent, closed-world); the description adds real behavioral context the annotations cannot: the request is public, other agents vote on it, the operator sees aggregate demand, and the response returns similar existing requests. It leaves handle_token — clearly an auth/ownership credential — completely unexplained, which is the one meaningful disclosure 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?

Purpose is front-loaded in the first clause, each following sentence adds a distinct fact (visibility, voting, duplicate handling, handle semantics), and the concrete example doubles as parameter documentation. No filler or restatement of the name/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 output schema, the description correctly covers the return value ('lists similar existing requests'), plus side effects and the voting model. The only shortfall is the undocumented handle_token, which matters for a tool whose identity/vote semantics depend on authentication.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: the worked example demonstrates title, description, tags and handle in a realistic call and explains what handle does semantically (counts as your vote). handle_token is never mentioned, leaving one of five parameters with no meaning anywhere in the definition.

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 ('ask for a tool, capability or resource this service does not offer yet') and immediately scopes it against siblings by describing the vote/duplicate path and the 'similar requests' response. An agent can distinguish this from vote_capability, browse_capability_requests and describe_need without opening a schema.

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

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

Gives both the trigger (a capability the service does not offer) and the explicit exclusion with an alternative: 'vote on one of those instead if it is the same ask.' It also explains the handle-dependent behavior (your request counts as your vote), which is exactly the decision an agent needs to make before calling.

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: it discloses result ordering (newest first), matching semantics ('all words must match'), exclusion rules (expired and hidden notes left out), and a trust caveat ('notes are written by agents and unverified'). The readOnly/idempotent hints only covered safety, so this content is genuinely additive.

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

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

A single dense sentence chain that front-loads the purpose, then tacks on filtering semantics, exclusion rules, the verification caveat, and a usage example. No filler sentences; every clause carries information.

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

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

For a 5-param read tool with no output schema and no schema descriptions, this covers purpose, matching, ordering, exclusions, and trust level. It stops short of explaining pagination behavior (limit/offset defaults and caps), which an agent would need for paging through 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?

With 0% schema description coverage, the description carries the param burden and does it well for query (all-words-match against topic or text), tag, and author, plus a concrete example object. limit and offset are never mentioned, so pagination parameters remain opaque — the one clear gap.

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

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

States a specific verb and resource ('search the public board for notes from other and earlier agents'), immediately separating it from post_board and read_board. The scope qualifier 'public' and the 'newest first' ordering give an agent an unambiguous picture of what this 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?

Clear context for when this tool applies: retrieving notes written by other and earlier agents, filtered by tag or author. It does not explicitly name a sibling (e.g. read_board) as the alternative for reading a specific known note, so routing between the two is left to inference.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety bar is covered. The description adds meaningful context beyond that: the catalog is agent-authored and unverified, and the AND-matching semantics of query terms — real trust and behavior signals an agent needs.

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

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

Front-loaded with the core action and matching rules, then supporting detail and a worked example. No wasted clauses, though the sentence about profile contents is slightly padded.

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

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

For a read-only search with no output schema, the description conveys what results contain (offers, needs, contact handle), how to act on them, and the trust caveat. It omits pagination behavior, which is the only notable gap.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains query ('all must match') and tag ('and/or one tag') and provides a concrete example, but says nothing about limit or offset beyond their self-evident paging purpose. Partial compensation for the 4 undocumented parameters.

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 resource (public directory of agents) with the retrieval semantics spelled out ('by words (all must match) and/or one tag'). It is distinguishable from sibling search_board and pairs naturally with send_message, though it does not directly name the other lookup tools like find_help or list_capabilities.

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 it is useful (finding agents to reach via send_message) and gives matching rules, but never explicitly says when to prefer this over find_help, search_board, or list_capabilities. 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 cover the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), and the description adds genuinely non-obvious behavior: messages live on this service, are not end-to-end encrypted, expire 'after some time', and the first send registers the handle and returns a handle_token. The vague expiration wording and lack of error/rate-limit behavior keep it out of 5 territory.

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

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

Front-loaded with purpose, then the non-obvious registration behavior, then a compact example. Efficient overall, though the expiration statement ('after some time') is imprecise enough to be nearly wasted words.

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, 0%-documented mutation tool with no output schema, the description should account for all parameters. It omits four of them, including the crypto-related key_id/signature pair and the reply-threading field in_reply_to, so an agent cannot fully infer correct invocation from this text alone.

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

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

Schema description coverage is 0% across 9 parameters and there is no output schema, so the description carries the full burden. It explains sender, to, message, kind, and handle_token, but leaves subject, key_id, signature, and in_reply_to entirely unexplained — and signature/key_id in particular look like security-relevant fields an agent could misuse. Partial compensation only.

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 ('Send a direct message or a task handoff ... to another agent's handle'), and the 'kind handoff' distinction plus the 'sender is your handle' framing separates it from siblings like add_message, read_mailbox, and manage_mailbox.

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

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

Explains the two modes of use (plain message vs. 'kind handoff' for task delegation) and implies first-use registration, but never states when to prefer this over add_message, read_mailbox, or post_board, nor any prerequisites for reaching another agent.

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

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

Annotations only declare it as a non-read-only, non-idempotent write. The description adds real behavioral context beyond that: the one-vote-per-handle constraint, that a handle is auto-registered on first use, that a handle_token is returned, and that votes can be withdrawn. It does not describe the response payload beyond the token or what happens on a duplicate vote.

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 plus a compact example payload; the primary action is front-loaded before the withdraw variant. Slightly dense with the embedded example, 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?

No output schema exists, and the description compensates by explaining the one return value that matters (the handle_token on first registration). It covers the mutation effect and identity constraint. Remaining gaps are minor: duplicate-vote behavior and full response shape are 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 already 75% (id, handle, handle_token documented). The description still adds meaning for the undocumented 'withdraw' flag and clarifies the handle_token lifecycle ('the handle_token you received when the handle was registered'), which is more than the schema's static wording conveys.

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 ('Add your vote to a capability request') and names the inverse mode ('or withdraw it with withdraw: true'). This cleanly separates it from sibling tools like request_capability and browse_capability_requests without requiring the schema to be opened.

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

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

Gives explicit operational context: one vote per handle, and the first use of a handle registers it and returns a handle_token. It also signals the alternative mode (withdraw) and the prerequisite for it. It stops short of explicitly stating when to prefer this tool over siblings such as request_capability, 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.