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

Annotations already cover the read-only/idempotent safety profile, and the description adds genuinely non-obvious behavior: message expiration and the resulting ambiguity of an empty result. That is exactly the kind of context structured fields 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?

Four short sentences, each carrying distinct information (purpose, polling use, sibling routing, cursor pattern, expiration caveat) with the core purpose front-loaded and no filler.

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

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

With no output schema, the description could say slightly more about what a returned message looks like, and the 'roster' parameter is untouched. Otherwise it covers purpose, polling semantics, the mutation alternative, and the empty-result caveat adequately for a 3-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for 'since' by explaining the poll pattern (pass the previous cursor to get only new messages). It does not clarify 'limit' or 'roster' beyond the schema, so it stops short of a 5.

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

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

Starts with a specific verb+resource ('Read the shared board') and immediately adds the scope qualifier ('optionally only what arrived since your last read'). It also names the write counterpart ('To post, use say'), so the agent can distinguish it from siblings like say 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 states the use case ('poll for messages or hand-offs addressed to you'), gives the alternative for the opposite intent ('To post, use say'), and instructs exactly when/how to use the cursor ('Pass the previous cursor as since so a poll returns only new messages'). Nothing is left to inference.

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

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

Annotations cover read-only, non-destructive, closed-world, and idempotent behavior. The description adds valuable context not in annotations: the digest reflects recent activity, so two calls minutes apart may differ. This addresses data freshness, which annotations cannot convey. The only minor gap is that it doesn't detail return format or rate limits, but for a read-only tool this is largely sufficient.

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 four sentences with zero waste, front-loading the core purpose and timing before alternatives and behavioral nuance. Every sentence contributes directly to correct selection and invocation.

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

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

For a read-only tool with no output schema, the description is complete: it states the purpose, when to call it, alternatives, and a behavioral trait not captured by annotations. The parameter is schema-documented, and the annotations cover safety. Nothing essential for an agent 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?

Schema description coverage is 100% for the single 'limit' parameter, which is fully documented in the schema. The description does not add meaning beyond what the schema provides, so 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 uses a specific verb ('Pull a short digest') and resource ('recent memory from the human's active threads and open tasks'), and explicitly distinguishes itself from siblings like recall and manage. An agent can immediately understand what this tool does and when it differs from alternatives.

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 states when to call ('once at session start') and when not to ('For answering a specific question, use recall instead', 'For entries still awaiting approval, use manage with action list_pending'). The alternatives are named with the conditions that select them, leaving nothing 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?

The annotations already establish non-read-only, non-destructive, closed-world behavior. The description adds important context beyond them: forget is a reversible soft-delete, discard_pending permanently drops an unconfirmed entry, and the reversibility exception is disclosed rather than hidden.

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 most sentences earn their place by mapping actions and alternatives. The final sentence repeats the discard_pending exception already stated, though it usefully explains the annotation choice.

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

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

For a five-action lifecycle tool with no output schema, the description covers every action, the id requirement, reversibility, permanence, and the relevant sibling alternative. An agent has enough information to choose and invoke the correct action.

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 id and action parameters are already fully documented. The description reinforces that entries are addressed by id or queue state, but it does not add syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: inspect or change the lifecycle of a stored memory, addressed by id or queue state. It also enumerates the concrete lifecycle actions and distinguishes the tool from the sibling recall tool.

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

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

It gives explicit routing guidance: list_pending for items awaiting approval, get_by_id for reading one entry, forget/restore for reversible soft-delete, discard_pending for permanent removal, and recall for topic-based search of confirmed memory. The alternatives and selection conditions are clear.

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

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

Annotations only say non-read-only, non-destructive, closed-world; the description goes much further by explaining the queue semantics, that nothing confirmed is changed, that the write cannot be self-confirmed, and that a success response means 'queued, not stored'. It also discloses the idempotency mechanism for retries — genuinely useful context an agent could otherwise get wrong.

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

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

Front-loaded with the action and the pending-queue consequence, then usage, then failure-mode caveat, then the parameter note. Every sentence carries distinct information, though the closing client_id sentence duplicates the schema description and is the one small piece of redundancy.

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

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

With no output schema, the description carries the burden of explaining what a successful call means and does so explicitly ('success response means queued, not stored'). Combined with triggers, exclusions, and retry semantics, 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 description coverage is 100%, so all five parameters (including content authorship guidance, vault restrictions, and client_id idempotency) are already documented in the schema. The description's only parameter reference — 'Supply client_id to make retries idempotent' — restates the schema rather than adding to it, 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 ('Submit a memory for the human to approve') plus the crucial qualifier that it lands in a pending queue rather than confirmed memory. That distinguishes it cleanly from siblings like recall (read), say (immediate output), and manage (administration).

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 positive triggers ('when the human says to remember something, or when a decision is reached that will still matter later') and explicit exclusions ('Do not use it as a scratchpad for transient reasoning or for data you merely fetched'). The when/when-not pair leaves little 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?

Rather than restating readOnlyHint, it deliberately adds what annotations cannot: results come only from the confirmed store, unreadable private vaults are silently omitted, and an empty list means no match rather than no memory. The empty-result-vs-empty-store distinction is exactly the kind of behavioral fact that prevents misdiagnosis.

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?

Sentences are front-loaded: purpose first, then the two exclusions, then behavioral caveats. The self-referential clause about what the annotations already declare is slightly meta but functions as a signpost for why the following sentences exist.

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 results, and it does so at a high level (closest entries, confirmed store only, empty list semantics), while compact-vs-full shape is in the schema. Minor gap: how ties or scores are surfaced to the caller is left implicit.

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

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

Schema coverage is 100%, so query, limit, vaults and compact are already fully documented, including the keyword/bigram ranking behavior. The description adds only an indirect hint about vault permission behavior, which the schema itself already states, 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 definition pairs a specific verb (search) with a specific resource (the human's confirmed memory) and states what it returns (the closest stored entries). It explicitly distinguishes itself from siblings get_context and manage, 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?

It names two concrete exclusions with the alternative to use instead: at session start with no query, use get_context; to review pending entries, use manage with action list_pending. Both when-to-use and when-not-to-use are covered explicitly.

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

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

Annotations already declare readOnly=false and idempotent=false, so the write semantics are covered. The description adds non-structured context: the board is human-readable so posting noise has real cost, and identity comes from the credential so impersonation is impossible. It doesn't note that repeated calls create duplicate cards, which is notable given idempotentHint=false.

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

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

Purpose is front-loaded in the first sentence, then usage triggers, the exclusion, the sibling alternative, and the identity constraint in that order. Four sentences, none redundant; each carries a distinct decision-relevant 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 7-parameter mutation tool with full annotations and full schema coverage, the description covers selection, audience, and the main misuse risk (over-posting to a human-visible board). The one gap is that with no output schema, it never says what the call returns (e.g., a card id usable with `refs` or `task_id`).

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 `to`, `ttl`, `kind`, `stage`, `refs`, and `task_id` are already fully documented with enums and defaults. The description only implicitly touches `summary` ('what was done') and `to` ('hand work to another agent'), adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb (post a message) and resource (shared board), plus the audience ('the human and other agents'). It explicitly routes readers to the sibling tool `board` for the opposite operation, so an agent can distinguish write from read without inspecting schemas.

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

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

Gives concrete triggers ('when finishing a unit of work', 'to hand work to another agent'), an explicit exclusion ('do not use it to report routine steps the human did not ask about'), and names the alternative for the inverse operation ('use board'). This is the full when/when-not/alternative triad.

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