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 declare readOnlyHint=false and destructiveHint=false, so the description carries the real burden and does: it discloses the asynchronous approval flow, that success means queued not stored, and that it cannot confirm its own writes. It does not contradict annotations — nothing written persists without human action.

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 sentences, each doing distinct work: purpose, trigger, exclusion, and the queued-not-stored caveat. The most decision-critical fact (pending queue, no confirmed write) is front-loaded.

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 workflow, the async success semantics, and retry safety, which is exactly what an agent needs before calling. It lacks a note on what a rejection looks like or whether tag/vault choices affect routing to the human, a minor gap given no output schema exists.

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

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

Schema coverage is 100%, so baseline is 3. The description only reinforces client_id idempotency semantics, which the schema already explains in nearly identical terms; content, vault, and vector are untouched in the description.

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

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

States a specific verb (submit a memory for human approval) and resource, and immediately distinguishes the outcome from siblings: it lands in a pending queue and changes no confirmed memory. An agent can tell this apart from recall (read) and say (communication) without opening any schema.

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

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

Gives explicit positive triggers ('when the human says to remember something', 'a decision is reached that will still matter later') and explicit exclusions ('not a scratchpad for transient reasoning', 'not data you merely fetched'). The alternative/anti-pattern guidance is unusually complete for this category.

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

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

Annotations already cover the read-only/destructive/idempotent profile, and the description deliberately adds what they cannot: results come only from the confirmed store, unreadable private vaults are silently omitted, and an empty list means no match rather than an empty memory. Those are exactly the non-obvious behaviors an agent would otherwise misread.

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 routing constraints and behavioral caveats are front-loaded and each sentence carries content. The one soft spot is the self-referential clause about what the annotations already declare, which is meta-commentary rather than tool guidance.

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

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

No output schema exists, and the description compensates by explaining result scope (confirmed store only), permission-driven omission, and the meaning of an empty result set. Nothing an agent needs to call this correctly or interpret its response is missing.

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

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

Schema description coverage is 100%, so limit, vaults, compact, query_vector and query are all fully documented in the schema. The description adds ranking framing ("closest stored entries") but says nothing about the parameters themselves, so the baseline of 3 applies.

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

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

States a specific verb (search) and resource (the human's confirmed memory) plus the retrieval semantics (natural-language query, closest stored entries). It is immediately distinguishable from sibling get_context (session bootstrap) and manage (pending review), which the description names directly.

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

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

Gives explicit when-to-use (find what was decided, recorded, or agreed) and two explicit when-not-to-use cases, each paired with the correct alternative tool: get_context for session start with no query, manage action list_pending for unapproved entries. 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?

Annotations already cover the safety profile (not read-only, not destructive, closed-world), so the description's added value is the audience-visibility model ('the human reads this board') and the credential constraint ('a caller cannot post as another agent'), which genuinely affects how an agent frames a message. It stops short of stating that repeat posts create duplicate cards despite idempotentHint=false, or what confirmation the caller gets 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?

Four sentences, zero filler, and the ordering is deliberate: what it does, when to use, when not to, where to read instead, then the identity guarantee. No sentence restates the title or 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 7-parameter post tool with no output schema, the description covers intent, audience, exclusions, and the auth model, which is nearly everything an agent needs to invoke it correctly. The remaining gap is the return behavior (confirmation, message id, whether the post can be edited or retracted later).

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

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

Schema coverage is 100% and the description adds no parameter-level detail beyond what the schema already says ('Write the outcome, not a log of steps' is repeated nearly verbatim from the summary description). With the schema doing all the work on 'to', 'ttl', 'kind', 'stage', 'refs', and 'task_id', the baseline 3 is right.

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 the shared board') and immediately identifies the audience (human and other agents). It also names the sibling 'board' as the read counterpart, so an agent can separate write-to-board from read-board 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 explicit triggers ('when finishing a unit of work, or to hand work to another agent'), an explicit exclusion ('Do not use it to report routine steps the human did not ask about'), and the alternative for reading ('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.