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

The description discloses behavioral traits beyond annotations: it explains gate blockers (conflicts, downgrade, first canonical) and the effect of force=true. Annotations already indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds context on validation and override behavior. No contradiction.

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 concise (three sentences) and well-structured: purpose, gate behavior, force option. Each sentence adds value without 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?

The description covers the main behavior (promotion, gate blockers, force override). While it doesn't explicitly state the success output format, the purpose is clear. Given no output schema, the description is adequate for an agent to invoke 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 baseline is 3. The description adds value by explaining the role of force in overriding gate blockers, which goes beyond the schema description. It clarifies the decision pathway, but parameters are already well-described in 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 clearly states the action: 'Promote a draft snapshot to canonical.' It specifies the resource (draft snapshot) and outcome (supersedes prior canonical), distinguishing it from sibling tools like save_snapshot (draft creation) and get_snapshot (retrieval).

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

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

The description provides context for when to use the tool (to finalize a draft) and explains the gate blocker mechanism and force override. However, it lacks explicit guidance on when not to use it or compare to similar tools like commit, which could improve clarity.

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 reveals INSERT-only behavior, no overwrite, intentional lack of conversationId, and queryability via GET endpoint. This adds value beyond annotations (readOnlyHint=false, destructiveHint=false) and 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?

The description is substantive and well-structured with sections (WHEN TO USE, INSERT-only, QUERYABLE, EXAMPLES). While slightly lengthy, every sentence adds value; no 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?

Given the tool's complexity (6 params, no output schema), the description covers all necessary aspects: purpose, usage, parameters, behavior, and examples. It is self-contained and 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?

All 6 parameters have schema descriptions (100% coverage). The description adds context: title patterns, verbatim content requirement, key_result as single-sentence deliverable, auto-added tags. This enriches the schema beyond raw definitions.

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 states the tool's purpose: persisting commitment-shaped artifacts (PRD, ADR, spec, OKR) as memories with intent='commitment'. It provides examples and distinguishes itself as the write primitive for specific slash commands, differentiating from 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?

The description explicitly states when to use (after artifact is fully drafted, for slash commands) and what not to do (do not summarize). It also clarifies insertion semantics (INSERT-only, never overwrite) and mentions queryability, providing clear 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?

The description details exactly what state changes occur: sets status='done', records completion_summary, clears active_session_id. It also specifies the return structure. This goes beyond the annotations (which only indicate non-read-only, non-destructive, non-idempotent, and open-world) by providing concrete behavioral details without contradiction.

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 concise and well-structured: three short paragraphs followed by a bulleted 'RETURNS' section. The main action is front-loaded, and every sentence adds necessary information with no 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 absence of an output schema, the description fully compensates by detailing the return fields (completed, next_task, message). It also explains the behavioral impact and usage context, making it complete for agent decision-making.

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 input schema covers all three parameters with descriptions (100% coverage). The description adds value by explaining that 'verification_summary' becomes 'completion_summary' and that 'task_id' comes from 'get_next_task', offering meaningful context 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 explicitly states the action ('Mark a project task as done') and the resource ('project task'), using specific verbs and distinguishing the tool by mentioning it closes the Jered Loop and returns the next pending task, which differentiates it from siblings like get_next_task.

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

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

The description provides explicit when-to-use guidance: 'Call this BEFORE ending a session — Jered's rule: consciously close each task.' It also explains the effects (sets status, records summary, clears session). While it doesn't explicitly state when not to use, the context is clear enough for a completion 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 indicate readOnly, destructive, idempotent, and openWorld hints. The description adds valuable behavioral context: it explains that the tool uses semantic clustering, groups results by topic, and includes platform indicators. This goes beyond annotations and helps the agent understand the tool's 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?

The description is well-structured with a title, bullet points, examples, and a response format section. It is front-loaded with key information. However, there is slight redundancy (e.g., repeating 'automatically discover' and 'Searches for memories'), making it slightly less concise than optimal.

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 tool's complexity (three parameters, no output schema), the description covers the main aspects: behavior, cross-platform nature, grouping, and platforms. Examples provide concrete scenarios. The response format is described at a high level, which is sufficient without an output schema. No critical gaps.

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 each parameter already has a description. The tool description adds minimal additional context for parameters, mainly implied through examples. It does not enhance understanding of parameter constraints or usage beyond what the schema provides.

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 states the tool's purpose: 'Find related conversations across ALL AI platforms' using semantic clustering. It specifies the verb (discover/find) and the resource (related conversations), and distinguishes from siblings like recall_memories by emphasizing cross-platform discovery and semantic grouping.

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

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

The description provides explicit guidance on when to use the tool (to discover related conversations across platforms) and includes practical examples. However, it does not explicitly mention when not to use it or suggest alternative tools among siblings, which slightly limits its completeness.

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 mark it as readOnlyHint=true and idempotentHint=true. The description reinforces this with 'No new data is generated' and details the 5-layer compaction process, adding behavioral context beyond 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?

The description is concise (10 lines) with a clear front-loaded purpose. Each section (intent, decisions, etc.) is presented succinctly. No unnecessary information is included, and the structure aids 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?

Given the tool's simplicity (2 optional params, no output schema) and strong annotations, the description fully covers the behavioral context: what it does, how it works (5-layer compaction), when to use it, and the fact it uses existing data. No gaps remain for an agent to understand the 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% and already describes both parameters (project_name, token_budget) with defaults and ranges. The description adds context by mentioning the token budget in relation to the compaction hierarchy, but does not significantly enhance understanding 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 clearly states the tool generates a surgical context brief for a new AI session, specifying the verb 'generate' and the resource 'handoff brief'. It distinguishes itself from re-explaining context by leveraging existing data, and the 5-layer hierarchy adds specificity.

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 when to call: 'at the start of a new session or when switching projects'. Also contrasts with re-explaining context, providing an alternative. However, it does not directly compare to sibling tools like recall_memories or get_snapshot, which could serve similar purposes.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds beyond that: sorting by occurrence count, inclusion of recent_occurrences[], and filters applied. No contradictions.

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 well-structured with sections (USAGE, QUERY PARAMETERS, EXAMPLE, RETURNS), front-loads the main purpose, and is not overly verbose. The example is useful. Minor trim possible but overall efficient.

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 no output schema, the description clearly specifies the return format (acknowledged_errors array, total_count, filters_applied). All parameters are documented with examples and defaults, making it complete for a read-only fetch 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% with descriptions for all 3 parameters. The description adds context with defaults, explanations, and a helpful example. Since the schema already fully describes parameters, the description adds moderate extra value.

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 states the tool fetches open and acknowledged errors for AI investigation, specifying statuses and including recent_occurrences. This distinct purpose differentiates it from sibling tools like get_investigations or get_test_results.

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 USAGE section provides explicit triggers ('investigate errors', '/investigate-errors') and details sorting and context. While it doesn't explicitly state when not to use or list alternatives, the clear purpose makes the usage context obvious.

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, destructiveHint=false, idempotentHint=true. The description adds that it lists artifacts and pairs with save_artifact, which is consistent but does not provide significant additional behavioral traits beyond what annotations offer.

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 consists of two concise and front-loaded sentences with no wasted words. It efficiently conveys the purpose and relationship to a sibling 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?

Given the tool has 3 well-documented parameters and no output schema, the description is adequate for a simple list operation. It could mention the response format, but the context signals and annotations provide sufficient information.

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 parameters are documented in the schema. The description adds no extra meaning or examples for parameters, maintaining the baseline score of 3.

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 states the tool lists artifacts linked to a parent conversation, with a specific verb 'List' and resource 'artifacts'. It also mentions pairing with save_artifact, which distinguishes it from other list tools like get_investigations or get_snapshot.

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

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

The description implies usage context by stating 'pairs with save_artifact', but does not explicitly provide when-to-use or when-not-to-use guidance compared to sibling tools. No exclusions or alternatives are mentioned.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds only the 'admin' context, but does not discuss return format, pagination, or other behavioral traits beyond 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?

The description is a single, efficient sentence that front-loads the main purpose. No wasted words, but could be slightly expanded for clarity.

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 simple listing tool with no output schema, the description is adequate. However, it lacks details about return values and specific usage scenarios, and the pairing hint is minimal.

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?

Input schema coverage is 100% with clear descriptions for all three parameters. The description does not add additional meaning beyond what the schema already provides.

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 states the verb 'List', the resource 'error investigation results', and the audience 'admin'. It also names a sibling tool, distinguishing it from others like 'save_investigation_result'.

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

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

The description implies usage by stating it pairs with 'save_investigation_result', but lacks explicit guidance on when to use versus other listing tools or when not to use.

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, destructiveHint, idempotentHint. The description adds behavioral details about chunked memory linked parts and pagination via offset/maxChars parameters, which are not covered by annotations. This adds 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?

The description is a single sentence that is front-loaded with the primary action and resource, no wasted words. Every part adds value.

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 tool with 4 parameters and no output schema, the description leaves out the structure of 'complete details' and potential limitations. It covers purpose and major features but could be more complete regarding response format or error conditions.

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 3. The description adds contextual meaning to the parameters (e.g., 'linked parts' maps to includeLinkedParts, pagination hints for offset/maxChars). However, it does not elaborate on parameter syntax beyond 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 clearly specifies the verb 'Get' and resource 'complete details of a specific memory', including the notable feature of linked parts. This distinguishes it from sibling tools like recall_memories (listing) and get_public_memory.

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

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

The description implies usage for retrieving full memory details, especially for chunked memories, but lacks explicit when-to-use or when-not-to-use guidance or alternatives. The context is provided by the tool name and schema, but no direct 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?

Discloses state change (marks task active), mentions the structured queue nature, and that tasks are created explicitly. Annotations indicate readOnlyHint=false and no destructiveHint, consistent with description. No contradictions.

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?

Well-structured with sections, bullet points for return values. Front-loaded with main purpose. No unnecessary sentences.

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

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

Given no output schema, description explicitly lists all return fields. Covers context, usage, side effects, error case. Complete for a task fetching/updating 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% with description for project_name. Description adds minimal value beyond schema (example value 'purmemo'). 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?

Clearly states 'Get the next pending task for a project and mark it active.' Specifies verb (get), resource (next pending task), and scope (for a project). Distinguishes from sibling tools like complete_task and recall_memories.

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 explicit guidance: call at start of work session, use recall_memories if no pending tasks, and call complete_task after finishing. Clearly distinguishes from recall_memories as alternative for finding work items.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that no authentication is required and lists the return contents (observations, entities, etc.), providing context beyond annotations without contradiction.

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 well-structured with header, WHEN TO USE, explanatory note, example, and RETURNS. Each sentence adds value, and there is no wasted text.

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?

Despite no output schema, the description lists all return components (content, observations, entities, tags, author attribution, metadata). Given the tool's simplicity (one parameter and full annotations), the description is complete and sufficient.

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% with the parameter 'memory_id' well-described as 'UUID of the public memory to retrieve in full'. The description provides an example usage but does not add significant new meaning 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?

The description clearly states 'Retrieve the FULL content of a public or unlisted memory by ID.' It specifies the verb (retrieve), resource (public memory), and scope (full content). It distinguishes from the sibling tool 'recall_public' which returns a preview.

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

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

The description explicitly states when to use: after recall_public, when user wants to read/implement, when having a public memory ID. It also notes that this tool 'closes the loop' with recall_public. Though no explicit when-not, the context is clear.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds 'Fast — no LLM calls,' providing further behavioral context without contradicting 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?

The description is extremely concise with two short sentences plus a focused usage section. Every word adds value, and the most critical info 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?

All essential aspects are covered: purpose, usage guidelines, behavioral traits, and parameters. No output schema is needed for this read operation, and the description is 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 description coverage is 100%, so the parameter descriptions are sufficient. The tool description does not add extra meaning beyond what the schema already provides, meeting the baseline.

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 states the tool reads an existing canonical snapshot into context, distinguishing it from sibling tools like save_snapshot or snapshot_sources.

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 explicit 'WHEN TO USE' section provides clear guidance on when to invoke this tool (when needing current canonical state without generation), and implies when not to use (when generation is needed).

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds context about pairing with save_test_result, default limit (50) and max limit (200), and return structure with fields (id, test_suite, passed, failure_details, updated_at). No contradictions.

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?

Well-structured with clear sections: main purpose, pairing note, usage examples, returns. Concise with no redundant information. Front-loaded with primary action.

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 purpose, usage, default limit, max limit, and return fields. Given no output schema, description adequately describes response structure. Ordering ('newest first') is specified. Complete for a simple list 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% with each parameter described. Description provides usage examples that illustrate parameters (passed filter, limit) and explains default and max limit, but does not add significant semantic 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?

Clearly states 'List recent test results for a project, newest first.' Specifies verb, resource, and ordering. Distinguishes from sibling tools like save_test_result.

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 tells when to use: 'Pairs with save_test_result — use this to recall past test outcomes without having to query the conversational memory layer.' Provides usage examples with different filtering options. Lacks explicit when-not but covers alternatives.

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, destructiveHint=false, idempotentHint=true. The description adds behavioral context by explaining the tool returns identity, session, and memory summary, and illustrates this with an example. It reinforces the safe, read-only nature without contradicting 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?

The description is well-structured with clear sections (WHAT IT RETURNS, WHEN TO CALL, EXAMPLE USAGE) and front-loads the purpose in the first sentence. It is somewhat lengthy but each section adds value, especially given the absence of an output 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?

With zero parameters, no output schema, and informative annotations, the description fully compensates by detailing the return payload, usage timing, and an example. It provides complete context for an agent to use this 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?

The tool has zero parameters, so schema coverage is complete. The description does not need to add parameter semantics, and the baseline of 4 is appropriate since no parameters exist to elaborate on.

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: 'Get the current user's cognitive identity and active session context.' It clearly distinguishes this tool from siblings by focusing on identity and session context, and further clarifies it is 'the core of Purmemo's identity layer.'

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 'WHEN TO CALL' section provides explicit usage scenarios: at the start of a new session, when the user requests context, and before making recommendations. It does not explicitly mention when not to use or alternatives, but given the tool's unique role among siblings, this is sufficient 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail above annotations: the read-only label reinforces safety, and it explains the dual-mode behavior (list vs open) and how project titles span all themes. It doesn't disclose return format or pagination, but the annotated safety profile and mode explanation cover most of the behavioral burden.

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 tightly-scoped sentences, zero filler. Every sentence earns its place: mode 1 (no-arg galaxy view), mode 2 (open with cluster=), and the pairing tip with recall_memories. Front-loaded with the purpose verb and immediately readable.

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 tool with no output schema and strong annotations, the description is complete. It covers both invocation modes, the pairing workflow with recall_memories, and read-only safety. The complexity is low and fully documented. There is no return-format requirement since output_schema is absent but the tool is simple enough that this isn't a 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% — the schema already documents the cluster parameter (title case-insensitive or UUID, omit to list). The description adds the dual-mode orchestration detail (open vs list) and mentions case-insensitivity is in the schema. Baseline 3 for full schema coverage is appropriate; the description reinforces but doesn't substantially expand 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 clearly states a specific verb+resource ('Browse/list clusters') with an explicit two-mode behavior: no-arg listing of PROJECT -> THEME hierarchy with counts, and cluster= argument that opens a cluster and lists its member memories. It distinguishes itself from siblings by naming recall_memories as the semantic-search companion and from get_memory_details as a different level of granularity.

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 explicit when-to-use guidance: 'use this to show what projects/topics do I have?' and explains the open vs list modes with cluster=selector behavior. Names the pairing companion recall_memories(cluster=...) explicitly for semantic search afterward, giving clear context on when this tool vs alternatives 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, destructiveHint, idempotentHint. Description adds that output is 'full catalog organized by category with descriptions', which is helpful beyond 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?

Two concise paragraphs, front-loaded with purpose, then usage guidelines. No wasted words.

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

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

Covers purpose, usage, output structure. No output schema needed; description sufficiently describes return format.

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% with adequate description for the single parameter. Description adds no further detail beyond 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?

Clearly states it lists workflows and describes them as 'structured, memory-powered processes'. Distinguishes from siblings like run_workflow.

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 provides a 'WHEN TO USE THIS TOOL' section with specific user queries, guiding selection vs. alternatives.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is fully covered. The description adds behavioral context by explaining ranking semantics ('ranked by semantic relevance'), the Phase 2 Knowledge Graph filtering capability, and filter behaviors like partial matching vs exact match for different filters. It does not describe pagination or total return behavior beyond the limit parameter, but the annotation coverage is strong.

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?

Well-structured with clear sections (BASIC SEARCH, FILTERED SEARCH, WHEN TO FILTER, COMBINED EXAMPLES) using emoji headers for visual scannability. The content is somewhat verbose with many examples, but each serves a distinct purpose (each filter has its own example). The combined examples at the end add practical value. Slightly longer than strictly necessary but well-organized and front-loaded with the core purpose.

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 tool with no output schema, this description is remarkably complete. It covers all filter types with examples, provides usage timing guidance, distinguishes exact vs partial matching semantics, and gives combined real-world patterns. The sibling context shows this is a memory-retrieval tool among many, and the description effectively positions it as THE semantic memory search tool. No output schema exists, so return-format information would be valuable but the schema itself documents the limit parameter and the filter semantics are thoroughly covered.

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 has rich descriptions with usage guidance and examples. The description adds value by showing FILTERED SEARCH patterns, the Phase 2 context, and combined examples like recall_memories(query='auth', entity='purmemo', has_observations=true). It also corrects/clarifies the 'stakeholder' parameter mentioned in the combined example that wasn't prominently promoted. However, some of this is redundant with the 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 states a specific verb+resource ('Search and retrieve saved memories') with clear semantic ranking. It distinguishes itself from siblings like recall_public (public memories) and get_memory_details (single memory lookup) through its filter-focused identity. The extensive examples reinforce the core purpose.

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 explicit WHEN TO FILTER guidance with concrete use-cases ('Use entity when user asks about specific person/project by name', 'Use intent when user asks for decisions'). The description explains when filters are needed for PRECISION over semantic similarity, and demonstrates combined usage patterns. It clearly distinguishes filtered vs basic search scenarios.

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, destructive, idempotent, and openWorld hints. The description adds non-obvious behavioral context: it does not consume recall quota, returns author attribution and relevance scores. No contradiction with 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?

The description is well-organized with labeled sections, front-loading the core purpose. Every sentence contributes useful information, though the 'FILTERS' section slightly repeats schema details.

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

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

The description explains return values (list with author attribution, relevance scores, recall counts) despite no output schema. However, it omits how the 'page' parameter works (pagination limits, default behavior), leaving a minor completeness 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 100%, so baseline is 3. The description provides additional semantics for parameters (e.g., 'semantic search query', 'by recall count' for sort) and gives an example call, adding value beyond 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 explicitly states 'Search public memories shared by all Purmemo users' with clear verb (search) and resource (public memories). It distinguishes from sibling 'recall_memories' (private) and 'get_public_memory' (single memory fetch).

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 'WHEN TO USE' section lists four concrete scenarios with user-question phrasing. It also specifies what the tool does NOT do (count against quota), providing clear boundaries.

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 (which declare non-destructive, idempotent, open-world), the description reveals that after 3 reports, a memory is automatically hidden from public view pending admin review. This adds valuable insight into the tool's side effects and consequences of repeated use.

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 well-structured with a clear header, 'WHEN TO USE' section, list of reasons, a behavioral note, and an example. It is concise, front-loaded with the purpose, and every sentence adds value without 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?

Given the tool's simplicity (no output schema), the description covers essential aspects: purpose, use cases, reasons, and a key behavioral outcome. The example provides a concrete usage pattern. It could be slightly more complete by explaining the return result, but it is sufficient for an agent.

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 input schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds a bit of extra context by listing the reasons and giving an example call, but it doesn't significantly elaborate on parameter meanings 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 clearly states the tool's action ('report') and resource ('public memory') with the specific purpose ('inappropriate content'), using a strong verb and resource combination. It distinguishes itself from sibling tools by explicitly mentioning a unique function not covered by others.

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

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

The description provides explicit 'WHEN TO USE' conditions, listing relevant scenarios like spam, misleading content, and personal information. It also includes the allowable reasons, offering clear context for when the tool should be invoked, though it does not explicitly state 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds behavioral context beyond that: memories are automatically loaded, and workflows can auto-route based on intent. This is useful, though it doesn't detail potential side effects or output behavior (which may be acceptable given the readOnly hint).

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 long but well-organized with clear headings, examples, and a negative usage section. Every section serves a purpose. It is slightly wordy but appropriately structured for a tool with many workflow options and routing rules.

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

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

The description is thorough on usage, workflows, and exclusions, but it omits any mention of return values or output format. Since there is no output schema, the description should compensate for this lack. Without knowing what the tool returns (text, steps, or a status), an agent cannot fully anticipate the tool's behavior, leaving a notable gap.

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

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

Schema description coverage is 100% for both parameters, but the description adds significant semantic value by listing valid workflow names, providing concrete examples of input and workflow values, and explaining the auto-routing behavior when the workflow parameter is omitted. This goes well 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 clearly states the tool's purpose: 'Run a Purmemo workflow — structured, memory-powered processes' and distinguishes it from sibling tools by listing what NOT to use it for (e.g., recall_memories, save_conversation, discover_related_conversations). The available workflow list further clarifies its scope.

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

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

The description includes an explicit 'WHEN TO USE THIS TOOL' section with concrete scenarios and a 'DO NOT use this tool for' section naming alternative tools. It also explains auto-routing when no workflow is specified, giving clear guidance on when to call and when to avoid.

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 are present (readOnlyHint: false, destructiveHint: false, openWorldHint: true). The description adds context about artifacts being high-value and becoming searchable objects, which goes beyond the annotations. It does not contradict 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?

The description is well-structured with clear sections (short statement, WHEN TO USE, WHY, FLOW, IMPORTANT). It is front-loaded with key information and every part serves a purpose without 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?

Given the parameter count, required fields, no output schema, and annotations, the description fully covers purpose, usage flow, parameter details, and importance. An agent can effectively use the tool based on this description.

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 adds semantics for conversationId (must match save_conversation), content (full verbatim, not summary), and provides examples for title and type. This adds value 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 clearly states the tool saves a single artifact linked to a conversation memory, with a specific verb and resource. It distinguishes from siblings like save_conversation and save_investigation_result by focusing on artifacts.

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

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

The description provides explicit WHEN TO USE guidelines, stating it should be called after save_conversation, once per artifact, with full content. It includes a FLOW example and explicit instructions not to summarize or truncate.

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, destructiveHint=false, openWorldHint=true. The description goes well beyond annotations by disclosing that prior content is NEVER lost (snapshotted to memory_events audit log), documenting the server-side chunking behavior (>15K auto-split), the append-chunking rejection limit, and the ADR-038 orphaned memory caveat. It also discloses the field constraints like minimum characters. The only area not covered is return format/output, though that's largely acceptable given this is a save operation.

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 long but densely informative with clear section headers (HOW SAVES TARGET MEMORIES, PRIOR CONTENT IS NEVER LOST, INTELLIGENT EXTRACTION, SERVER AUTO-CHUNKING, EXAMPLES, WHAT TO INCLUDE, FORMAT REQUIRED, ARTIFACT PRESERVATION). Front-loads the critical requirement (send complete content) first. It earns its length given the complexity of the tool's behavior, though some redundancy exists between the opening paragraphs and the later 'WHAT TO INCLUDE' section which repeats the same admonitions about complete content.

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 complexity (6 params, chunking behavior, append/replace semantics, audit logging, ADR caveats, artifact handoff), the description is remarkably complete. It covers edge cases (append+chunking rejection), warns about the orphaned memory caveat, provides the exact required format template, and provides a clear action flow for artifact preservation. There is no output schema, so return-value documentation isn't necessary, and the description adequately compensates for the tool's behavioral complexity.

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%, providing baseline 3. However, the description adds substantial meaning beyond the schema: it explains the auto-generation of conversationId from title slug, details the exact append separator format (\n\n--- UPDATE <ISO8601> ---\n\n), explains the conversationContent minimum is actually 500 chars not just the 100 in schema, and provides concrete EXAMPLES showing parameter usage for each mode. The description compensates heavily and transforms the parameters into a clear mental model.

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 states the purpose: saving complete conversations as memories, with a specific emphasis on requiring complete verbatim content. It distinguishes itself from siblings like save_artifact (which is explicitly referenced for artifacts) and recall_memories by describing the write/save function distinctly. The verb+resource ('Save... as memory') plus the content requirements make the purpose unmistakable.

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

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

The description provides exceptionally detailed guidance on when to use this tool, how mode affects targeting, and explicitly names save_artifact as the alternative for artifacts ('save them SEPARATELY using save_artifact after this call'). It distinguishes replace vs append use cases, explains the /save skill behavior, and gives explicit when-to-use guidance for living documents vs one-shot snapshots.

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 indicate readOnlyHint=false and destructiveHint=false, so the tool is a write operation but not destructive. The description adds that it stores results for audit trail and returns specific fields. It does not contradict annotations. It could mention more about idempotency or overwrite behavior, but given annotations are present, the description provides adequate 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?

The description is well-structured with sections (header, usage, request fields, example, returns). It is relatively long but every section adds value. The front-loaded purpose statement helps quick understanding. Minor redundancy in the usage section could be trimmed, but overall it's effective.

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 tool has 12 parameters, nested objects, and no output schema, the description covers each parameter, provides an example, and lists return fields. It explains the tool's role in the investigation workflow. It could clarify optional parameters' behavior when omitted, but it is sufficiently complete for an agent to use 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?

Parameter descriptions are already present in the schema (100% coverage). The description goes further by grouping them under 'REQUEST FIELDS' and explaining usage context, e.g., 'root_cause_analysis: Your analysis', 'similar_incidents_analyzed: from recall_memories'. This adds semantic depth 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 begins with a clear action: 'Save AI investigation results for an error incident.' It specifies the resource (investigation results) and context (error incident, audit trail). The usage section ties it to a specific workflow step (after investigation and fix deployment), distinguishing it from sibling tools like save_artifact or save_snapshot.

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

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

The description provides explicit usage instructions: 'Call after completing investigation and deploying fix.' It explains the purpose (store for audit trail, learning). However, it does not explicitly state when not to use this tool or mention alternative tools for different scenarios. Still, the guidance is clear and useful.

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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds valuable behavioral context: 'Runs claim verification on your content' and 'Backend derives evidence_tier from cited_ids — not caller-controlled.' This goes beyond annotations, though it could mention side effects or error conditions.

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 concise sentences: first states the primary action, second provides usage context and step number, third adds behavioral notes. No fluff, front-loaded with key information. 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?

Given the multi-step snapshot process and 4 parameters, the description effectively sets context (step 3, post-snapshot_sources). It mentions claim verification and evidence_tier derivation but does not specify return values or next steps (e.g., accept_snapshot). With no output schema, a brief note on output would improve completeness.

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 adds marginal value by explaining that evidence_tier is derived from cited_ids, adding meaning to that parameter. The force parameter's effect is implied but not elaborated. Overall, the description complements the schema without fully compensating for its own lack of detail.

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 states the tool persists a synthesized snapshot draft and identifies it as step 3 of the MCP snapshot path. It distinguishes from siblings like snapshot_sources (which produces sources) and accept_snapshot (which finalizes), making the purpose specific and 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?

The description explicitly says 'Call this after synthesizing from snapshot_sources()', providing clear usage context. It also notes that evidence_tier is backend-derived and claim verification runs. However, it does not mention when not to use this tool or alternatives for non-draft saves, slightly limiting 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?

Discloses idempotent behavior: 'Re-running with the same test_suite name updates the existing memory (living document).' Also explains linking to active task and return values. Adds significant value beyond annotations which only hint at idempotency.

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?

Concise, well-structured with clear sections (purpose, usage, returns). Every sentence adds value without redundancy. Front-loaded with core action.

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 4 parameters, no output schema, but description thoroughly covers inputs, behavior (update on re-run), linking, and return values. Complete for a straightforward save 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?

All 4 parameters are described in schema (100% coverage), but the description adds extra context: failure_details is only for passed=false. Usage examples show parameter combinations, enhancing schema clarity.

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 states 'Save a test result memory for a project, linked to the current active task,' using specific verb and resource. It uniquely identifies the tool's purpose among siblings like 'save_artifact' or 'save_investigation_result'.

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 'Call this after running tests — pass or fail — to record the outcome' and provides examples for both passing and failing cases. Does not explicitly exclude other use cases or mention alternatives, but the context is clear.

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

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

The description adds value beyond annotations by disclosing ownership requirement, quota limits, and return behavior. No contradiction with annotations; it complements them with practical constraints.

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 well-structured with clear sections (VISIBILITY LEVELS, WHEN TO USE, QUOTA, EXAMPLE, RETURNS). It is concise yet informative, with no unnecessary words.

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

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

For a tool with 2 required parameters and no output schema, the description is complete: it explains what the tool does, when to use it, the effects of each parameter, and what the agent can expect as return. Adequate for correct invocation.

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 the schema covers 100% of parameters, the description adds meaning by explaining the visibility enum values in the VISIBILITY LEVELS section and providing an example usage. This clarifies the purpose of each parameter 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 clearly states the verb 'set' and the resource 'visibility of a memory you own', and distinguishes it from sibling tools like recall_memories and get_public_memory. The inclusion of visibility levels and usage scenarios reinforces purpose clarity.

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 'WHEN TO USE' section lists specific conditions, providing clear context for when to invoke the tool. It does not explicitly state when not to use, but the guidance is sufficient for an AI agent to decide.

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 indicate readOnlyHint=false (creating), destructiveHint=false (non-destructive draft), idempotentHint=false (each call creates new draft), and openWorldHint=true. The description adds detailed behavioral context: it is INSERT-only, creates a draft, explains the process (fuzzy match, recency-weighting, evidence tier), and mentions future integration ('Gemini integration ships later').

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 well-structured with sections (WHEN TO USE, HOW IT WORKS, EXAMPLES) and bullet points. Every sentence adds value without unnecessary verbosity.

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?

Despite no output schema, the description explains the output: a draft snapshot with evidence_tier and grounded_ratio, status='draft', and the required subsequent action (accept_snapshot). It covers the tool's behavior comprehensively.

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 single parameter 'topic' has full schema coverage (100%) with description, min/max length, and examples. The description adds meaning beyond schema: it explains the parameter is used for fuzzy matching against tags and titles, and that matching is recency-weighted.

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 states the tool's purpose: 'Generate a state-shaped artifact for a topic from your saved memories.' It uses a specific verb ('Generate') and resource ('artifact'), and the description differentiates it from siblings like 'get_snapshot' and 'accept_snapshot' by detailing that it creates a new draft.

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 'WHEN TO USE' section explicitly lists use cases (architecture map, glossary, runbook, etc.) and mentions the slash command. While it doesn't explicitly say when not to use alternatives, the context is clear and differentiates from other snapshot-related tools.

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 and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable behavioral context by explaining the role as step 1 of a multi-step process and what it returns (sources + conflicts), which goes beyond 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?

The description is well-organized with clear sections (main purpose, WHEN TO USE, FLOW) and uses concise, direct language. While slightly longer than necessary, it efficiently communicates all critical information without 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?

Given the tool's simplicity (one parameter, read-only, no output schema), the description is complete. It explains the tool's placement in a workflow, what it returns, and how to proceed (synthesize and call save_snapshot). The absence of an output schema does not detract because the description implies the return structure.

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% for the single parameter 'topic', and its description already explains fuzzy matching. The tool description does not add additional semantic meaning beyond what the schema provides, so the baseline score of 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 clearly states the tool fetches citation bundles and conflict detection for a topic, with specific verbs ('Fetch') and resources ('citation bundle + conflict detection'). It distinguishes itself from sibling tools like save_snapshot and accept_snapshot by explicitly outlining the snapshot generation flow.

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 'WHEN TO USE' section explicitly states the tool is for generating a snapshot from inside Claude, providing clear context. It references sibling tools (save_snapshot, accept_snapshot) in the flow but does not explicitly state when not to use it, which is acceptable given the clarity of the flow.

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