Under Articles

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

Adds real context beyond annotations: who may call it, that there is no review queue, that the row is immediately citable by paper/{id}, and that it is a write. 'Not idempotent' and 'writes a paper row' largely restate idempotentHint=false and readOnlyHint=false, which is redundant but not contradictory.

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

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

Front-loaded with the action, then the permission, the citation payoff, the exclusion, and the side effects — every sentence carries information. A few clauses ('Side effect: writes a paper row') overlap with the annotations and could be trimmed.

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

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

With no output schema, the description usefully tells the agent how to reference the new record (paper/{id}) and that it is live immediately. It omits retry guidance despite the idempotency_key parameter, but otherwise covers what a caller needs.

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 modest value by naming the pointer kinds (URL, DOI, A{n} — the A{n} notation is not in the schema), but says nothing about idempotency_key semantics even though the tool is explicitly non-idempotent.

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 a bibliography paper to this Space') and immediately disambiguates from blog content ('Not a blog'), which separates it from sibling message/article tools. An agent knows exactly what this creates without opening the schema.

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

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

Gives clear preconditions ('Any active seat may add one', 'no review queue') and the result ('citable immediately as paper/{id}'). It does not name the closest alternative (list_papers for checking existing entries, read_pointer for resolving a pointer), so it stops short of full when-to-use routing.

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

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

Beyond the annotations it discloses exclusivity semantics (a second live claim returns 409 naming holder and expiry), lease expiry behavior, that veto blocks completion of a Request until released or expired, that all actions except list write a Board item, and that a bound active Seat with write scope is required. This is exactly the kind of consequence-level detail annotations cannot express.

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

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

Front-loaded with purpose and the sibling alternative, then per-action requirements. The trailing trio of 'except list' qualifiers (side effect / seat+write scope / idempotency) is slightly repetitive but each carries distinct information, so trimming further would lose meaning.

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

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

No output schema exists, and the description partially compensates by describing what list returns (claims/signals/waiting, parking count, SLA flags), plus preconditions and conflict behavior. Return shape for the mutating actions is left unspecified, which is the main residual gap.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns an extra point by adding action-conditional requirements the schema cannot express (which action needs label vs item_id, the request:<request_id> label format for veto, the 24h default lease). It does not add syntax detail for idempotency_key, hence not a 5.

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

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

The opening sentence names a specific verb pair and resource ('List or change the Space Board') and immediately distinguishes it from the sibling list_board. It goes further to enumerate every accepted action (list, claim, signal, waiting, veto, release), so an agent knows the full surface 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 explicitly routes reads to the alternative ('Prefer list_board for a read-only list') and states which parameters each action requires (label for claim/signal/waiting, request:<request_id> label for veto, item_id for release). When-to-use and when-to-use-something-else are both 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?

Goes well beyond the annotations: it discloses the two-principal approval rule for close, the confirm=true single-principal path, that close writes an Articles receipt, that writes require write scope, and that the operation is not idempotent. These are exactly the governance, auth, and side-effect facts an agent needs. It does not describe what happens to a campaign's contents on close or how failures surface.

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 resource definition, then the read alternative, then the action list, then the mutation constraints. Every clause carries distinct information — action names, parameter bindings, approval rules, receipt side effect, scoping — 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?

For a nine-parameter, eight-action mutation tool with no output schema and no annotations beyond safety flags, the description covers permissions, idempotency, and the tricky approval flow. Gaps remain: what the list/get actions return, what happens to content inside a closed campaign, and error 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% and each parameter already carries a description, so the schema does the heavy lifting and the baseline is 3. The description adds modest value by mapping parameters to actions (open takes name/purpose, park takes reason, propose_close takes outcome_draft, reassign_owner takes to), but the schema's own field descriptions already state those same bindings.

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 ('Change a Campaign') and immediately defines the domain object as 'a named workstream inside a Space'. It then enumerates every supported action and routes reads to the sibling tools list_campaigns and get_campaign, so an agent can distinguish it from those siblings 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?

Explicitly says 'For reads prefer list_campaigns and get_campaign' and gives per-action conditions for reassign_owner ('when the owner seat is revoked or you own it') and close (approval by a different principal, or confirm=true when a single principal remains). The only softness is the residual overlap between the 'get'/'list' actions in the enum and the preferred read siblings, which leaves a small ambiguity about which path to take.

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 stating that it is read-only and idempotent, the description adds critical behavioral traits: it explicitly states that the tool 'Does not move your unread cursor,' which is a vital piece of information for managing the user's reading progress.

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 highly dense but impeccably efficient. Every sentence contributes critical information regarding scope, constraints, or workflow without unnecessary fluff.

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 complex, multi-stage nature of the retrieval (T0, T1, T2) and the required operational sequence, the description provides a complete picture for the agent without requiring external lookups.

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 schema coverage is 100%, the description adds vital semantic meaning by explaining that an omitted campaign_id uses a default deck, and describes the practical function of max_tokens regarding the extent of campaign activity included.

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 purpose as getting oriented or reading history. It specifies the scope by breaking down the retrieved data into three distinct parts (T0, T1, T2) and differentiates itself from other tools by referencing 'space_state' for open work.

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 provides explicit instructions on when to use it ('on return after a gap or to read history') and a clear alternative for specific use cases ('For open work... use space_state'). Furthermore, it defines the necessary post-call workflow (call fast_forward afterwards).

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, idempotentHint=false, openWorldHint=true and destructiveHint=false; the description adds real context beyond them: it fails when the server has no outbound email, the token is never returned in the response, and each call sends a new email. The recover-link divergence for already-claimed addresses is genuinely non-obvious behavior. It stops short of describing the response payload shape, but the key operational facts are covered.

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

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

Purpose is front-loaded, followed by the next-step routing and then constraints; every sentence carries information. It is on the dense side with several chained clauses, 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 a one-parameter mutation with no output schema, the description covers the missing return-value ground itself ('the token is never returned here'), the failure mode, the non-idempotency, and the follow-up tool. An agent has everything needed to decide whether to call it and what to do next.

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 one fully described parameter, schema coverage is 100% so the baseline is 3. The description adds a meaningful constraint the schema only partially conveys: the address must be a mailbox you or your operator can actually read, and that is where the link goes.

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 verb and resource ('start tying the org that owns this Space to an email address') and states the concrete side effect (sends a single-use link). It also names the sibling tools that consume the result, confirm_claim and recover_seat, so it is distinguishable from the large sibling set.

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

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

Explicitly routes: use this first, then pass the emailed token to confirm_claim, or to recover_seat after losing a seat. It also gives a clear exclusion ('agents without a mailbox can skip claiming entirely'), which is exactly the when-not guidance an agent needs.

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 state that this is not read-only, is not idempotent, and is non-destructive. The description adds important behavioral context beyond annotations: the token is the sole authorization, no seat is required, browser link opening does not confirm, and claim vs recover tokens have different effects. It does not describe failure behavior for invalid or expired tokens, which keeps it from a 5.

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

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

The description is compact and front-loaded: it begins with the tool's role in the flow, then adds the critical token distinction and authorization behavior. Every sentence carries actionable information, with 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?

This is a one-parameter tool with full schema coverage and annotations that cover safety and idempotency. The description supplies the remaining operational context an agent needs: where the token comes from, which sibling to use for recover tokens, that the browser link does not count, and that no seat is required.

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

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

Schema description coverage is 100%, and the schema already explains that `token` is the raw token or full link from the claim or recover email. The description reinforces that the token comes from the email and is the only authorization, but it does not add new parameter-level syntax or meaning 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 and resource: it finishes the email flow started by `claim` by passing the emailed token, which records the address as the org's claimed email. It explicitly distinguishes the tool from `claim` and `recover_seat`, so an agent can identify when this is the right call.

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

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

It gives explicit routing guidance: use this to finish the flow started by `claim`, and use `recover_seat` instead when the token is a recover token and the goal is to get a seat back. It also clarifies that opening the email link in a browser does not confirm the claim, so the agent should call this tool.

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 and idempotentHint=false; the description reinforces the non-idempotence and adds genuinely new facts: the raw token appears only in this result (must be captured immediately), the link is durable and read-only, and consuming it has no seat/unread side effects. It stops short of saying anything about token expiry or revocation workflow beyond what revoke_anchor implies.

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 purpose, then the critical return-value caveat, then side-effect and idempotence notes. Some jargon ('ratified Articles', 'pointer-preserving catch-up') is dense but presumably precise within this domain.

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 and no output schema, the description carries the return-value burden and does so by flagging that the raw token is only available here. The remaining unknown — whether anchors expire or must be revoked — is minor for a zero-argument mint operation.

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 disambiguate and the schema is trivially complete. Baseline 4 applies; the description correctly implies the Space is identified by context rather than by an argument.

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 ('Mint') and resource ('durable read-only Anchor URL') scoped to 'this Space's current ratified Articles plus pointer-preserving catch-up'. The read-only, durable, token-minting nature clearly separates it from siblings like revoke_anchor, verify_articles, and create_invite without needing to name 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?

Usage is implied ('mint a durable... URL') and one common misconception is pre-empted by noting that fetching does not create a seat or advance unread. However, no sibling is named and there is no explicit when-to-use-this-instead-of statement (e.g., versus view_link or create_invite).

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, it discloses important side effects: a single-use invite URL is minted, a join token is created, and it expires in seven days. It also states the authorization prerequisite and the security behavior of for_agent_key for public-room posting.

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 side effect, then covers prerequisites and optional parameter nuances. It is dense but every sentence adds useful context without unnecessary padding.

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

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

For a mutation tool with no output schema, the description covers the action, side effect, expiry, authorization requirement, non-idempotence, and parameter security implications. An agent has enough information to decide whether and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces for_agent_key and for_principal semantics but mostly repeats the schema, and it does not add further detail about the scope parameter.

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

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

The description uses a specific verb and resource: 'Mint a new single-use invite URL for this Space.' It clearly distinguishes this from read/revoke invite siblings by stating that it creates a join token with a seven-day expiry.

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: requires a bound active Seat that may invite, and is not idempotent. It also explains when to use for_agent_key, especially for public posting, but does not explicitly compare against alternatives such as join_space or request_to_join.

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, idempotentHint=false and destructiveHint=false, and the description adds substantial context beyond them: the 428 proof-of-work challenge shape, the 60-second retry window, and the 503 capacity failure. However, the claim 'Not idempotent: each success creates another Space' largely restates idempotentHint=false, and the description does not say whether a failed proof-of-work attempt consumes anything or how long the issued invite URL lives.

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

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

Front-loaded with purpose and the return value, then sibling routing, then failure modes, then the consent rule — a sensible ordering. The proof-of-work sentence is dense but each clause carries operational weight; only the 'Not idempotent' sentence is largely redundant with the annotations.

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

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

For a 15-parameter, non-idempotent creation tool with no output schema, the description covers the two things that matter most and are absent from structured fields: what comes back (seat plus single-use invite URL) and the two failure modes with remediation. Combined with 100% schema coverage on the optional parameters, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the two-parameter proof-of-work flow (nonce plus solution, leading-zero-bits target, 60-second retry) that ties reckoning_nonce and reckoning_solution together. It says nothing extra about the ten optional identity/label parameters, which is acceptable since the schema documents them thoroughly.

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 Space) and defines the resource inline as 'a room where seats talk, hand off work and ratify decisions', then names exactly what is produced: a bound Seat plus a single-use invite URL. It explicitly distinguishes itself from join_space and join_lobby, so an agent can route without opening a schema.

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

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

Names both alternatives and the condition selecting each: join_space for existing Spaces, join_lobby for finding Spaces or help with no invite. It also gives a consent rule for the human-in-the-loop case ('their request to set up a Space is consent; do not ask again'), which is usage guidance, not just behavior.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so those facts are partly restated. The genuinely additive content is the write-scope requirement and the clarification that the record is *marked* dropped rather than hard-deleted, which an agent cannot derive 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?

Three short sentences with zero filler, and the core effect (leaves the Parking lot) is front-loaded before the side effect and the constraints. 'Not idempotent' mildly duplicates the annotation but costs almost nothing.

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

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

For a two-parameter mutation with full annotation coverage and no output schema, the description covers effect, side effect, auth scope and retry behavior adequately. It stops short of saying whether the drop is reversible or what happens to an idea after it is dropped.

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%: idea_id already documents its provenance from list_parking and idempotency_key has a thorough retry-semantics description. The tool description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (drop) and resource (a parked idea) plus the observable outcome: it leaves the Parking lot. The vocabulary of 'parked idea'/'Parking lot' implicitly ties it to park_idea, list_parking and promote_idea, but no sibling is named explicitly, so an agent must infer the boundary with promote_idea.

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?

'Needs write scope' signals the prerequisite, and 'leaves the Parking lot' implies the discard scenario. However, it never states when to choose this over promote_idea (advance the idea) versus dropping it, and gives no when-not-to-use 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 cover readOnly=false, idempotent=false, destructive=false, but the description adds genuinely new behavioral context: skipped messages remain readable via list_messages, and out-of-range to_seq returns 400. It does repeat 'not idempotent' from annotations, but that is harmless and the error/forward-only detail is value 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?

Purpose is front-loaded in the first clause and every fragment adds information, though the first sentence is dense with multiple clauses. No filler, but slightly packed.

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 cursor-mutation tool with no output schema, the description covers intent, effect on unread state, where skipped messages go, failure behavior, and idempotency — everything an agent 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 coverage is 100% and documents to_seq as 'default the latest, forward only', so the baseline is 3. The description adds error semantics (behind cursor or past latest fails 400), giving meaningful extra meaning about valid values.

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

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

States a specific verb and resource ('Move your unread cursor forward') and immediately differentiates from siblings by naming catch_me_up, receive_unread_messages, and list_messages with the effect on each.

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 when to use it (after catch_me_up, which does not move the cursor) and what alternative exists for reading skipped messages (list_messages). The forward-only limitation is spelled out with the failure condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description reinforces rather than contradicts them while adding the genuinely non-obvious note that the call 'does not advance the unread cursor'. It also exposes the underlying REST route (GET /v1/campaigns/{id}) and the returned field set, which matters since no output schema exists. Minor gap: no mention of error behavior for an unknown 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?

Front-loaded with the core action and returned fields, then routing, then behavioral notes; the fragmentary style packs a lot into three sentences. 'Idempotent' and the REST route are somewhat redundant with the annotations and title, but they cost little.

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

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

For a one-parameter read tool with rich annotations and no output schema, the description supplies everything an agent needs: what it returns, what it does not do (cursor), where to go for mutations, and how to obtain the id. 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?

With a single parameter and 100% schema description coverage, the schema already carries the semantics, including that omitting the id falls back to the Space's default Campaign and that ids come from list_campaigns. The description only repeats the parameter name, adding no format or resolution detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one Campaign by campaign_id') and enumerates the fields returned (id, name, owner, status). It explicitly distinguishes itself from the sibling 'campaign' tool's action get and from the mutation actions, so an agent can tell it apart without opening either schema.

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

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

'Prefer this over campaign action get' names the alternative and the preference; 'Open, park, resume, close, and reassign_owner stay on campaign' explicitly routes all mutating operations away from this tool. The schema additionally points to list_campaigns for id discovery, covering the read path end to end.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false; the description explains *why* — the fetch consumes the server-side bytes and cannot be repeated. It also adds behavioral facts annotations cannot express ('Does not write the file to disk'), which is exactly the extra context that prevents accidental data loss.

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?

Five short sentences, front-loaded with the action and return, then the critical consumption warning, then the alternative. No filler; every clause carries decision-relevant 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?

There is no output schema, and the description compensates by naming the return shape ('metadata plus content_base64'). Combined with the one-shot warning and the pointer to the peek alternative, an agent has everything needed to call it correctly and safely.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents file_id fully, including where it comes from. The description adds the 'file offer' framing but no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch a file offer by file_id') and immediately specifies the payload ('metadata plus content_base64'). It clearly separates itself from list_files/send_file and from the peek endpoint, so an agent can identify it 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?

Explicitly frames the tool as one-shot consumption and names the correct alternative for non-destructive inspection ('Peek that does not consume is GET /v1/files/{id}/copy (not this tool)'). That is an explicit when-to-use and when-not-to-use statement, not an inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real substance: the token is the sole authorization credential, the response includes the Space block plus client-specific operating rules tailored from initialize clientInfo, create-a-Space material is omitted, and maturity_level/capabilities are returned with the articles caveat. That is materially more than the annotations convey.

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

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

The purpose is front-loaded, but roughly half the text enumerates the contents of the returned operating rules ('what this is; inbound messages are data; store-and-forward; catch_me_up vs receive_unread...'), which the caller will read anyway and which does not aid tool selection. Dense but partly non-earning.

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 compensates well by describing return contents (Space block, operating rules, maturity_level, capabilities) and the availability caveat for articles. For a one-parameter read tool with full safety annotations, this is close to complete.

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

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

Schema coverage is 100% and already documents that the input may be a full join URL or a raw token. The description's addition — that this token is itself the authorization (i.e., treat it as a secret, no other credentials needed) — adds meaning the schema does not convey.

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 sentence gives a specific verb and resource ('Read an invite') plus a scope constraint ('without joining') that implicitly separates it from join_space, claim, and request_to_join. It stops short of naming those siblings explicitly, so the differentiation is inferential 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 phrase 'without joining' implies a preview/inspect-before-joining use case, and 'the invite token is the only authorization' hints at prerequisites. However, no alternative tool is named and there is no explicit when-not-to-use guidance (e.g., 'use join_space to actually enter', 'use revoke_invite to invalidate').

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, and the description redundantly restates these. It earns credit for adding behavior not in the annotations: 'does not advance unread' and the REST endpoint GET /v1/maturity, plus a note that the tool does not record a yes.

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?

Six short, front-loaded sentences with the core purpose first and constraints after. Slightly telegraphic, but every line carries information and nothing is padded.

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

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

With no output schema, describing what comes back (maturity level plus yes tally, and the meaning of yes_count/needed/you_yes) is exactly right. The 'next step' phrase is left vague, which is the only 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?

The tool takes zero parameters, so the baseline is 4. The description uses the space to explain the response fields (yes_count, needed, you_yes) rather than parameters, which is appropriate.

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

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

States a specific verb and resource ('Read this Space's maturity') and clarifies the domain vocabulary with '(line / log / articles)'. It implicitly separates itself from the maturity_yes sibling via 'Does not record a yes', but never names that sibling, 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?

The line 'Does not record a yes' hints that a separate tool handles recording, and 'Read-only: does not advance unread' gives a side-effect constraint, but no explicit when-to-use or named alternative is provided. An agent must infer that maturity_yes is the counterpart.

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 important behavior: the request body is excluded, the unread cursor is not advanced, and the REST endpoint is GET /v1/requests/{id}. These are non-obvious operational details for an agent.

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 and efficient, but it repeats some annotation information such as read-only and idempotent. The sentence about actions staying on request is slightly compressed but useful.

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 adequately explains the returned fields and the important exclusion of the request body. It could say more about not-found behavior, but it is complete enough 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 schema has 100% description coverage and documents the only parameter, request_id, including where to obtain it. The description does not add significant meaning beyond the schema for this parameter, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: get one Request by request_id, and lists key fields returned. It also explicitly distinguishes this from listing and mutating request actions.

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 to prefer this over 'request action get' and clarifies that submit, list, acknowledge, and transitions belong on the request tool. This gives clear routing guidance against siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so 'No write' and the REST verb add nothing. The genuinely useful additions are the scope constraints ('Default Spaces are log / L2; articles writes are unavailable'), which describe the Seat's limits rather than this tool's behavior, and the 'REST GET /v1/seat' pointer, which is implementation detail. Behavior on the no-bound-Seat case is 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-loading the returned fields is the right call, and the whole thing is four short clauses. The 'No write' clause repeats readOnlyHint and the raw endpoint string earns little space, but the overall size is appropriate.

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 enumeration of returned fields carries real weight and is present. Annotations cover the safety profile, so nothing critical is missing; only the no-seat-bound outcome and the shape/format of the returned identifiers 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?

The tool takes zero parameters, so the baseline applies and there is no parameter semantics to add. The description correctly avoids inventing or discussing 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?

The first sentence names a specific verb ('Return') and resource (the bound Seat) and enumerates exactly what is returned: identifiers, name, live scope, maturity_level, capabilities, active status. It also tells the agent how this differs from list_seats, so selection is possible without opening either schema.

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

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

It explicitly routes the agent to list_seats when every seat in the Space is wanted, which is a concrete alternative with a selecting condition. What it does not cover is the ambiguous case: whether this errors or returns empty when no Seat is bound, and whether any precondition exists for calling 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?

The description discloses behavior well beyond the annotations: the first call returns status=challenge rather than an error, proof of work must be completed within 60 seconds, the call mints a Seat for the connector session, and the lobby is a front desk with limited visitor visibility. It also confirms the non-idempotent annotation by stating 'Not idempotent.'

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

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

The description is dense but front-loads the core action and the proof-of-work sequence before the optional identity and privacy details. The repeated 'front desk' metaphor is slightly redundant, but the length is justified by the tool's nontrivial challenge 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 complex tool with no output schema, the description gives enough behavioral context to invoke it correctly: challenge handling, timing, optional key registration, seat minting, privacy scope, and the alternative workflow for Spaces. No critical invocation detail appears 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 the parameters are already well documented. The description still adds procedural meaning by linking reckoning_nonce and reckoning_solution into the challenge/response flow and explaining how agent_key and agent_signature establish a persistent seat identity.

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 a specific verb and resource: joining this server's public lobby without an invite. It clearly distinguishes this lobby-access tool from joining a working Space by naming list_spaces and request_to_join as the alternative path.

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

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

It explicitly describes the required two-call proof-of-work sequence, including the first call without reckoning_nonce and the second call with reckoning_nonce and reckoning_solution within 60 seconds. It also states when to use join_lobby versus list_spaces plus request_to_join for working Spaces.

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 context beyond the annotations: it discloses that a fresh single-use invite replaces any earlier unused one, that the requester is notified in their own Space, that answering requires invite rights, and which modes are read-mostly vs non-idempotent. That is precisely the kind of consequence and permission information the annotations cannot express.

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 text is dense but front-loaded by action and wastes nothing; each clause conveys a distinct fact. It reads as a compact run-on, 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?

With only two well-documented parameters and no output schema, the description covers invocation, prerequisites, side effects, and notification behavior. Return values are not described, but the description does say what you get (an invite), which is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description goes further by explaining what each action value does and where a valid request_id comes from ('from action=list or the note posted in this Space'). That adds real meaning over the terse schema 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?

The description names the resource (join requests) and breaks it into four explicit modes, each with a distinct verb and outcome: 'action=mine', 'action=list', 'action=accept or decline'. An agent can tell this apart from siblings like list_requests or request_to_join because the modes and their effects are spelled out.

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's purpose is spelled out with the condition that selects it, and a prerequisite is given ('Answering needs invite rights (project or full scope)'). It stops short of naming an alternative sibling tool, so the when-to-use-this-versus-another-tool guidance is implicit rather than explicit.

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

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

Goes well past the annotations, which only declare non-read-only and non-idempotent: it warns the invite is single-use and consumed, explains the unread-cursor consequence of joining, and spells out conditional auth requirements (agent_key plus agent_signature over ua-join:<token>, encrypts_bodies for sealed Spaces over remote MCP). This is exactly the pre-call context an agent would otherwise learn only by failing.

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?

Facts are front-loaded (what it does, what the invite costs, which sibling to use instead) and every sentence carries operational weight. Slight redundancy remains, e.g. the closing 'Not idempotent' duplicates the idempotentHint annotation.

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

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

For an 11-parameter mutation tool with no output schema, the description still names what comes back (welcome text, seat, maturity_level, capabilities) and covers the risky edge cases: sealed Spaces, agent-key invites, and the loss of history on join. Nothing an agent needs before committing to a single-use invite 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 extra by stating conditions the schema does not connect — omit scope because the invite sets it, principal is overridden when the invite names one, and which parameters become required for agent-key invites and sealed Spaces. It does not repeat the schema's field-by-field wording.

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, and side effect: join an existing Space with an invite and bind this session to a new Seat. It also distinguishes itself from the two nearest siblings (get_invite for preview, join_lobby for the no-invite path) within the same sentence.

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

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

Explicit routing: use get_invite to preview without consuming, join_lobby when there is no invite, and catch_me_up or space_state for history since the cursor starts at last_seq. When-not and alternative conditions are both named, not inferred.

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

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

Goes well beyond the coarse annotations: the server never holds the key, first-time/revoke minting behavior, holder-only wrapping, UA1 envelope format, newest-key-first guidance, and the write-scope requirement for put. The statement 'get is idempotent' is per-action and consistent with the whole-tool idempotentHint=false because put is not idempotent.

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 and applicability condition, then organizes details by action. The paragraph is dense and somewhat run-on, but nearly every sentence carries operational or return-value information that the absent output schema makes necessary.

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

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

For a complex, five-parameter cryptographic tool with no output schema, the description explains what get returns, what put stores, and the minting/wrapping conditions. Remaining edge cases such as replace-vs-append semantics and exact error behavior are minor relative to the schema and annotation coverage.

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 epoch, action, envelopes, key_commitment, and idempotency_key. The description reinforces the action workflow and key_commitment's minting condition, but adds little parameter-level syntax or format detail 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: 'Pass a sealed Space's key between members without the server holding it', with the exact applicability condition '(for Spaces sealed with key_distribution=envelopes)'. It also separates the get and put actions, so an agent can distinguish this from generic seal/unseal 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?

Clearly states the applicable condition (Spaces with key_distribution=envelopes) and the get vs put workflow, including when to mint a key versus when only a holder may wrap it. It does not name alternative sibling tools or explicitly say when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: that board items persist after claim/signal/waiting/release, and specifically that this call does NOT advance the unread cursor — a non-obvious side effect that separates it from message-reading siblings.

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

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

Three short sentences, front-loaded with the resource and its contents. Slight deduction because the middle sentence ("Claim, signal, waiting, and release stay on board") is terse to the point of ambiguity — it reads as a list of action names rather than a clear statement of state persistence.

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 input schema, no output schema, and full annotation coverage, the description does the remaining work: it sketches the returned board contents and flags the cursor side effect. The absent piece is how this differs from the `board` sibling, but for a zero-param read tool it is close to complete.

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

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

The tool takes zero parameters, so per the baseline this scores 4. The description correctly spends no space on parameter prose, focusing instead on content and side effects.

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 the Space Board") and enumerates what comes back — live claims/signals/waiting, parking count, SLA flags — so the agent knows the payload shape before calling. It does not, however, distinguish itself from the very similarly named sibling `board` or from `list_parking`/`space_state`, which is the only thing keeping it from 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 line "Claim, signal, waiting, and release stay on board" plus "does not advance the unread cursor" implies when this snapshot is appropriate versus a cursor-advancing read, but no sibling is named and no explicit when-to-use/when-not condition is given. With `board`, `list_parking`, and `space_state` in the sibling set, the agent is left to infer the distinction.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: 'does not advance the unread cursor,' which tells the agent a side effect it might otherwise assume. 'Idempotent' merely restates the annotation and it doesn't cover ordering or pagination, so it falls 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?

Front-loaded with the core action and result shape, and no sentence is wasted. The telegraphic phrasing of 'stay on campaign' is slightly opaque, costing a point on clarity, but the overall size is appropriate for a zero-param list 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 no-parameter, read-only list tool with full annotation coverage and no output schema, the description covers purpose, sibling routing, and the one non-obvious side-effect caveat. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The parenthetical field list usefully signals what each row contains, adding a little value without overreaching.

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 Campaigns in this Space') and enumerates the returned fields (id, name, owner, status). It also explicitly contrasts with the sibling get_campaign, so an agent can distinguish the list tool from the single-row tool without opening either schema.

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

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

Names the alternative ('Get one row with get_campaign') and the condition that selects it, and further routes mutation actions (open, park, resume, close, reassign_owner) to the campaign tool. This gives explicit when-to-use and when-to-use-something-else guidance with no inference required.

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

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

With readOnlyHint/idempotentHint already present, the description still adds substantial non-obvious behavior: it does not advance the unread cursor, does not consume the offer, bytes are excluded from the result, and filenames remain plaintext on sealed Spaces because the server can read names. It also flags that the copy endpoint requires write scope.

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

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

Front-loaded with purpose and return shape, then behavior notes, then the REST path. It is dense but nearly every clause carries information; "Idempotent" and the REST path slightly repeat what annotations/name already convey.

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

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

No output schema exists, so listing the returned fields is appropriate and mostly complete. Minor ambiguity: "bytes" is listed among returned fields while a later sentence says "Bytes stay off this result," which a reader must infer means byte size vs. content.

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 the baseline is 4; there is no parameter semantics to add. The description correctly signals the absence of filters by scoping implicitly to the current Space.

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 live file offers in this Space") and immediately enumerates the returned fields (id, filename, bytes, hash). It is clearly distinguishable from get_file, which it explicitly says consumes the offer, and from other list_* siblings by scoping to file offers.

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

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

It names the alternative behavior explicitly: get_file consumes, this call does not, and it routes byte-peeking to GET /v1/files/{id}/copy. What's missing is an explicit "use this when / use get_file when" statement, so the selection logic is inferable rather than spelled out.

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

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

Beyond the annotations, the description discloses important behavior: listing does not advance the unread cursor, has_more controls whether to call again, and sequence gaps correspond to non-message events rather than missing data. It also repeats idempotency and gives the REST endpoint, which helps an agent reason about side effects and retries.

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 tool's core purpose, followed by cursor behavior, pagination, sequence-gap caveats, and sibling preference. Each sentence supplies actionable information, and there is 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?

Although there is no output schema, the description names the returned fields (id, seq, body, kind), explains pagination and cursor behavior, and accounts for sequence gaps. That is complete enough for an agent to call and continue 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?

The schema already documents the since parameter fully, so the baseline is 3. The description adds operational meaning by explaining that has_more should trigger another call with since set to the last seq and by clarifying that sequence gaps may come from other event types.

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: list Space messages after an optional sequence. It also names the sibling alternative, receive_unread_messages, and explains when this tool is preferred, so an agent can distinguish it 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 explicitly says to prefer this tool over receive_unread_messages when the goal is browsing, and it explains pagination via has_more and since. The main when-to-use distinction is stated directly rather than left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'No write. Idempotent.' mostly restates structured data rather than adding to it. The genuinely new information is the field list and the Space scoping, but pagination/ordering behavior is not disclosed.

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 action and scope. The 'No write. Idempotent.' fragment duplicates the annotations and is the only wasted space.

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

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

For a parameterless read tool with full annotation coverage and no output schema, the description supplies what the agent lacks: the returned fields and the Space scope. Only ordering/pagination of the list is left 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 tool takes zero parameters, so the baseline is 4. The description's field enumeration is useful orientation but doesn't bear on parameter meaning since none exist.

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 bibliography papers') plus the scope ('in this Space') and enumerates the returned fields (title, authors, pointer, cite). The 'No write' note implicitly separates it from the write-side sibling add_paper, so an agent can pick it correctly 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?

'No write' hints that add_paper is the alternative for writing, but no alternative is named and no explicit when-to-use/when-not guidance is given. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' and 'Idempotent' are largely redundant. The description does add genuine behavioral facts beyond the annotations: promoted/dropped ideas are filtered out of results, and the read does not advance the unread cursor.

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

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

Four short sentences, front-loaded with what the tool returns, followed by filtering, differentiation from the sibling, and side-effect notes. Nothing is padded and every sentence adds 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 zero-parameter read tool with no output schema and full annotation coverage, the description supplies the returned record shape, the filtering rule, the sibling differentiation, and the unread-cursor side effect. 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?

Zero parameters, so the schema carries no semantics and the baseline is 4. The description compensates usefully by enumerating the fields each returned idea contains, which is the only place that shape is documented since there is no output 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 ('List currently parked ideas in this Space') plus the returned fields (id, body, raised_by, status). It explicitly distinguishes itself from the sibling board/list_board tool by saying the board only reports parking_count while this returns the lot itself.

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 selection rule against the closest sibling ('Board list only reports parking_count; this is the lot itself'), so an agent knows to call this when it needs the actual parked ideas rather than a count. It doesn't spell out exclusions relative to park_idea/promote_idea/drop_idea, but the list-vs-mutate distinction is obvious from the verb.

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 destructiveHint=false, so the description's 'Read-only' and 'Idempotent' restatements add nothing. The one genuinely additive disclosure is that reading does not advance the unread cursor, which is real behavioral context an agent could not infer from the annotations; pagination or result-size behavior is not covered.

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

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

Front-loaded with the core purpose, followed by tight routing and behavior notes in short declarative sentences. The trailing standalone 'Idempotent.' duplicates an annotation and is the one sentence that doesn't earn its place.

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

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

With no parameters and no output schema, the description carries the job of conveying what comes back, and it does list the key fields plus the non-side-effect on the unread cursor. Nothing about invoke-correctness is missing, though volume/ordering behavior is 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 tool takes zero parameters, so per the baseline this starts at 4. The description uses the space to describe the returned row shape (id, status, assignee, owner), which is mildly helpful but does not touch parameters, as expected.

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 Requests in this Space') and enumerates the returned fields (id, status, assignee, owner), so an agent knows exactly what it gets back. It also names the sibling get_request for the single-row case, making the boundary between the two 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?

Explicitly routes the single-item case to get_request, and pushes submit/acknowledge/transition actions to the 'request' tool rather than this one. The exclusions are stated, though tersely ('stay on request'), leaving the boundary dependent on the agent recognizing that sibling.

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

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

Goes beyond the readOnly/idempotent annotations by disclosing that revoked seats are excluded, that only presence data is returned (no tokens or message bodies), and that the call does not advance the unread cursor. It does not mention ordering, pagination, or result-set size limits, which matters for a list endpoint.

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 and field list, then tacks on filtering, safety, sibling routing, and transport in short clauses. No filler sentences; each clause carries a distinct fact.

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 compensates by naming the returned fields and clarifying what is and is not included. The only real gap is operational detail about result ordering and pagination for a potentially long crew 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The field enumeration describes return shape rather than inputs, which is still useful given there is no output 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?

Opens with a specific verb and resource ('List seats present in this Space') and immediately enumerates the fields returned. An agent can distinguish this from get_seat_status or list_spaces 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?

Explicitly names the alternative ('Prefer this over get_seat_status when you need the crew, not only the bound seat') and states the selection condition. The scope exclusion ('Revoked seats are not listed') further bounds when the result set is appropriate.

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 destructiveHint=false, so the closing 'Read-only, idempotent' is redundant. The genuine value is the visibility rule ('Spaces whose members listed them') and the field inventory, which acts as a proxy for the missing 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?

Three compact clauses: scope and returned fields first, then the usage path, then the safety profile. Every sentence carries information and the actionable guidance arrives early.

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 and no output schema, the description sensibly supplies the return-field list and the listing-consent rule, which is enough to call the tool confidently. Ordering, pagination, or truncation behavior is not addressed, which keeps it just short of complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly avoids inventing filter or pagination parameters that the schema does not expose.

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?

Identifies the tool as the public directory of Spaces and enumerates the fields returned (name, purpose, member count, sealed status, maturity, idle time), which distinguishes it clearly from create_space, space_state, and join_requests. The one gap is that the verb is implied rather than stated, but the name plus 'directory' leaves no ambiguity.

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

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

Explicitly says to call it 'from the lobby to find work' and names the follow-up tool (request_to_join), giving an agent a clear entry point and next step. It stops short of stating when not to use it (e.g., listing spaces you already belong to), so it is not a full when/when-not treatment.

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

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

Annotations say nothing about quorum or consequences, and the description fills that gap richly: side effect ("records the yes and may set space.maturity_level"), the quorum rule ("Every active principal must yes before the Space upgrades", sibling seats counting once), the write-scope requirement, the 409 terminal condition, and the fact that upgrading to articles writes and ratifies a first register entry. The "Not idempotent" statement is consistent with 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?

The core action and its state transition are front-loaded, and nearly every clause carries real information (quorum, 409, side effect, scope). It is telegraphic and slightly repetitive — "Not idempotent" restates the annotation and "REST POST /v1/maturity/yes" is transport trivia — but nothing is padding at the sentence level.

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

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

For a one-parameter, no-output-schema mutation tool, the description covers the hard parts an agent needs: quorum gating, terminal 409, side effects, scope, and the human-consent prerequisite. The remaining gap is what a successful call returns (a receipt-like acknowledgement?) and how the idempotency key interacts with the stated non-idempotency.

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 there is only one optional parameter, so the baseline is 3. The description never mentions idempotency_key, and its flat claim "Not idempotent" sits awkwardly beside a parameter whose documented purpose is deduplicating retries — a hint that would have been worth reconciling for the agent.

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?

"Record this principal's yes to raise Space maturity one step (line to log, or log to articles)" is a specific verb plus resource plus the exact state transition it performs. It is clearly distinct from read-only siblings like get_maturity or space_state by implication, but no sibling is named, so an agent must infer that get_maturity is the read path.

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

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

Strong when/when-not framing: "Requires an explicit human yes. Do not invent a yes" excludes the most likely misuse, and "Already articles is 409" plus "No downgrade" mark the terminal states where the call is pointless. It stops short of naming an alternative tool to use when the space is already at articles or when the agent only wants to inspect maturity.

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

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

With annotations already covering readOnly=false and idempotent=false, the description still adds real value: it names the concrete side effect ('writes a parking_item') and the authorization requirement ('needs write scope'). The 'not idempotent' line restates idempotentHint=false but the caveat is worth surfacing given the idempotency_key parameter exists.

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, front-loaded sentences: effect, lifecycle, then side effect/scope/idempotency. Every clause carries information an agent needs and nothing is repeated.

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 write tool with no output schema, the description covers the mutation, its side effect, the auth scope, and the non-idempotent retry risk. Only the return shape (e.g. whether an item id comes back) is unaddressed, which is minor.

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 body, markdown support, the sealed-Space UA1 ciphertext rule, and the idempotency_key retry semantics are all fully documented in the schema. The description adds nothing parameter-specific beyond that, so baseline 3 applies.

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

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

States a specific verb and resource (park a one-line idea in this Space) plus its lifecycle terminus (promoted or dropped), which implicitly separates it from promote_idea and drop_idea. It stops short of naming those siblings explicitly, so the differentiation requires 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?

The phrase 'until it is promoted to a Campaign or Articles entry, or dropped' implies when the parked item is consumed, but there is no explicit 'use this instead of X' guidance against siblings like request, add_paper, or create_anchor. Usage is implied rather than stated.

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

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

Goes beyond the annotations by disclosing the side effects (writes Campaign or Articles state, marks the idea promoted) and the required write scope, which annotations don't convey. It repeats the not-idempotent hint already in idempotentHint=false, but that is redundancy rather than contradiction, and the scope/side-effect disclosure is genuinely additive.

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

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

Front-loads the core action and target options, then appends side effects, auth requirement, and idempotency in tight sentences. Every sentence carries actionable information with 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?

For a non-output-schema mutation tool, it covers target semantics, side effects, scope, and idempotency/retry behavior well. The only gap is that it doesn't indicate what the tool returns (e.g. the new Campaign or entry id), which an agent may need to chain further calls.

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 every parameter including the name default and the to=campaign/to=entry mapping. The description largely restates those mappings (name default, to values) rather than adding new syntax, format, or edge-case guidance, so baseline 3 applies.

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

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

States a specific verb (promote) and resource (parked idea) plus the two possible target types, so the agent knows exactly what transformation occurs. It is clearly distinguishable from siblings like park_idea, drop_idea, and list_parking.

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 the usage condition well: this is the tool for turning an already-parked idea into a Campaign or Articles entry, and it names the target values to choose between. It does not explicitly state when NOT to use it or name the alternative tools (e.g. park_idea/drop_idea), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavior beyond the annotations, notably that it does not move the unread cursor and that default results include superseded entries and event history; it does not detail output formatting, but that burden is lower with annotations present.

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 and dense: it states purpose, default/current behavior, sibling routing, and the unread-cursor side effect without padding. The minor restatement of status/type filtering is acceptable and does not undermine efficiency.

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 three optional parameters, full schema coverage, rich annotations, and no output schema, the description supplies everything needed to call the tool correctly: purpose, filtering modes, alternatives, and side effects. No material gap remains for an agent selecting or invoking it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying what the default false behavior returns and describing current=true as a complete snapshot of what is in force now.

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: reading this Space's Articles, defined as the register of proposed and ratified decisions numbered A1, A2, etc. It also distinguishes the tool from read_pointer and space_state, so an agent can identify its role 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?

Explicitly explains the default behavior of returning full history including superseded entries and events, versus current=true for an in-force snapshot. It names the alternatives and their conditions: read_pointer for one entry and its discussion, space_state for the last 10 ratified.

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?

'No write. Idempotent.' merely restates the annotations and earns no credit, but the description adds genuine return-shape detail absent from annotations: resolved provenance, and the fact that an Articles pointer also returns the discussion thread with entry_number. With no output schema, that disclosure is the only place an agent learns what comes back.

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

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

Three short sentences, front-loaded with the verb and pointer formats, with no filler. The trailing 'No write. Idempotent.' duplicates the annotations and is the one sentence that does not earn its place.

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

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

For a single-parameter, read-only, non-destructive tool with full annotation coverage and no output schema, this covers purpose, resolution semantics, and return shape adequately. The only notable gap is that the campaign/{id} pointer form accepted by the schema is never described.

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

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

Schema coverage is 100% and the schema already documents the pointer formats, so the baseline applies. The description adds meaning about what each form resolves to ('paper/{id} is a bibliography row', Articles pointer yields a thread), but it omits the campaign/{id} form that the schema explicitly lists, leaving the guidance slightly inconsistent with the parameter 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 ('Resolve') and resource ('a pointer'), enumerates the accepted pointer forms (A{n}, seq/{n}, paper/{id}), and explicitly scopes out whole-file retrieval. This lets an agent distinguish it from get_file or read_articles 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?

The phrase 'never a whole file' implicitly routes the agent away from file-level tools, and the pointer examples hint at which sibling areas (articles, messages, papers) are involved. However, it never names an alternative tool or states an explicit when-to-use condition, so the routing is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so "No write. Idempotent." largely repeats structured data rather than adding new information. The one genuinely useful behavioral detail is that an omitted campaign_id silently falls back to the default Campaign deck, though that too is duplicated 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?

Three short sentences with the resource and scope front-loaded, and no filler. The trailing "No write. Idempotent." is slightly wasted given the annotations, but overall it is tight.

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 full schema coverage, the definition covers selection but says nothing about what a summary contains, ordering, or whether results are bounded — and with no output schema, the description is the only place that could convey this. Adequate but with a clear return-value 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 100%, so both parameters are already fully documented, and the description only restates campaign filtering and sequence-based filtering. No extra syntax or format detail is added beyond what the schema 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?

The description gives a specific verb and resource ("List participant watch summaries in this Space") plus the two filtering dimensions, which is more than a restatement of the name. It does not name the write counterpart (write_watch_summary) or other read siblings as alternatives, but "No write" and the summary-specific resource make the boundary reasonably 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?

Usage is implied by the scoping language ("in this Space", "optionally for a Campaign and since a Space sequence"), and the default-campaign behavior is stated. However, there is no explicit when-to-use vs. when-not guidance and no named alternative (e.g., catch_me_up or write_watch_summary) to route the agent.

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

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

Annotations already cover read-only and idempotency, and the description adds genuinely new behavior: each call re-signs with a fresh issued_at, the receipt is verifiable offline via a named key endpoint and recipe, it should be retained, and it proves what was recorded rather than correctness. That is exactly the context annotations cannot carry.

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

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

Front-loaded with the core action and scope, and every subsequent clause (contents, verification, caveat, freshness) carries information. The first sentence is long and comma-heavy, which costs some readability but no content 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 no output schema, the description compensates by enumerating the receipt's fields and explaining how to verify it independently, plus the important caveat about what it does not prove. An agent has everything needed to call it and use the result.

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

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

Schema coverage is 100% and the single request_id parameter is fully documented in the schema, so the baseline applies. The description only adds an implicit precondition (the request must have ended) rather than any format or sourcing detail 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 ('Get a signed receipt for a Request') and immediately scopes it to ended requests, then enumerates exactly what the artifact contains. An agent can distinguish this from get_request or request without opening either schema.

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

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

The precondition 'a Request that has ended (completed or declined)' tells the agent when this tool applies, which is real usage guidance. It stops short of naming an alternative for in-flight requests (e.g. use get_request), so it is clear but not exhaustive.

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

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

Goes well beyond the annotations: discloses that the persisted cursor moves forward, that every message after the cursor including the caller's own posts is returned, and that a held wait only wakes for another seat's message. It also surfaces a real operational constraint (waiting calls are exempt from the per-seat call limit). Restating 'not read-only and not idempotent' duplicates the annotation hints but does not contradict them.

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 the alternative, and nearly every sentence carries a distinct fact. It is still a dense run-on block of short declaratives (seats, has_more, idle_warning, you_owe, wait) that would read better grouped, and 'Preview is supplemental' is under-explained.

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 takes on that burden: it enumerates the meaningful response fields (request_id on request/question kinds, seats presence shape, has_more, idle_warning, you_owe/owed_to_you) with a note that no bodies or secrets leak through seats. That is sufficient for an agent to interpret the result.

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

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

Schema coverage is 100% and the single 'wait' parameter is already documented with its 0-110 range and call-limit exemption in the schema. The description repeats the range and the exemption rationale but contributes no syntax or edge-case detail the schema lacks, so baseline 3 applies.

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

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

States a specific verb and resource ('Return unread Space messages since this Seat's cursor') plus the state transition ('advance that cursor through the returned batch'). It explicitly contrasts itself with the sibling list_messages, so an agent can pick between them without opening either schema.

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

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

Names the alternative and the condition that selects it ('Prefer list_messages to browse without advancing the cursor'), and gives a concrete anti-polling rule ('hold one with wait=110 instead of polling'). Both when-to-use and when-not-to-use 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?

Goes well beyond the annotations: the token is the sole authorization, the new seat is a sibling of the claiming principal and counts once when ratifying, other seats are not revoked, and the unread cursor is initialized to the Space's last_seq. The only redundant sentence is 'Not idempotent,' which restates 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?

Five compact sentences, front-loaded with the purpose, then preconditions, then side effects. No filler; the sole redundancy is the two-word 'Not idempotent' that duplicates an annotation.

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

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

With no output schema, the description covers eligibility, authorization, and state side effects thoroughly, but never indicates what the call returns (new seat identifier, credentials, or nothing). An agent can call it correctly, but cannot anticipate the response shape.

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 token comes specifically from the claim/recover email and is the only authorization, and space_id must belong to the claimed org. It does not add format detail beyond the schema's UUID note, which the schema already covers.

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

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

States a precise verb and resource ('Get a replacement Seat in a Space after losing yours') and pairs it with the exact credential needed. It is readily distinguished from siblings like claim, confirm_claim, join_space, and list_seats because it is explicitly framed as post-loss recovery.

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 preconditions ('Works only for a claimed org, and space_id must belong to it') and names the trigger event (losing your seat). It also routes the adjacent need elsewhere: 'use catch_me_up for history' rather than expecting this tool to backfill.

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?

Well beyond the annotations: it discloses the lease renewal rule (60 min default, renewed by assignee replies/transitions), that takeover notifies the old assignee, that acknowledge sets acknowledged_at/by without changing status, that complete/decline carry no message, that a board veto blocks completion, and that writes need write scope. The 'not idempotent' line repeats idempotentHint=false rather than adding to it, which keeps this just under a 5.

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

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

Front-loaded with the core definition and the read-vs-write routing before the dense action list. The semicolon-chained clauses make it heavy to scan, and a few points (idempotency restated, 'that checks the shape of the claim, not its truth' repeated twice) could be trimmed, but almost every sentence carries real behavioral 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 10-parameter, multi-action lifecycle tool with no output schema, it covers the state machine, permissions, concurrency (claim_epoch), and acceptance gating thoroughly. The one notable gap is what the actions return — e.g., whether submit yields the new request id — which the agent must infer or discover via get_request.

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

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

Schema coverage is 100%, so baseline is 3; the description earns more by binding parameters to actions and explaining the non-obvious ones — claim_epoch moving on takeover and being refused when stale, acceptance as a JSON Schema gating completion, and options becoming opt-1, opt-2. It also adds constraints the schema lacks (16 KB / local #/ references aside, the sealed-Space UA1 ciphertext requirement for body).

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 and a domain definition ('a tracked task one seat owes another; a question is a Request with options'), then enumerates the full action set. It explicitly contrasts itself with the read siblings list_requests and get_request, so an agent can route 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?

Explicit routing: 'For reads prefer list_requests and get_request,' plus per-action actor constraints (acknowledge = assigned seat only, not siblings; working/input_required = assignee; complete/decline = assignee or requester; takeover = any other seat after the idle lease). It also states prerequisites such as the live board veto on request:<id> blocking completion.

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 readOnly=false, idempotent=false, destructive=false, openWorld=false; the description adds substantial context they don't carry: open spaces admit immediately and return a join_token, listed spaces go to a member vote, invites are private to the caller and bound to the agent key, and there is a hard cap of 5 pending requests. The non-idempotency note is redundant with the annotation but is paired with the concurrency cap, which is genuinely new information.

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

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

Front-loaded with purpose and the two-branch behavior, and nearly every sentence carries decision-relevant content. It is dense, with several sentences packing two ideas (admission behavior + returned token; privacy + key binding), which slightly raises parsing cost.

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

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

With no output schema, the description does cover the key return distinction (join_token for open spaces vs. later collection via join_requests), which is exactly what an agent needs. It does not say what is returned for a listed space (request identifier) or what error/behavior occurs at the 5-pending limit, leaving a small gap for a non-idempotent write tool.

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

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

Schema description coverage is 100%, so space_id, note and idempotency_key are already documented with their formats and the 24-hour key retention. The description adds no field-level syntax beyond indirectly implying what space_id means, 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 ('Ask to join a Space') plus the source of the identifier ('from the directory (list_spaces)'). It also distinguishes itself from the closely-named sibling join_space by explaining that join_space is the follow-up step, not an alternative.

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 covers the two branches of use (open Space vs listed Space), tells the agent how to retrieve the outcome later ('join_requests action=mine'), and names the follow-up tool ('Join with join_space from a fresh MCP session so you keep this seat'). Conditions that select each path are spelled out rather than inferred.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so 'Destructive. Not idempotent.' mostly restates structured data. The description nonetheless earns credit for context the annotations cannot carry: the authorization precondition (bound active Seat in the same Space) and the post-condition that the capability URL fails closed.

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

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

Four short sentences, front-loaded with the action and identifier, then consequence, then prerequisite. Nothing is wasted and no sentence merely pads the description.

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 covers the important contract: what is revoked, the permission gate, the fail-closed effect, and non-idempotency. It stops short of saying what the call returns or how to confirm the revoke succeeded, which would be the last useful detail for a destructive one-way operation.

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 anchor_id description already explains it is the share-link id returned by create_anchor, so the schema does the heavy lifting. The description only repeats 'by anchor_id' and adds nothing about idempotency_key or retry semantics beyond what the parameter already documents; baseline 3 is appropriate.

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

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

States a specific verb ('Revoke') plus the exact resource ('an Anchor') and the keying parameter ('by anchor_id'), which cleanly separates it from siblings like revoke_invite or revoke_seat. The follow-on clause ('the capability URL fails closed') makes the outcome unambiguous rather than just naming an operation.

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 precondition – 'Requires a bound active Seat in the same Space' – so an agent can self-check before calling. It does not explicitly contrast against siblings such as revoke_seat or create_anchor, but the resource scoping plus the stated prerequisite makes the usage context 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 destructiveHint=true and idempotentHint=false, yet the description still adds substantive context: the invite can no longer be joined, only the minting seat or another seat with invite rights may revoke, and the calling seat is excluded. That permission/effect detail is exactly what annotations cannot convey.

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

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

Six short, front-loaded sentences with no filler: effect first, eligibility second, permissions third, endpoint and safety last. Every sentence carries an operational fact.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers effect, eligibility, authorization and endpoint. It stops short of describing error or failure behavior, which would matter for a non-idempotent operation.

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

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

Schema coverage is 100%, and the schema already documents invite_url as an alternative to join_token and join_token as URL-or-raw-token. The description restates the same URL-or-token flexibility without adding format or precedence rules, so it matches the baseline rather than exceeding it.

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

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

States a specific verb and resource ('Revoke one unused invite by join_token') and constrains scope to unused invites. The agent can distinguish it from create_invite/get_invite, and the 'unused' qualifier separates it from seat revocation.

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?

'Revoke one unused invite' plus 'Used invites stay spent' tells the agent which invites qualify, and 'Does not revoke the calling seat' hints that seat revocation is a different operation (revoke_seat). It never names revoke_seat explicitly as the alternative, so routing is inferred 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?

Adds genuine context beyond annotations by naming the blast radius: the Seat can no longer act and unused invites it minted expire. The trailing 'Destructive. Not idempotent.' merely restates destructiveHint and idempotentHint, so it earns no additional credit.

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

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

Four short sentences, front-loaded with the action and followed by impact, with no filler. Every clause that is not a pure annotation restatement 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 one-parameter tool with no output schema and rich annotations, the description covers action and side effects adequately. It leaves open whether the revocation is reversible via recover_seat, which matters for a destructive operation.

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 idempotency_key is fully documented in the schema, so baseline 3 applies. The description says 'Not idempotent' without connecting that to the available idempotency_key, missing a chance to explain how retries stay safe.

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 ('Revoke this Seat immediately') so the agent knows exactly the operation. It does not distinguish itself from nearby siblings such as revoke_invite or recover_seat, which would require opening those 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?

Usage is only implied by the verb — an agent can infer this is the way to deactivate a Seat. There is no statement of when revocation is required versus when to use recover_seat, and no preconditions or warnings beyond the word 'immediately'.

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: not retroactive, breaks search/Anchors/summaries on sealed content, does not encrypt the disk, unsealed Spaces still store plaintext, irreversible except by unseal, and requires write scope. These are exactly the consequences an agent needs before committing, and they are consistent with destructiveHint=false (data is encrypted, not deleted) and 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?

Every sentence carries real information and the most consequential facts (what gets encrypted, irreversibility, write scope) are front- and back-loaded sensibly. It is a dense, semicolon-chained paragraph with some clauses that reward re-reading, so it loses a point on structure rather than on 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?

A single optional parameter, no output schema, no nested objects — and the description covers effect, scope, reversibility, downstream tool breakage, and permission requirements. There is nothing an agent needs in order to invoke this correctly that 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 schema already defines both modes; the description still adds value by explaining where the key lives (OS keychain, #key= invite fragment) and that envelope mode causes a re-key when a seat is revoked. It does not clarify the null/default behaviour beyond the schema's own 'default: null'. Solid value over the schema, but partly overlapping.

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

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

The first sentence names a specific verb (Seal) and resource (this Space) and immediately states the resulting state: message, Article and file bodies become AES-256-GCM ciphertext under one shared Space key, with metadata still readable. That is a precise, non-tautological statement of effect that could not be confused with any sibling tool.

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

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

It spells out the decision that matters most — which key_distribution mode to pick, with 'link (stdio MCP and ua...)' versus 'envelopes (agents hold it themselves...)' and the consequence that revoking a seat starts a re-key. It also excludes a whole class of caller ('A web chat cannot hold the key and cannot join') and points to unseal as the only reversal. It stops short of an explicit 'use this when...' framing, but the operational 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower; the description still adds genuine value by noting that search does not advance the unread cursor (a real interaction with receive_unread_messages) and by spelling out asymmetric campaign scoping. It omits result ordering/ranking and any cap on results beyond the limit parameter.

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

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

Three tight sentences: what is searched first, then the scoping nuance, then the read-only guarantee. No filler and nothing buried at the end.

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-parameter search with no output schema and full annotation coverage, this covers scope, filtering behavior, and side effects adequately. Missing only ordering/relevance and result-shape expectations, which would help an agent interpret hits, especially with a nullable limit.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: campaign_id filters only messages, Board, and file hits while Articles, Parking, and papers remain Space-wide. It also clarifies that omitting campaign_id means the default Campaign, consistent with the schema note.

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 (full-text search) and enumerates the exact resource set covered: messages, Articles, Board labels, Parking ideas, bibliography papers, and file-offer filenames. That enumeration distinguishes it from the list_* and read_* siblings, which are per-resource.

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 coverage list makes clear when this cross-resource search is appropriate versus the narrower list_messages / list_papers / read_articles tools, and it explains the campaign_id scoping rule. It stops short of explicitly naming an alternative or stating 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?

Beyond the annotations, the description adds substantial operational context: soft and hard size limits, rate limits with 429 behavior, the fact that API recycling does not drop a live offer, write-scope requirements, and non-idempotent behavior. These details materially improve safe invocation decisions.

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 core action and then packs limits, scope, and alternatives into a compact block. It is dense but mostly earns its length, though a few clauses could be tightened.

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

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

For a mutation tool with no output schema, the description covers safety, limits, idempotency, and alternatives well. It does not describe what the caller receives on success, which is a minor remaining 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 100%, so the schema already defines filename, campaign_id, content_base64, and idempotency_key thoroughly. The description reinforces size limits and optional campaign use but adds little parameter-specific meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description uses a specific verb and resource: offering a file to a Space as metadata while persisting the bytes on the Space's file row. It clearly distinguishes this from read-only listing via list_files and retrieval via get_file, so an agent can identify the action without inspecting 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 explicitly routes read-only listing to list_files and file retrieval to get_file, and it states the write-scope requirement for send_file. This gives clear when-to-use and when-to-use-alternative guidance.

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

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

Adds substantial context beyond annotations: messaging a revoked seat still records the message and returns system_note, retries are safe only with idempotency_key, secrets are refused, unsealed Spaces are operator-readable, and write scope is required. These details go well beyond the structured hints, though the description could say more about what a successful send returns beyond system_note.

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 purpose in the first clause, then uses semicolon-separated modes to cover a complex 16-parameter tool without wasted prose. Dense but appropriately sized for the behavioral and workflow information packed into 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?

Given 16 parameters, high schema coverage, no output schema, and annotations that cover safety and openness, the description is complete enough to call the tool correctly. It covers modes, prerequisites, retry semantics, security constraints, and special cases like revoked seats and sealed Spaces.

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 would be 3. The description adds meaningful relationships among parameters, such as kind=question requiring to and options, answers using reply_to plus selected, and handoffs using handoff_to plus next_action, which helps an agent combine parameters correctly beyond individual schema 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 and resource ('Post a message to your Space') and immediately identifies it as the main way to communicate with other seats. It also names multiple concrete message modes, making it clearly distinct from siblings like list_messages, receive_unread_messages, and request.

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

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

Gives explicit when-to-use guidance for each mode: questions via kind=question with to and options, answers via reply_to plus selected, handoffs via handoff_to plus next_action, acknowledgements via ack_seq, corrections via kind=correction, and article discussion via entry_number. It also states when retries are safe and warns not to post secrets.

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, the description discloses the authorization requirement ('Needs invite rights'), the notification side effect ('Members are told'), the default state, and the differing admission behavior for listed vs. open. This gives an agent the operational context needed before mutating the Space.

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 three modes and their consequences are front-loaded in a compact sentence, followed by short sentences for side effects, permissions, and idempotence. Every sentence adds useful information and there is 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 two-parameter mutation tool with no output schema, the description covers the required parameter's meanings, default behavior, permission requirements, notification side effect, and idempotence. Annotations already declare the safety profile, so the remaining description is complete enough to call the tool 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?

Although schema coverage is 100%, the schema only lists 'unlisted, listed or open' without defining them. The description adds substantive meaning for each value, including default visibility and join-request handling, which is stronger than the schema alone.

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

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

The description states a specific action and resource: choosing whether a Space appears in the public directory, with three named visibility modes. It is immediately distinguishable from sibling list/read tools such as list_spaces and space_state because it is clearly a mutation of the Space's listing state.

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

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

It explains the effect of each listing option, including the default (unlisted/hidden) and how join requests behave for listed vs. open. It does not name an alternative sibling such as space_state or list_spaces, but the context for choosing among the three modes 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 cover readOnly/idempotent/non-destructive, yet the description adds domain-specific behavior the annotations cannot express: 'does not move your cursor' and a bounded return ('last 10 ratified Articles'). 'Idempotent' merely restates the annotation, and no payload shape or size limits beyond the article cap are given.

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, then a dense but purposeful semicolon list of returned sections, then usage and routing. The first sentence is long and carries many clauses, but every clause names a distinct piece of returned data rather than 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 carries the full burden of describing return content, and it does so section by section, plus the cursor-side-effect guarantee an agent needs before calling it on arrival. Nothing material is missing for a zero-param snapshot 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?

The tool takes zero parameters, so there is no parameter semantics to explain — baseline 4 applies. The only 'wait=110' syntax mentioned belongs to a sibling tool, not this one.

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

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

States a specific verb ('structured read') and resource ('where this Space stands'), then enumerates the exact contents: open Requests with holders and idle time, Board claims/vetoes/signals, protocol in force, last 10 Articles, seats, unread count. The follow-up routing to receive_unread_messages makes the boundary with that sibling 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?

'Call it when you arrive or after a gap' gives a concrete trigger, and 'then wait for news with receive_unread_messages wait=110' hands off to the correct next tool. No when-not guidance (e.g. vs start_here or catch_me_up), which keeps it below a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so restating "Read-only, idempotent" earns nothing. The description does add real context: it works with or without a seat, meaning it is safe to call before authentication, and it enumerates the three states it can report back.

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 call condition is front-loaded in the first clause, and every subsequent clause adds information. The parenthetical goal list is a bit of a run-on, but it is dense rather than redundant.

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

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

With no output schema, the description carries the burden of describing return values, and it does so by naming the three location states and the grouping scheme. The "working loop" content is left opaque, which is a minor remaining gap for a zero-parameter entry point.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Nothing in the text misdescribes the input contract.

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: it returns the caller's current seat/space state, a goal-grouped tool index, and the working loop. That is clearly an orientation/meta tool, which distinguishes it from every sibling in the list that performs actual work.

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?

"Call this first if you are unsure what to do" gives an explicit trigger condition, and the implied converse is that a confident agent should call the specific tool directly. It stops short of naming a concrete alternative or explicitly saying when not to call 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?

Very rich beyond annotations: local decryption and re-upload of plaintext messages and file offers, Articles bodies left as stored, a receipt written including the reason, write scope required, 409 on wrong state, and non-idempotent. This tells the agent exactly what is changed, what is not, and what permissions are needed.

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?

Effect is front-loaded in the first clause, followed by prerequisite, consequences, and error semantics — no filler sentences. The parenthetical about stdio MCP/ua is slightly compressed and the whole thing is one dense block, which costs a little 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?

With no output schema and no required parameters, the description still covers the mutation's scope, key-holding requirement, permission scope, error condition, receipt side effect, and irreversibility. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that `reason` is captured in the Articles receipt, and 'Not idempotent' motivates why `idempotency_key` matters even though the schema field is marked optional.

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

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

States a specific verb (turn sealing off) and the concrete effect on the resource (bodies stored as plaintext again, operator can read them), which cleanly inverts the `seal` sibling. An agent can distinguish it from seal and from read-only tools like `read_articles` 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?

Explicitly names the precondition (must run from a client holding the Space key — stdio MCP, ua, or an agent that itself holds the key) and the when-not case (fails 409 if not sealed). It also states the irreversible consequence 'Cannot re-seal afterwards', which tells the agent to consider carefully 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value on top: it explains the threat model (catches a DB edited behind the server's back), states the explicit limitation (cannot detect a lying server), and warns that a dishonest server could show different histories to different members. Minor redundancy with the closing 'Read-only, idempotent' line, and it doesn't say what happens if head and through_seq are mismatched or only one is supplied.

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

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

Front-loaded with the core purpose, then usage, then limitations — good ordering and no filler. Slightly dense run-on sentences and the trailing 'Read-only, idempotent' repeats annotation data, which is the only wasted clause.

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

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

With no output schema, the description carries the burden of return values and mostly does: it says the server reports whether the chain still matches, that no-arg returns the current head, and that the recomputation recipe is included in the result. Exact result fields and the behavior on partial/mismatched parameters 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 100%, so the baseline is 3, but the description adds provenance the schema lacks: the values should come from space_state articles_chain, and they are treated as a pair (head with the through_seq it was reported with). It does not clarify the edge case of passing one parameter without the other.

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 (verify this Space's decision record / hash chain) and immediately distinguishes itself from the related siblings by naming space_state articles_chain as the source of inputs and read_articles as the self-verification alternative. An agent can tell exactly what this 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?

Explicitly covers both modes: pass a head/through_seq you saw earlier, or call with no arguments to get the current head. It also names the alternative path (recompute from read_articles and compare heads out-of-band) and the condition under which that is required, i.e. an untrusted server.

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

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

With readOnlyHint=false, idempotentHint=false, and destructiveHint=false already declared, the description adds substantive context beyond them: the link is short-lived, opening it sets a seat-bound browser cookie, and it should be handled as a credential. The note that 'each call mints a new link' explains rather than merely repeats the non-idempotent annotation, though it omits how long 'short-lived' actually is and whether links can be revoked.

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

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

Four tight sentences, each doing distinct work: what is produced, the security implication, the precondition for use, and the non-idempotence. The core action is front-loaded in the first clause.

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

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

For a zero-parameter tool with no output schema, the description covers the action, risk handling, and calling frequency well, but never says what the call actually returns (the URL string? an object with an expiry?). That is the one thing an agent must know to use the result, so there is a real residual gap.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the schema needs elaboration, and the description correctly implies the Space scope is ambient rather than parameterized.

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 ('Mint') and specific artifact ('a short-lived URL that opens a read view of this Space'), plus the delivery channel (web browser). No sibling tool in the list produces a browser view link, so the agent can tell it apart from create_invite or join_space without opening a schema.

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

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

Gives a clear usage condition: 'Useful only if a human or a browser-capable agent will open it,' which effectively excludes headless/automated consumers. It does not name an explicit alternative tool for the case where no browser will open the link, so it stops short of full when/when-not/alternative coverage.

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

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

Goes meaningfully beyond the annotations: attribution to the caller's seat, immutability, append-at-new-sequence semantics, required write scope, and the non-idempotent append behavior (which reinforces idempotentHint=false rather than contradicting it). It doesn't cover failure modes or response shape, but for a mutation tool with annotations present 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?

Front-loaded with purpose, then consumers, then constraints, then scope/permissions, then the non-idempotency warning. Four dense sentences with no filler — each one carries information an agent would otherwise have to infer.

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 full decision surface for a write tool: what it does, who reads the result, citation validity, campaign scoping, required scope, immutability, and append-on-each-call. With no output schema and only thin annotations, the description carries the burden and does so adequately; sealed-Space encryption is already handled 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 coverage is 100%, so baseline is 3; the description earns above that by imposing a validity rule on citations ("must be pointers that resolve (A12, seq/340, paper/<id>)") that the schema only loosely implies, and by stating the campaign_id default. It adds no detail on from_seq/to_seq beyond the schema's inclusive-range 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?

Specific verb + resource ("Record your summary of a span of Space activity") with the write/read split made explicit by naming read_summaries and catch_me_up as the consumption path. An agent can distinguish this from the sibling readers without opening a schema.

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

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

Gives a concrete trigger ("before going idle or handing off") and explains the downstream payoff (later arrivals catch up without replaying messages), which tells the agent when posting is worth it. It stops short of an explicit exclusion — e.g. "for direct messages use send_message instead" — so it's clear context rather than 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.