Recall

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

Goes well beyond the annotations by disclosing side effects (it creates the session and speakers on first use), asynchronous behavior (learning runs in the background, do not wait), and idempotency mechanics (a repeated key returns the first result). This is exactly the kind of mutation/async context an agent needs and cannot get from the 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?

Four tightly packed sentences, front-loaded with the core action and scoping rule, then side effects, then the idempotency instruction. No filler, and each sentence carries a distinct operational instruction.

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

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

With an output schema present, the description need not explain return values, and it fully covers scoping, side effects, async behavior, and retry handling for this 4-param mutation tool. Nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds usable meaning: it explains the timing/purpose of idempotency_key ('when a retry is possible') and constrains what should go into messages. It does not add format/syntax detail, but the added semantic value above the schema is real.

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

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

States a specific verb and resource ('Store specific messages... so memory can learn from them') and scopes it precisely to messages the user wants kept. The 'never the conversation history' clause distinguishes it from a general chat/history tool, so an agent can tell it apart from siblings like chat or search.

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

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

Gives clear when/when-not guidance: send only the messages to keep, never the conversation history, and pass idempotency_key when a retry is possible. It also tells the caller not to wait for learning. It does not name a specific sibling as the alternative, but the conditions for correct use are 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?

Annotations already declare readOnlyHint/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: answers are grounded in recorded data, and the tool explicitly says so when it does not know (abstention behavior). It omits any note about latency/cost of deeper reasoning, but the core behavior is 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 with illustrative examples and the read-only guarantee front-loaded; no filler. Every clause carries information useful for selection.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain return values or permissions. It covers purpose, grounding, and abstention adequately for a 7-parameter tool; only explicit sibling routing 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 documents all seven parameters, including the non-obvious peer_id/target_peer_id relationship, defaults, and the reasoning_level enum. The description adds nothing beyond this, 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 action and resource: ask memory a natural-language question and receive a written, grounded answer. The examples ("Where does the user live?") make the resource and output shape concrete. It does not explicitly distinguish itself from the sibling `search`, though the NL-question framing implicitly separates it.

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 through the examples and the read-only framing, but there is no explicit when-to-use guidance or routing against alternatives in the sibling set (`search`, `get_peer_card`, `list_conclusions`). An agent can infer intent but is not told when this beats a plain search.

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

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

Annotations already declare this is a write (readOnlyHint=false), non-idempotent, non-destructive. The description adds real behavioral context beyond them: "Creates the peers on first use" discloses a side effect (peer creation) an agent could not infer otherwise.

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

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

Two tight sentences, front-loaded with the purpose and followed by concrete examples and formatting guidance. No filler; the examples earn their space by clarifying what counts as a 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?

An output schema exists, so return values need no explanation. The description covers purpose, content format, and the peer-creation side effect, and the schema covers the optional session/workspace/peer parameters; only explicit sibling routing is absent.

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

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

Schema coverage is 100%, so all five parameters are already documented, making 3 the baseline. The description adds a little meaning — each conclusion should be a "short, self-contained statement" — but this is content-format advice rather than parameter clarification.

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 ("Save facts") with a concrete scope constraint ("facts you were told outright") and examples. It does not explicitly distinguish itself from siblings like add_messages_to_session or list_conclusions, so a 4 rather than 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?

Provides an implicit trigger — facts the user stated outright, as opposed to inferring them — and hints at timing ("so memory has them straight away"). However, it names no alternative tool and gives no explicit 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds genuinely new context: the deletion is irreversible ('cannot be undone') and requires user confirmation before executing. It does not cover auth/permission requirements or failure modes, keeping it 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?

Three short sentences, no waste, with the destructive nature front-loaded before the confirmation instruction and the id sourcing. Every sentence earns its place.

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

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

Output schema exists, so return values need not be explained. For a two-parameter destructive mutation, the description covers permanence, confirmation, and argument sourcing – nothing an agent needs to invoke 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%, so both parameters are already documented and the baseline is 3. The description goes beyond the schema by naming the tools (list_conclusions, search) that supply the required conclusion_id, adding practical meaning to the 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?

States a specific verb (permanently remove) and resource (one conclusion), plus the qualifying conditions (wrong or user-requested forgetting). An agent can distinguish it from create_conclusions, list_conclusions, and search 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?

Explicitly says when to use it (conclusion is wrong, or the user asked to forget), mandates confirming with the user first, and routes the agent to list_conclusions or search to obtain the required id. Both the when and the how-to-source-the-argument are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'Read-only' clause is redundant. What the description adds beyond the structured data is genuinely useful: it discloses that the call is cheap, that it is a sensible first call, and that it returns null when no card exists yet — a non-obvious return behavior.

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

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

Three tight clauses, front-loaded with the verb and resource definition, followed by cost/ordering guidance and the null-return caveat. No filler sentences and nothing repeated from the schema.

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

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

An output schema exists, so return structure need not be described, yet the description still flags the null case. With annotations covering the safety profile and full schema coverage on all three 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 description coverage is 100%, and the schema already explains peer_id, workspace_id defaults, and the target_peer_id indirection in detail. The description adds no parameter-level semantics beyond that, 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 the peer card') and immediately defines what the resource is: 'a short list of the most stable facts about a person (name, location, role, preferences).' That content definition cleanly separates it from siblings like search, list_conclusions, or get_session_context, none of which return a per-person fact card.

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?

'Cheap; a good first call' gives an explicit ordering heuristic for when to reach for this tool, which is real routing guidance. It stops short of naming alternatives or stating when not to use it (e.g., when you need richer context, use get_session_context), 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so the trailing 'Read-only' is largely redundant. The description does add that output is sized to a token budget and is prompt-ready, which is useful, but it omits default behaviors driven by the optional params (summary default true, session/peer defaults).

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 dense, front-loaded sentences enumerate the payload first, and the takeaway ('Drop the result into your prompt') follows immediately. The trailing 'Read-only.' fragment is slightly redundant against the annotations 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?

An output schema exists, so return values need no prose, and annotations cover the safety profile. The description adequately frames what the call assembles for a zero-required-param aggregation tool, though it could have flagged the default-behavior interactions of summary and peer_target.

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 eight parameters, including defaults and bounds. The description echoes token budget, summary, and optional peer presence but adds no syntax or format detail beyond the schema, 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?

The description names a concrete verb (Get) and enumerates the exact resource payload: a summary of older turns, recent messages, and the peer representation plus peer card. This distinguishes it from siblings like get_peer_card and search, which return only fragments of the same data.

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 implies usage ('to continue a conversation', 'Drop the result into your prompt') and hints that peer data only appears 'with a peer', but never states when to prefer this over get_peer_card, search, or chat, nor any exclusions. Usage is inferable but not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Read-only' in the description is largely redundant. The description does add one genuinely useful cross-tool fact: returned ids can be passed to delete_conclusion. No mention of pagination defaults beyond what the schema carries.

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

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

Two tightly written sentences, front-loaded with the resource and ordering, with the delete-tip last. 'Read-only' is the only phrase that duplicates annotation data rather than earning 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?

An output schema exists, so return values need not be described, and all nine parameters are documented in the schema. The description covers the two modes adequately; only the ambiguous boundary with the `search` sibling is left unaddressed.

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 nine parameters (including peer_id, target_peer_id, reverse, session_id) are already documented in the schema. The description echoes the query and ordering behavior but adds no syntax or default details 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+resource ('list the facts/conclusions') plus scope ('about a person, newest first, or best matches for a query'), so the two operating modes are clear. It does not, however, differentiate from the sibling `search`, which likely covers overlapping query semantics.

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?

Describes the two modes (plain listing vs query match) and notes the id feeds delete_conclusion, which implies usage. But it gives no explicit when-to-use/when-not guidance against alternatives like `search` or `get_peer_card`, leaving the agent to infer 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered and the trailing 'Read-only' is largely redundant. The description earns credit for disclosing the retrieval mechanism ('Hybrid keyword and semantic search') and that results combine messages with peer facts, which annotations do not 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?

Three short sentences, front-loaded with what the tool returns, followed by the mechanism and the routing contrast. No sentence is wasted and nothing important is buried.

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

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

With an output schema present, return values need no explanation, and the description covers scope, mechanism, and the primary alternative. It is only slightly incomplete in not clarifying the division of labor with the facts-oriented siblings (list_conclusions, get_peer_card).

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 query, peer_id, session_id, workspace_id, and both limits including defaults. The description's conditional 'plus (for a peer) the facts memory holds about them' hints at peer_id behavior but adds no syntax, format, or constraint 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 ('Find raw evidence: messages that match the query') and clarifies the compound result set by including peer facts. It also distinguishes itself from the chat sibling directly, so an agent can tell the two 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?

Explicit routing guidance is given against the most confusable sibling: 'Use chat when you want an answer instead of evidence.' However, it does not address the overlap with list_conclusions/get_peer_card for the facts portion of its output, leaving one ambiguity for the agent to resolve on its own.

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