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

Beyond the readOnlyHint annotation, the description discloses that the tool is 'Pure TypeScript — no LLM call,' lists the exact policy decision order, and explains the three possible outcomes. The 'Always audit what was decided and why' note adds behavioral context about expected follow-through, significantly enriching the annotation-only safety profile.

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

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

The description is front-loaded with purpose, then efficiently enumerates the entire policy decision table in a compact colon-separated list. Every sentence contributes essential information—purpose, inputs, computational nature, and policy order—with no filler or repetition.

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 core decision logic, output values, and policy ordering, sufficient for an agent to invoke the tool. However, it does not specify the exact return JSON shape (e.g., fields beyond decision/reason), and the 'Always audit' statement is ambiguous as to whether the tool itself logs or the agent must do so. Given no output schema, slightly more explicit return-field documentation would make this fully 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?

With 100% schema description coverage, the schema already documents the parameters. The description adds meaning by clarifying that assessment must be the full output of risk_assess and by giving concrete examples for action_type ('npm publish', 'git push origin main'). It does not mention entity_id, but the schema covers it, so the incremental value is solid but not maximal.

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 action: 'Apply the Brain OS policy table to a risk assessment.' It clearly names the resource (policy table), the input (risk assessment), and the output (allow/ask/block decision). This distinguishes it from sibling risk_assess, which produces the assessment, and decision_check/review tools.

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 it 'Takes the output of risk_assess plus the concrete action type,' establishing a clear pipeline context and when to use it. It does not explicitly name alternatives or when-not-to-use cases, but the dependency on risk_assess and the detailed policy ordering provide clear usage context.

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

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

With readOnlyHint already present, the description adds useful context: the tool returns time-ordered history, covers all memory mutations, and serves integrity/debugging purposes. It does not contradict the annotation, but it omits details like ordering direction (e.g., newest first) and the exact shape of returned entries, so it is not fully transparent.

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 two sentences, front-loaded with the core purpose, then provides usage guidance and an explicit contrast with a sibling tool. Every sentence earns its place with no redundancy or filler.

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

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

For a read-only audit log with three optional filters, the description covers purpose, usage scenarios, and differentiation from semantic_recall. It doesn't specify the return format or ordering direction, but given the simplicity of the tool and the presence of readOnlyHint, these are minor gaps. The description is sufficiently complete for an agent to select and invoke it correctly.

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

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

The input schema already documents all three parameters with descriptions (100% coverage). The description adds a concrete usage hint for last_n ('Pass last_n=1 for the single most recent mutation'), which goes beyond the schema's generic 'Number of recent entries to return (default 20)' and helps the agent apply the parameter correctly.

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 'Read the audit trail of all memory mutations,' identifying the specific verb (read) and resource. It also explicitly contrasts with semantic_recall, distinguishing its scope and purpose from a key sibling tool.

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

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

It gives explicit guidance to 'Use this — not semantic_recall —' for recency questions, provides concrete example queries, and closes with a clear differentiation: semantic_recall for topic search, audit_log for time-ordered history, integrity checks, and debugging. This fully addresses when to use the tool 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?

Goes well beyond the readOnlyHint annotation by disclosing deterministic behavior, matching signal priority order, the explicit prohibition on guessing from cwd, return fields, and confidence-based decision flow. No contradictions 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?

Dense but well-organized; every sentence contributes actionable detail—purpose, determinism, orchestration, and thresholds—with no filler or 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?

Compensates for the lack of an output schema by describing return fields, confidence thresholds, and required follow-up actions. For a read-only resolution tool, it is fully 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 covers all parameters with rich descriptions (100% coverage), so baseline is 3. The description adds signal-priority semantics (explicit vs weak) but does not substantially extend per-parameter details beyond the schema. This extra context justifies a 4.

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 resolves which entity the current work belongs to with a derived confidence. It also distinguishes itself from sibling tools by referencing focus_get/decision_check and specifying when to call 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?

Explicitly instructs to call before focus_get/decision_check when the target entity is not already known, and provides confidence thresholds for when to proceed silently, when to communicate uncertainty, and when to ask. This is concrete when-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 readOnlyHint=true, but the description goes far beyond that by explaining the return semantics, the meaning of 'review_triggered' as an opposite signal, and the nuanced case where a decision is both a conflict and a review trigger. This is rich behavioral disclosure that helps an agent act correctly on the result.

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 logically structured: state purpose, list return values, provide usage directive, then explain the subtle review_triggered behavior. Every sentence earns its place; no filler or redundant 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?

There is no output schema, so the description must explain return values and interpretation, which it does thoroughly. It covers the three statuses, the review_triggered list, how to handle conflicts, and the dual conflict/review-trigger case. This is complete for the tool's 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%, and both parameters ('entity_id' and 'proposed_action') already have clear descriptions in the schema. The tool description does not add parameter-specific detail beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description opens with a specific verb+resource: 'Check a proposed action against all active decisions.' It clearly states the returned statuses ('clear', 'caution', 'conflict') and the 'review_triggered' list, which distinguishes it from sibling tools like action_guard or memory_check. The purpose is unambiguous and specific.

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 BEFORE taking actions that might contradict prior decisions' and provides a clear conditional: 'If status is conflict, do NOT proceed without explicit user confirmation.' This gives strong when-to-use guidance, though it does not name alternative tools or state when not to use it beyond the conflict case.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context by explaining that logged decisions persist across sessions and that invalidate_if conditions turn a timestamped decision into a testable frame for future reasoning. This goes beyond the bare annotations without contradicting 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 concise, with three sentences that front-load the core purpose and then elaborate on required and optional inputs. Every sentence contributes meaning, and the structure is 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?

The description omits mention of several required fields like entity_id and decision, but the schema covers them. However, the inaccurate statement about alternatives being required is a significant gap that could mislead. The description does explain the purpose of assumptions and invalidate_if, but the misinformation lowers 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 high (82%), so baseline is 3. However, the description inaccurately states that 'alternatives' is needed when the schema marks it as optional (required array only includes entity_id, decision, why, proof_action, review_date). This misinformation actively misleads an agent about required parameters, subtracting value rather than adding it.

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

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

The description uses a specific verb 'Log' and resource 'strategic decision', clearly indicating the tool records persistent decisions. It states the persistence aspect, which distinguishes it from siblings like decision_review and decision_check that likely read or analyze decisions.

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 clear context for use: logging strategic decisions for persistence across sessions. It also gives guidance on required elements ('reason, alternatives, and a proof action') and optional ones (assumptions, invalidate_if), though it does not explicitly name alternative tools or state when not to use this tool.

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

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

The annotations indicate this is a mutating tool (readOnlyHint=false) but not destructive (destructiveHint=false). The description goes beyond this by clarifying that content is not mutated, only metadata, and that adding evidence appends a dated entry without overwriting. It also discloses a side effect: transitioning away from 'superseded' automatically clears the dangling superseded_by pointer. This provides useful behavioral context beyond the annotations, though it does not cover all possible edge cases (e.g., invalid decision_id).

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

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

The description is concise and well-structured. It opens with a clear verb and resource, lists the three main actions, and then provides two critical usage notes in separate sentences. Every sentence earns its place, and there is no fluff or repetition of schema content that is already obvious. The length is appropriate for the tool's complexity.

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 moderate complexity (4 parameters, one required, no output schema), the description is mostly complete. It explains the core functions, the distinction from decision_log, and the special superseded status rule. However, it does not mention what the tool returns (e.g., success confirmation or updated decision object) or how errors are handled (e.g., nonexistent decision_id). Since there is no output schema, a brief note on the return value would have been helpful, but the tool remains usable with the information provided.

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 describes all four parameters with 100% coverage, so the schema already provides the heavy lifting. The description reinforces the meaning of 'add_evidence' (append, never overwrites) but does not add substantial new meaning beyond the schema. The 'status' parameter's special handling is also documented in the schema, so the description's reference to it is redundant but consistent. As per the baseline rule for high schema coverage, a 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's purpose: refreshing metadata for an existing decision, listing specific actions (bump review_date, append evidence, change status). It distinguishes itself from related tools like decision_log by explicitly noting it does not mutate decision content, and for content changes, a new decision should be logged. The verb 'Refresh' plus resource 'decision metadata' is 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 gives explicit usage direction: 'Use INSTEAD of editing decisions.json directly' and 'for content changes, log a new decision via decision_log.' It also provides a conditional rule for the 'superseded' status, stating this should only be used when a replacement decision exists and advising to prefer decision_log with the 'supersedes' parameter. This is clear when-to-use and when-not-to-use guidance with specific 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?

The description reinforces readOnlyHint with explicit 'READ-ONLY' and explains it mutates nothing, proposes and cites reasons, and auto-detects duplicate stubs. It also describes conditional behavior with root_path, adding value beyond the annotation.

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 sentences, front-loaded with usage triggers, no fluff. Dense but organized, 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?

For a read-only review tool with no output schema, the description covers purpose, usage, safety, and conditional behavior. Missing output format is acceptable since no output schema exists and the description gives adequate context.

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 covers all 4 parameters with detailed descriptions (100% coverage). The description doesn't add significant new parameter semantics beyond what schema provides; it references root_path but schema already explains it in 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's function: a review-debt inbox that buckets overdue decisions into still_true / changed / archive / needs_evidence with recommended actions. It uses a specific verb ('Call this...') and distinguishes from siblings by focusing on review/analysis rather than mutation or checking.

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 it ('before making new decisions, at session end, or when the user asks if a decision is still valid or what's overdue') and directs follow-up actions via decision_refresh / decision_log, providing clear workflow context and 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 declare readOnlyHint=true, and the description adds the returned data shape (status, momentum, blockers, etc.) and the ability to fetch all entities. This goes beyond the annotation but doesn't cover potential edge cases like staleness or error behavior, but for a read tool the bar is lower.

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 focused sentences: usage instruction, core functionality, and an exclusion. Front-loaded and every sentence earns its place with 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?

The tool is simple (one optional param, no output schema). The description fully covers when to use it, what it returns, and how to invoke it (first, before grep), making it complete within its simplicity.

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 entity_id is fully described in the schema ('Entity ID to read. Omit for all entities.'). The description repeats this concept ('one or all tracked entities') without adding new syntax or format details, 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?

Clearly states the tool returns operational state for entities, with specific fields (status, momentum, blockers, etc.). The verb 'Returns' and resource scope ('one or all tracked entities') distinguish it from update tools and code-reading alternatives.

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

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

Explicitly instructs to call this tool FIRST for state questions, before reading code or git history. Provides an exclusion ('Do not grep files') and implicit alternative (code/git reading), making usage unambiguous.

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, so the write nature is known. The description adds valuable behavioral context: it upserts ('Creates the entity if it doesn't exist'), stores structured operational state, and explains the context_hint rejection mechanism that prevents cross-project contamination. This goes 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 front-loaded with 'Use this' and consists of five sentences, each earning its place: purpose, trigger phrases, upsert behavior, stored fields, and timing. No redundancy or filler.

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

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

Given the tool's complexity (3 params, nested updates object, no output schema), the description covers purpose, triggers, timing, and an important safety behavior (context_hint validation). It does not describe return values or error handling in general, but the core usage context is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with each parameter already documented. The description lists field categories (status, momentum, blockers, next move, decisions) which loosely maps to schema properties but adds no new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's verb ('add or update') and resource ('project, product, or business idea in Brain OS'), and distinguishes it from built-in memory. It also provides trigger phrases ('add project X', 'track X') and notes the upsert behavior, making the purpose unambiguous and differentiated.

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 gives explicit when-to-use triggers: user phrases and timing ('after work is done, a decision is made, a blocker changes, or momentum shifts'). It mentions 'not built-in memory' as an alternative but does not explicitly exclude other sibling tools like entity_read or plan_add, so it falls short of full when/where-not 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 readOnlyHint annotation already declares the tool is read-only. The description adds valuable context about the Brain OS data source, the follow_through_alerts behavior (entities with stale next_move), and how they should be treated as first-class prompts. This goes beyond what the annotation alone conveys.

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 efficiently front-loaded with the critical 'CALL THIS FIRST' instruction, followed by concise but rich context about data source, recommendation criteria, and alert handling. Every sentence earns its place with no filler.

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

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

For a read-only tool with no output schema, the description covers the core purpose, trigger conditions, and a notable behavior (follow_through_alerts). It does not detail the exact response format, but given the full parameter schema and clear output description ('prioritized recommendations'), this is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of entity_id ('Pass entity_id to scope focus to a single project') slightly reinforces the schema but adds little new meaning. Other parameters (constraints, max_results, suppress_default_guidance) are not elaborated 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 states the tool returns prioritized recommendations based on specific criteria (urgency, momentum, leverage, staleness, dependencies) and distinguishes it from reading code/files/git history. It also explicitly positions it as the first tool to call for focus-related queries.

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 trigger phrases ('asks what to focus on, what to work on...') and clear precedence guidance ('CALL THIS FIRST... before reading any code, files, or git history'). It also explains when to pass entity_id, making usage unambiguous.

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 what the tool flags (stale data, contradictions, overdue reviews, etc.) and what it returns (classification + recommended actions), adding meaningful behavioral context beyond the readOnlyHint annotation. It's consistent with read-only behavior and gives the agent a clear picture of what to expect.

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

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

Four sentences, front-loaded with the core purpose, then enumerating flags and returned values, ending with actionable usage guidance. Every sentence contributes information with no filler.

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

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

With no output schema, the description compensates by naming the return categories (strong/weak/noise/dangerous) and cleanup actions. The optional parameter scope is covered by the schema. The tool is relatively simple, and the context is sufficiently complete, though more detail on cleanup actions could be added.

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 (entity_id) is fully documented in the schema with 'Check one entity, or omit for full memory audit', so schema coverage is 100%. The description doesn't add parameter-specific meaning beyond this, maintaining the baseline 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 uses a specific verb ('Assess') with a clear resource ('quality and reliability of current memory state') and enumerates distinct outputs (signal classification, cleanup actions). It distinguishes itself from siblings by focusing on trustworthiness of memory rather than reads, writes, or decision checks.

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 final sentence gives explicit guidance: 'Call this before acting on memory to know what to trust.' This provides a clear usage context, though it doesn't name alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds context about updating all touched entities and logging/recording, but does not elaborate on side effects like whether updates are irreversible or how momentum_changes are applied. It does not contradict annotations, and the extra end-of-session framing is useful.

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 two sentences, front-loads the core verb ('End-of-session commit'), and packs all key behaviors without padding. Every word 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?

For a commit tool with 5 parameters and no output schema, the description covers the trigger and main effects but omits momentum_changes and does not explain the destructive implications beyond the annotation. It is adequate but missing important operational detail.

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 only 40%, but the description partially compensates by mapping 'logs decisions' to decisions_made and 'records patterns' to patterns_noticed. It does not mention momentum_changes, which remains undocumented both in schema and description, leaving a gap for that parameter.

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

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

The description opens with 'End-of-session commit', a specific verb+resource pair, and enumerates concrete actions: 'Updates all touched entities, logs decisions, records patterns'. This clearly distinguishes it from sibling tools like decision_log, entity_update, and pattern_detect by positioning it as a consolidated commit operation.

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

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

The description explicitly instructs 'Call before ending any work session', providing a clear trigger context. It does not mention alternatives or exclusions, but the usage condition is direct and actionable.

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, so the safety profile is covered. The description adds that the tool analyzes 'all tracked entities' and returns 'detected signals with entity context,' which is useful but does not detail output format, pagination, or potential performance implications. This is similar to the reference example where annotations carry the main 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?

The description is two sentences, front-loaded with the most important usage trigger, and ends with a concise statement of behavior and output. Every word earns its place with no redundancy or filler.

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

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

Given the low complexity (one optional parameter, no output schema), the description is complete enough for an agent to select and invoke the tool. It covers when to use, what it does, and what it returns. The schema covers parameter details, and annotations cover safety.

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

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

The schema provides 100% coverage for the single 'scope' parameter, including its options ('recent', 'deep', or a specific theme). The description does not add further parameter-specific meaning, which is acceptable given the high schema coverage. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it analyzes patterns across tracked entities and returns detected signals with entity context. It also explicitly lists trigger conditions (patterns, recurring blockers, theme convergence, avoidance signals), distinguishing it from generic file grepping or log reading.

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 opens with explicit 'Call this when...' guidance listing specific user intents that should trigger this tool, and explicitly says to use it 'instead of grepping git logs or reading files to find trends.' This clearly communicates when to use it versus the alternative manual approaches.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, consistent with the mutation described. The description adds value by explaining insertion positions ('at the end or immediately after the current active step'), offering behavioral detail 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?

Two sentences deliver purpose, usage context, and positional behavior without redundancy. Every phrase earns its place, and the structure is front-loaded with the 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?

With simple 3-parameter schema, helpful annotations, and clear usage context, the description is nearly complete. It doesn't mention return values or side effects, but for a low-complexity mutation tool with strong schema support, this is a minor gap rather than a critical omission.

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 meaning beyond the schema by clarifying the 'after_current' position means 'immediately after the current active step', which is not fully explicit in the schema's enum description.

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

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

The description clearly states the tool's action: 'Add steps to an existing plan' with the specific resource (plan) and target (steps). It also distinguishes from siblings by noting mid-plan usage and positioning options, which differentiates it from plan_set and plan_advance.

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 a clear usage context: 'Use when new work is discovered mid-plan.' It implies a specific scenario but does not explicitly name alternatives or say when not to use, though the sibling list and context make the distinction intuitive.

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

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

The description discloses multiple behavioral traits beyond the annotations, including the mandatory evidence/reason requirements, automatic promotion of the next pending step, updates to next_move, and the 'cannot skip without reason' constraint. This gives a comprehensive view of the tool's side effects and validation rules.

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, front-loaded sentences. Every sentence contributes meaningful information: one states the core action and prerequisites, the other explains the automatic behavior and enforcement. There is no redundancy or filler.

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

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

For a mutation tool with no output schema, this description sufficiently covers purpose, conditions, and side effects. It handles the main use cases and explains the state transition. Minor gaps exist, such as behavior when there is no pending next step, but these are not critical for primary usage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the conditional dependency between action and evidence/reason, which is not fully captured in the schema. This helps the agent understand which fields are required in which scenarios.

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 function: 'Complete or skip the current plan step.' This specificity distinguishes it from sibling tools like plan_add (which adds steps) and plan_read (which reads plans). The verb-resource pairing is precise.

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 clear context for when to use 'complete' vs 'skip' by requiring evidence or reason respectively. It also explains the automatic promotion of the next step and the continuity enforcement. While it doesn't explicitly name alternative tools, the guidance is sufficient to infer appropriate usage.

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, so the safety profile is known. The description adds valuable behavioral detail about return content (all steps, status, active step, overall progress), which is especially important since no output schema exists.

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

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

Two concise sentences with no filler. The core action and its scope are front-loaded in the first sentence, and the second sentence enumerates the output contents efficiently.

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

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

For a read-only, single-parameter tool with no output schema, the description fully covers what the tool does and what it returns. There are no missing prerequisites or side effects to disclose given the readOnly hint.

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 entity_id is fully described in the schema with a clear description. The tool description does not add extra semantics, but none are needed for such an obvious parameter. Schema coverage is 100%, 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?

Description uses a specific verb 'Read' with resource 'current plan for an entity', and lists what is shown (steps, status, active step, progress). This clearly distinguishes it from sibling plan mutation tools like plan_set or plan_advance.

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 read-only purpose is clearly stated, making it obvious when to use this tool. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it for reading a plan.

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

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

The description discloses key behavioral traits beyond annotations: 'Replaces any existing plan' (destructive behavior) and 'Step 1 becomes the active next_move' (activation semantics). These add value above the destructiveHint annotation, which only flags destructiveness generically.

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

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

Four short sentences, each carrying essential information: purpose, replacement behavior, activation rule, and usage guideline. No fluff or repetition. Exceptionally well-structured for quick agent comprehension.

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 simplicity of the tool (2 parameters, no output schema), the description covers all necessary aspects: what it does, when to use it, how it affects existing state, and what constitutes valid input. The addition of a quality guideline for steps (concrete, completable) makes it fully self-contained 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?

Schema coverage is 100% and already describes steps as 'Ordered list of concrete steps. First step becomes active immediately.' The description adds 'Each step should be a concrete, completable action,' which is a slight refinement but largely redundant with the schema. No significant new meaning is provided.

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 'Set an ordered plan for an entity' and explicitly notes it 'Replaces any existing plan', which distinguishes it from sibling tools like plan_add. The verb+resource+scope is specific and actionable.

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 usage context: 'Use when committing to a sequence of work — not for brainstorming.' This gives a clear when-to-use signal and an exclusion. It does not name alternative tools explicitly, but the context implies this is for finalizing a plan rather than exploring ideas.

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

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

Beyond the readOnlyHint annotation, the description adds that it 'Mutates nothing and does no inference: it returns ALL candidate signals,' clarifying the tool's non-destructive, non-interpretive behavior. It also details the output format ('surfaced as exact lines'), giving a clear behavioral contract.

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 yet information-dense. Each sentence earns its place: purpose, output content, usage timing, non-mutation guarantee, and sibling distinction. It is front-loaded with the core function and avoids 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?

Despite having no output schema, the description explains what the tool returns (evidence categories, exact lines) and the scope of files scanned. Combined with usage timing and behavioral guarantees, it fully equips an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no parameter-specific guidance beyond what the schema already states; it merely implies that root_path is the target repo. Since the schema fully documents both parameters, the description needs no further elaboration.

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

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

The description uses a specific verb ('scan') and resource ('a repo's native operating state'), enumerates exact file patterns, and explicitly distinguishes itself from sibling context_resolve by stating 'This is NOT context_resolve.' This makes the tool's purpose unmistakable and separate from alternatives.

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

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

Provides explicit sequencing: 'Call AFTER context_resolve and BEFORE building a focus answer,' and an explicit exclusion: 'do not use it to pick which project you're in.' This gives clear when-to-use and when-not-to-use guidance, superior to most tool descriptions.

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

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

The description discloses behavior beyond the readOnlyHint annotation: it mentions a pre-filter that returns low/skipped for safe actions, then applies signal detection across five risk categories, and lists the return fields (risk_level, boundary_crossed, reversibility, risk_reasons). This provides a clear picture of the tool's internal processing.

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

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

The description is four sentences, each earning its place: purpose, process, usage trigger, and output/handoff. It is front-loaded with the core purpose and contains no redundant 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?

For a tool with 7 parameters, a nested object, and no output schema, the description covers purpose, usage triggers, process, return fields, and the next step to action_guard. It does not explicitly connect parameters like package_info or diff to the detection logic, but the schema covers those details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description references 'proposed action' and target categories, but does not add parameter-specific details beyond what the schema already provides (e.g., how diff or package_info are used).

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 'Assess the risk of a proposed action before executing it' with a specific verb and resource. It goes on to list the detection categories and the explicit trigger set, distinguishing it from sibling tools like action_guard.

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

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

It provides explicit when-to-use guidance: 'Call this BEFORE any action in the trigger set: publish, push, force-push, git tag, deploy...' and instructs the next step: 'Pass the result to action_guard to get a policy decision.' This clearly positions the tool relative to 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, so the read-only safety is covered. The description adds meaningful behavioral context beyond that: it explains the semantic search mechanism and the fact that it matches by description rather than exact name. This goes beyond the minimal annotation baseline, though it doesn't disclose result format or failure 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 sentences, front-loaded with trigger conditions, followed by the core functionality and a usage directive. Every sentence earns its place with no redundancy or 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?

For a read-only search tool with well-described parameters and no output schema, the description provides complete selection and invocation context: it tells the agent when to use it, what it does, and how to order it relative to git log. No critical gaps for an agent to call it correctly.

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

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

Schema description coverage is 100%: query has an example, max_results and source_kind have clear descriptions. The tool description does not add parameter-specific meaning, so the baseline of 3 is appropriate per the rubric.

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: 'Searches memory by meaning using semantic similarity.' It also specifies concrete use cases (what changed last session, recent events, finding by description) and distinguishes from exact-name search and git log, differentiating it from sibling tools like entity_read.

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 triggers ('when the user asks what changed last session...') and a strong guideline: 'Use BEFORE reading git log or commit history for session-level context questions.' This clearly guides the agent on tool selection and ordering relative to 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 only say readOnlyHint=false, so the description carries the full burden of behavioral disclosure. It discloses that low-risk fields are applied immediately, high-risk changes are staged as unconfirmed records, a session_wrapped marker is always logged, and staged items are proposals not writes. This is consistent with readOnlyHint=false.

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

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

Four dense sentences, each earning its place: trigger/context, alternative, risk-tier behavior, logging, and a caution. The prose is front-loaded with 'Tier 2' and 'safety net' and contains no filler or redundant restatement.

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

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

For an 8-parameter, nested tool with only readOnlyHint=false and no output schema, this description covers purpose, trigger conditions, side-effect behavior, risk classification, and a critical caveat. It leaves no major gap in deciding whether and how to invoke 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%, so the baseline is 3, and the description reinforces the low-risk/high-risk split already present in schema descriptions. It adds crucial meaning by warning that pending_review is never effective immediately, clarifying how to set those fields, while not significantly altering parameter semantics beyond that.

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 frames wrap_auto as 'Tier 2 of auto-wrap' for persisting a session wrap without review, clearly naming the verb (persist, apply, stage) and resource (session wrap). It distinguishes itself from the interactive /wrap sibling by positioning it as a safety net, so an agent can tell what this tool uniquely does.

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 states when to use the tool ('context is about to be lost (compaction, session end) or the user declined to review') and explicitly says to use the normal interactive /wrap when the user is present and reviewing. This provides both inclusion and exclusion criteria, plus a clear warning against treating pending_review as immediately effective.

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 the description reinforces this with 'never mutates.' It adds valuable behavioral context beyond the annotation, such as returning unwrapped_count and recommend_wrap, and instructing the agent to offer a wrap rather than act silently. Minor gap: no mention of error conditions or edge cases, but the core behavior is fully 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?

The description is compact (~75 words) with front-loaded purpose and no fluff. Every sentence contributes either usage timing, return values, or an explicit behavioral rule. It is structured logically: what it does, when to use it, what it returns, and how to act on the result.

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 having no output schema, the description fully documents return values (unwrapped_count, projects touched, recommend_wrap) and the recommended action. It also covers usage timing and the read-only nature. Given the tool's relative simplicity and strong annotations, the description is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, with both threshold and session_id having clear descriptions in the schema. The tool description itself does not add extra parameter meaning beyond the schema, but it hints at the threshold's purpose via 'recommend_wrap' logic. Baseline 3 is appropriate because the schema carries the full load.

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 specific verb and resource: 'Check how much state-changing work has accumulated since the last wrap.' It clearly differentiates from the sibling tool 'wrap_auto' by positioning itself as the read-only check (Tier 1) that decides whether to offer a wrap, not perform 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?

Explicitly states when to call: 'when the user signals they are wrapping up or ending a session, or periodically during a long session.' It also provides a clear exclusion: 'do not auto-wrap silently from this tool,' and implies alternative behavior by mentioning the auto-wrap tier.

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