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

Annotations only show non-readonly and non-destructive. The description adds that it inserts phases, with high-priority at the front, implying additive behavior. More behavioral context than annotations alone provide.

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, front-loaded with main purpose, 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?

With 7 parameters and no output schema, description is brief. It explains insertion but not effects on existing phases, dependencies, or return value. Adequate but has 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 coverage is high (86%), so baseline 3. Description only adds meaning for 'priority' by noting insertion ordering; other params rely on 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 clearly states 'Add a new upcoming phase to the roadmap' with a specific verb and resource, and distinguishes from siblings like 'bulk_import_phases' by targeting single-phase addition.

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

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

Explicitly says when to call: 'when you identify new work during a session — gaps, refactors, follow-ups'. Also notes insertion ordering for high-priority phases, but does not exclude when not to use it (e.g., vs bulk import).

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 behavioral context beyond annotations: it mentions the reinforcement loop and auto-archive behavior. However, it references a parameter (do_not_revert) that is not present in the input schema, which is misleading. No mention of return value or side effects. Annotations only provide readOnlyHint and destructiveHint, so description adds some value but has a significant inconsistency.

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 (3 sentences) and front-loaded with the main purpose. It efficiently conveys key behavioral points. Minor improvement could be structuring parameter details, but overall it is well-sized.

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 is a simple mutation (2 parameters, no output schema), the description lacks details on return behavior and confirmation. It hints at state changes (resetting counters, archiving) but does not fully specify the effects. The missing do_not_revert parameter further reduces completeness. It is adequate but not comprehensive.

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 0%, and the description does not explain the meaning of the two parameters (skill_id and success). It implicitly references them but provides no details on expected format, values, or behavior. With only 2 parameters and no schema descriptions, this is a critical gap.

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: manually recording a skill outcome (success/failure). It specifies the verb 'record' and resource 'outcome for a skill', and distinguishes itself from sibling tools by noting it is a manual override to the automatic git-derived outcomes.

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 explains when to use the tool: as a manual override for the automatic outcome signal. It describes the reinforcement loop behavior (resetting consecutive_failures, auto-archiving at 5 failures) which helps the agent decide context. However, it does not explicitly exclude when not to use or compare with alternatives among siblings.

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 idempotency and the default value of 'status?='done'', adding to annotations (readOnlyHint=false, destructiveHint=false). It also specifies optional fields and a common use case, going beyond what annotations provide.

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, no wasted words. The first sentence gives the main purpose, the second outlines the item structure, and the third adds idempotency and usage context. Front-loaded and 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 the tool's complexity (array of nested objects) and no output schema, the description covers all necessary aspects: input structure, idempotency, and real-world usage scenario. It is sufficient for an AI agent to select and 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?

The description enriches the schema by detailing the structure of each phase item (number, name, status with default, optional fields), which is not present in the schema's minimal description. Schema coverage is 100%, but the description adds significant 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 action ('backfill multiple historical phases at once'), identifies the resource ('phases'), and distinguishes from sibling tools like 'add_phase' which likely handles single phase addition.

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 context: 'useful for adopting codevira on a project that already shipped N phases in git.' It implicitly excludes normal phase addition, but lacks an explicit 'when not to use' statement.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral nuance beyond that: the handling of negated restatements as conflicts rather than duplicates, the exact return status vocabulary, and the internal call from record_decision. This is exactly the kind of non-obvious logic an agent needs to predict tool 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 dense but every sentence earns its place: first the core purpose, then the critical negated-restatement nuance, then the return shape, then the call-timing guidance. There is no filler or redundancy, and the most important operational detail 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?

For a read-only, idempotent check tool with no output schema, the description is complete: it names the input concept, the return envelope, the edge-case behavior, and the relationship to record_decision. An agent has everything it needs to invoke the tool correctly and interpret the result at a practical level.

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

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

Schema description coverage is 100%, so the schema already fully documents decision_text and file_path, including file_path's preference for same-file hits. The description reinforces the meaning of decision_text by calling it a 'proposed decision' and relating it to record_decision, but it does not add new parameter-level detail 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 states a specific verb and resource: checking whether a proposed decision contradicts or duplicates existing decisions. It also names the concrete behavioral rule for negated restatements, which sharply distinguishes this from sibling tools like record_decision. The return statuses are listed, leaving no ambiguity about what the tool 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?

The description explicitly says to call this BEFORE record_decision, and even explains that record_decision internally runs the same check and surfaces _conflict_warning unless force=true. This gives the agent a clear procedural rule and a direct comparison to the alternative, so there is no guessing about when this tool 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 indicate readOnlyHint=false and destructiveHint=false. The description adds that key_decisions are recorded permanently and that backfill does not advance the queue, which clarifies write behavior and the safety check. It does not contradict annotations and provides useful context beyond the schema.

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 plus two bullet-like items) and front-loaded with the core action. Every sentence adds value: main action, safety requirement, special cases for backfill and git_ref. 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?

Given the tool's complexity (multiple modes, safety check) and lack of output schema, the description adequately covers the main use cases and parameters. However, it does not explain side effects on other system state (e.g., phase status transitions) beyond advancing the queue.

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 significant value by explaining the purpose of phase_number as a safety check, the backfill workflow (with required parameters), and the git_ref linking. This frames parameters in a functional context beyond their schema 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 explicitly states the tool's main action: 'Mark the current phase as complete and advance to the next upcoming phase.' It also mentions recording key decisions permanently and includes a safety check. This clearly distinguishes it from siblings like add_phase (creation) or defer_phase (postponement).

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 specific usage guidance: normal use requires phase_number to match the current phase, and it offers two alternative use cases (backfill for historical phases and linking git_ref). While it does not explicitly state when not to use, the clarity of the normal mode and backfill alternative implies appropriate contexts.

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, but the description does not elaborate on behavioral traits like what exactly happens to the phase, whether it is removed from the original list, or any side effects. The description adds minimal 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?

The description is two sentences: first states the action, second provides usage guidance. Every word earns its place, and it is front-loaded with the key 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 simple 2-param tool with no output schema, the description covers the action and usage adequately. However, missing parameter details and return value make it slightly incomplete.

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 50% (only 'reason' has a description). The tool description does not add any parameter details; for example, 'phase_number' lacks any explanation. The description fails to compensate for the missing schema documentation.

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 'Move' and specifies the resource 'upcoming phase to the deferred list', clearly distinguishing it from siblings like complete_phase or add_phase.

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 this tool: 'Use when priorities shift or a phase depends on unavailable work.' It does not mention when not to use or alternative tools, but the usage 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds 'never raises on unknown IDs' and return structure, exceeding annotation coverage.

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, front-loaded with purpose, 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?

With one parameter, strong annotations, and description detailing return structure, no missing critical 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?

Schema coverage 100% with clear parameter description. Description adds minimal extra ('pass the IDs you care about'). 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?

Description clearly states verb 'fetch', resource 'FULL decision records', and context 'expand path for summary-first search'. It distinguishes from sibling tools like list_decisions and search_decimals.

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 to use after scanning compact rows via search_decisions/list_decisions defaults. Implies workflow but does not list alternatives for 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 indicate readOnly, idempotent, non-destructive. Description adds behavioral details: default truncation (~500 tokens), ordering by most recent first, and option for untruncated text.

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 succinct sentences. First sentence states purpose and defaults. Second explains the full option and ordering. No waste, 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?

Handles all requirements for a read-only history tool. No output schema, but description covers inputs and behavior. Slightly lacking in describing return format, but inferred.

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 3 params with descriptions (100% coverage). Description adds value beyond schema: clarifies default limit (5) and truncation behavior (~500 tokens) for the full 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?

Clear verb+resource+scope: 'Get recent decisions touching a file.' Distinguishes from siblings like list_decisions and search_decisions by specifying file-specific history.

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 defaults (5 decisions, truncated context) and optional parameters (full=true, limit). Implicitly guides use for file-specific history, but lacks explicit alternatives 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 confirm read-only, idempotent, non-destructive behavior. The description adds context on default output (10 files + counts, ~400 tokens) and the summary_only option (~80 tokens), which is beyond annotation coverage.

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 main purpose. Every sentence adds value: purpose, output details, and a directive. 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?

Despite no output schema, the description fully explains return values (files and counts, or summary counts). It covers default behavior, token sizes, and a use case. Nothing essential is missing.

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

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

Input schema has 100% coverage with descriptions. The description adds meaning by linking default behavior to the 'limit' parameter (default 10) and explaining 'summary_only' in practical terms. Slight improvement over 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 clearly specifies the verb 'Get' and resource 'blast radius for a file', distinguishing it from sibling tools like get_node or get_history. It explicitly ties to the pre-modification 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?

The description states 'ALWAYS call before modifying any file', providing strong usage context. It also mentions the summary_only option for gate checks. However, it does not explicitly list scenarios where the tool should not be used or 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 and idempotentHint, but the description adds beyond that: clarifies default summary behavior, lists the fields returned, mentions token count (~100), and explains the effect of full=true. This is valuable additional context for an AI agent.

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 three sentences, each serving a distinct purpose: stating the action, describing default behavior, and prescribing when to use. No wasted words, and 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?

Given no output schema, the description adequately explains the return value for the default case and hints at the full output. It also provides a usage recommendation. For a simple retrieval tool, this is 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 descriptions for both parameters. The description adds context by explaining what the boolean 'full' does and that the default is summary-only, which helps the agent understand the trade-off between detail and token usage.

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 ('Get') and resource ('context graph node for a file'), clearly differentiating it from siblings like get_code or get_impact by focusing on the context node rather than source code or impact analysis.

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 'Call this INSTEAD of reading the source file', providing a clear when-to-use directive. However, it does not list alternative tools for other contexts, leaving some room for interpretation.

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. Description adds that it returns 'full details' and works for any phase status, providing additional useful context 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?

Single sentence of 12 words, front-loaded with the core action and resource. No extraneous information; each word 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?

Given the simple parameter set and annotations that cover safety, the description fully conveys the tool's purpose and scope. No output schema exists, so no need to describe return values.

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 adequately describes the phase_number parameter with examples. The tool description does not add semantic value beyond the schema, so baseline 3 applies.

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

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

Description clearly states verb 'Get' and resource 'phase', specifying scope 'by number' and qualifying that it works for 'completed, current, or upcoming' phases. This differentiates it from sibling tools like add_phase or complete_phase.

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?

No guidance on when to use this tool versus alternatives. Sibling tools like get_code, get_node, or get_playbook are present but no differentiation is provided.

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 confirm read-only, idempotent, and non-destructive behavior. The description adds that only 2-3 rule files are returned (not all), which is specific behavioral context 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 sentences, front-loaded with purpose, and no redundant information. Every sentence 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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, return value nature, and valid inputs. It lacks details on rule file format but is sufficient for selection.

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 parameter description. The description adds the list of valid task types, which is not present as an enum in the schema, providing extra semantic clarity 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 clearly states the tool retrieves curated architectural rules for a specific task type, specifying the output is only 2-3 relevant files and listing valid task types. This distinguishes it from other 'get' siblings by resource and 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 implies usage for obtaining architectural rules for a task type but does not explicitly state when to use this tool over alternatives or provide any exclusion criteria. Usage context is implied but not detailed.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the returned state fields and the intended invocation time, 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?

Two sentences, front-loaded with purpose, followed by usage advice. No wasted words, perfectly concise for the tool's simplicity.

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 parameters, rich annotations, and low complexity, the description fully covers what an agent needs to know: what the tool returns and when to call it.

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?

No parameters exist, so the description need not provide parameter details. Per guidelines, 0 params yields a baseline of 4, and the description is satisfactory.

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 'Get' and the resource 'current project state', listing specific fields (phase number, name, status, next action, upcoming phases). This distinguishes it from siblings like 'get_phase' which likely retrieves a single phase.

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 at the START of every session', providing a clear usage context. It does not explicitly mention when not to use or alternatives, but the directive is strong and suffices for a read-only snapshot 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?

Beyond the readOnlyHint/idempotentHint annotations, the description reveals important behaviors: recent_decisions ranking by "recency x outcome-confidence," hidden reverted/outdated decisions, a needs_review flag with review_hint values, and cross-tool support. This materially shapes how an agent interprets the response and what follow-up actions may be needed.

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 front-loads the core purpose in its first sentence and then elaborates on ranking, filtering, and review semantics that directly affect how the output should be used. It is somewhat dense with examples like the "decision git watched survive" parenthetical, but every sentence contributes meaningful information.

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

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

With no output schema, the description carries the burden of explaining what the agent will receive, and it does so thoroughly: roadmap phase, decisions with confidence, preferences, active rules, ranking logic, hidden entries, and review hints. Combined with zero parameters and safe read annotations, this is complete enough for correct invocation and interpretation.

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 takes zero parameters and the schema reflects that with 100% coverage, so there is no parameter documentation burden on the description. The baseline for a zero-parameter tool is 4, and the description does not need to add parameter-level 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 opens with a specific framing, "Single 'catch me up' call for cross-tool continuity," and then lists the concrete resources it returns: current roadmap phase, recent decisions, learned preferences, and active rules. This clearly distinguishes it from narrower sibling tools like list_decisions or get_roadmap by describing it as the all-in-one session-restore call.

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 an explicit usage directive: "Call this at the START of every session instead of multiple separate calls." This tells the agent both when to invoke it and that it should be preferred over assembling the same information through multiple sibling calls, which is strong usage 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?

Goes well beyond annotations by revealing scoring formula, recency decay, and score_breakdown return, providing deep insights into tool 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 dense sentences with front-loaded version and purpose, no filler, every sentence adds unique 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?

Covers scoring, filtering, and debug output adequately, but could mention pagination or empty result behavior. With no output schema, this is reasonably 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?

Adds context for query (example) and file_path (filtering behavior), though top_k lacks additional description. Schema coverage is 67%, and description compensates partially.

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 clearly states it's a composite-ranked search over active skills with explicit scoring formula, distinguishing it from sibling tools like list_skills and search_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?

Guidance is provided on using file_path for filtering, but no explicit when-not-to-use or comparison to alternatives is given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: output capped at ~150 tokens, entries truncated at 120 characters, and returns a specific structure. This 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?

Two concise sentences that are front-loaded with version and key purpose. Every word earns its place, 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?

For a simple tool with one parameter and no output schema, the description provides sufficient context including return type, constraints, and intended use (ReAct-loop injection). It competently covers the essentials.

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 a clear description of top_k. The description does not add additional semantics beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states it renders top working-memory entries in compact markdown for ReAct-loop injection, specifying return structure and output limits. While it doesn't explicitly differentiate from siblings like working_get, the purpose is specific enough.

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?

No explicit guidance on when to use this tool versus alternatives like working_get or other queries. The description implies it's for injection into the ReAct loop, but does not provide when-not-to-use or comparisons.

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 read-only and idempotent behavior. The description adds significant behavioral detail: default compact rows, full mode, summary_only precedence, expand function, and filters (protected_only, include_superseded). This exceeds the minimal disclosure from 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 dense with version numbers and internal references (v2.1.2 Item 11, 26, 27) that may clutter for an agent. It contains a verbatim quote and acronym (E1). While informative, it could be more streamlined for quick parsing.

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 partially compensates by describing compact vs full rows and expand. However, it lacks explicit output field listing beyond 'one-line decision summary + key fields'. The mention of parity with search_decisions aids context, but return structure could be clearer.

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 9 parameters with descriptions. The description adds context: default limit (20, max 200), expand mechanism, interaction between full and summary_only, and version-specific filter tags. This adds meaning beyond raw schema, though some parameter behavior (e.g., since_date format) is already 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 tool's purpose: 'enumerate decisions with filters'. It lists specific filter parameters and explains the gap it closes ('can't list what it remembers'). The inclusion of default vs full modes and the expand function further clarifies its role.

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 does not explicitly guide when to use this tool versus alternatives like search_decisions. It mentions 'parity with search_decisions' for summary_only, but does not provide direct comparison or exclusion criteria. The default behavior is described, but usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating safety. The description adds behavioral detail on how status and tags filters work, which is beyond the annotations. It does not mention pagination or sorting, but given the annotations cover the safety profile, this is acceptable.

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 clear, concise sentences. The first sentence states the primary purpose, and the second elaborates on filtering behavior. No extraneous information is included, making it efficient and 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?

The description adequately explains core filtering behavior for a list tool but lacks details on the 'limit' and 'source' parameters. There is no output schema, so the agent has no information about the response format. For a tool with 4 parameters and no output schema, the description is somewhat incomplete.

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 25% (only status has a description). The description adds meaning for status and tags, explaining their behavior. However, it omits any detail about the 'limit' and 'source' parameters, which remain undocumented. Thus, the description partially compensates for low schema coverage but not completely.

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 it is a filtered list of skills, mentioning the status and tags filter behavior. It distinguishes its purpose from single-skill retrieval tools like get_skill, though it does not explicitly differentiate from other list tools like list_decisions or list_tags.

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 specific guidance on when to use different status values (active vs all vs filtered) and explains that tags use set intersection. However, it does not provide context on when to use this tool versus sibling tools like search_decisions or get_skill, nor does it mention prerequisites or 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds that tool returns decision counts, which is useful context beyond annotations. 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?

Single sentence with an explanatory phrase. No fluff, every word earns its place. Front-loaded with 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 zero-parameter tool with no output schema, the description fully explains what it does and what it returns (tags with decision counts). Complements the sparse structured fields.

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 has no parameters (coverage 100%). Description adds meaning by explaining what tags are and that counts are included, which enriches the empty 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?

Description clearly states verb 'enumerate all tags' and resource, specifies 'with decision counts', and provides a usage context question. Easily distinguishes from siblings like list_decisions or list_skills.

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 'useful for discovery — what categories of decisions do we track?' which guides when to use. Lacks explicit when-not-to-use or alternatives, but contextually clear among siblings.

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 and destructiveHint=false. The description adds significant context: the tool writes one amendment to .codevira/decisions.jsonl, audit is preserved, it is reversible via set_decision_flag(is_outdated=false), and it stops the decision from surfacing in list/search tools. This goes well beyond what annotations provide.

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 three sentences, front-loaded with version and purpose, then covers behavior, usage, and reversibility. No superfluous words; every sentence 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?

Given the simple tool (3 parameters, no output schema), the description covers behavior, side effects, alternatives, and reversibility. It lacks return value details but that's acceptable without an output schema. Slightly more about error states could improve, but overall 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 coverage is 100% and already describes each parameter. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('tombstone' / 'mark as outdated') and clearly identifies the resource ('a decision'). It distinguishes from the sibling tool 'supersede_decision' by noting when to use each, and lists which tools are affected (get_session_context, search_decisions, list_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?

Explicitly states when to use: 'when a decision is simply no longer true and has NO successor'. Also specifies when not to use and provides an alternative: 'for a replacement, use supersede_decision to preserve lineage'. Mentions reversibility via set_decision_flag.

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. The description adds behavioral context about what the tool returns (specific fields and protection/supersession metadata), which goes beyond the annotations. 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 very concise, consisting of two sentences that front-load the key information. Every sentence adds value with 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?

For a simple read tool with one parameter, the description is mostly adequate but lacks explanation of the parameter and output format. Given the presence of annotations, it meets a minimum viable level.

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 has one required parameter with 0% description coverage. The tool description provides no additional meaning for the parameter 'decision_id' beyond its name, failing to compensate for the lack of schema documentation.

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 'Return' and the resource 'M1 origin block', and specifies the contained fields and metadata. It is specific enough, though it does not explicitly differentiate from sibling tools like 'get_node' or 'get_history'.

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 notes that the tool is 'always available regardless of the handshake flag', implying a usage condition, but it does not explicitly state when to use this tool over alternatives or provide exclusions.

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 (readOnlyHint=false, destructiveHint=false) indicate the tool modifies data but is not destructive. The description adds important behavioral context: it refuses if the target file exists unless force=True, and it makes the result discoverable via get_playbook. This goes beyond the annotation signals, providing concrete failure conditions and side effects.

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 covering the main action and two key behaviors (refusal condition and discoverability). It includes a version prefix ('v3.1.0 M3') that is unnecessary and adds clutter, but the core information is front-loaded. The structure is logical and efficient, though trimming the version would improve conciseness.

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 has 4 parameters, no output schema, and sparse annotations. The description explains the primary input (skill_id, task_type) through the file path, and mentions the force parameter. It also notes the post-promotion discoverability. However, it does not specify what the tool returns (e.g., success message, file path, or error), nor does it address prerequisites like the skill having a procedure. Some gaps remain for a complete understanding.

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 50% (task_type and name have descriptions). The description adds meaning for 'force' (clobber protection) and indirectly for 'task_type' (as directory). However, 'skill_id' is not described in either schema or description (though its purpose is inferable from the tool name). The description does not detail the 'name' parameter's use beyond what the schema states. Overall, it adds moderate value but does not fully compensate for missing parameter 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 clearly states the verb 'write' and the specific resource ('skill's procedure as a playbook markdown file'), with a concrete file path pattern and the resulting discoverability. It distinguishes from siblings like 'get_playbook' (retrieval) and 'record_skill' (different action). The version prefix is unnecessary but does not obscure the 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?

The description provides limited usage guidance: it notes that the tool refuses on existing files unless force=True, preventing accidental overwrites. However, it does not explicitly compare to alternatives or state when to use this versus other tools like 'record_skill' or 'update_playbook' (if such existed). The context is implied but not spelled out.

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, which clearly indicate the tool is safe and non-destructive. The description adds no behavioral context beyond the annotations, but does not contradict them. Since annotations carry the transparency burden, a score of 3 is appropriate.

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 sentences with no wasted words. The first sentence states the core purpose, and the second provides a concrete usage example. It is well front-loaded and 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?

For a read-only query tool with three parameters fully described in the schema and no output schema, the description provides adequate context. It explains the functionality and gives a practical hint. However, it does not describe the return format, which could be useful for an agent. Still, it is mostly 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% with all three parameters described. The description adds a helpful hint about using query_type='symbols' to list all functions, but otherwise adds little beyond the schema. Baseline 3 is correct given high schema coverage.

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 queries a function-level call graph for callers, callees, tests, dependents, or symbols. It uses specific verbs (Query, Find) and identifies a specific resource (function-level call graph). Among sibling tools, none appear to offer similar call graph functionality, so it is well-distinguished.

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 call graph queries but does not explicitly state when to use this tool versus alternatives like get_code or get_signature. It provides query type options but no when-not or exclusions. This leaves some ambiguity for an agent selecting among siblings.

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 non-read-only and non-destructive, so the description carries the full behavioral burden. It discloses the precise side effect: appending a single 'reaffirmed_at' amendment to .codevira/decisions.jsonl and resetting the clock. It also clarifies important nuances: the lock never auto-flips, the flag is advisory, and soft-expiry can be configured via an environment variable.

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 dense but efficient: every sentence contributes either the core action, the trigger condition, the configuration, the side effect, or an alternative. The action is front-loaded, and no sentence is 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 one simple parameter and no output schema, the description fully equips an agent to invoke the tool correctly. It covers the decision trigger, the expiry mechanism, the environment override, the exact file mutation, and the relevant sibling tools — more than enough for correct selection and 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?

The input schema already fully documents the single decision_id parameter with an example, so the baseline is 3. The description adds selection semantics beyond the schema: the decision should be soft-expired and still load-bearing, which helps the agent choose the right id. It does not add syntax or format details, but the schema is already sufficient for 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 states a specific verb ('refresh') on a specific resource ('a do_not_revert decision's soft-expire clock'), making the action unambiguous. It also distinguishes itself from sibling tools by explicitly naming supersede_decision and set_decision_flag as the tools for different operations.

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 when to call the tool: 'on a soft-expired decision that is still load-bearing.' It also gives clear alternatives with conditions: 'For semantic rewrites use supersede_decision; for flipping the flag use set_decision_flag.' The soft-expiry trigger is made observable via dnr_soft_expired and dnr_age_days, so an agent can decide with concrete evidence.

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 annotations (readOnlyHint=false, destructiveHint=false), the description discloses that do_not_revert locks the decision across sessions and IDEs, and it specifies the return shape {decision_id, session_id}. It also hints at the audit trail preservation via supersede_decision. No contradiction with annotations, and useful behavioral context is added.

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 three sentences, front-loaded with the core purpose, and every sentence earns its place by covering action, locking behavior, return value, and alternatives. There is no redundant phrasing or unnecessary detail.

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 high schema coverage and that the tool has no output schema, the description compensates by specifying return values and the cross-session lock effect. It does not mention the implicit check_conflict behavior or the force parameter, but those are covered in the schema. The description is complete enough for a well-informed 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 provides 100% parameter coverage with detailed descriptions for all 10 parameters, so the description need not repeat them. It does add extra context for do_not_revert ('lock it across sessions and IDEs'), reinforcing the schema, but does not substantially expand meaning for other parameters. 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 states 'Record one architectural decision' with a specific verb and resource, clearly distinguishing the create action from siblings. It also names supersede_decision and set_decision_flag as alternatives for later changes, explicitly differentiating this tool from those.

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 indicates when to use the tool ('Record one architectural decision') and provides explicit alternatives for later modifications ('To change it later use supersede_decision ... or set_decision_flag'), giving clear context. It does not mention exclusions or conditions when this tool should be avoided, but the guidance is sufficient for basic selection.

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, destructiveHint=false. The description adds that the tool writes a skill and checks for conflicts, with an option to override. This provides useful context beyond annotations, though it doesn't cover all potential side effects.

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, well-structured. First sentence states purpose and format, second explains conflict check and alternatives. The version string 'v3.1.0 M3' adds minor noise but does not significantly detract.

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 7 parameters (including nested objects) and no output schema, the description covers the main purpose and conflict check but lacks details on return values and the nested 'triggers' object. Slightly incomplete for a complex 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 high (86%), so baseline is 3. The description adds value for the 'force' parameter by explaining it overrides duplicate warnings. However, other parameters like source, summary, triggers, do_not_revert are not elaborated 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 'Author' and resource 'new skill' with location '.codevira/skills.jsonl'. It distinguishes from siblings by mentioning alternatives like supersede_skill and promote_skill_to_playbook.

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 use this tool (creating new skills) and when not (use supersede_skill for versioning, promote_skill_to_playbook for promotion). Also explains conflict checking and force override.

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?

Adds substantial behavioral context beyond annotations: confirms the tool is a read-only, idempotent operation (consistent with annotations), details the indexing algorithm (FTS5/BM25, Porter-stemmed), specifies default response format (summary-first rows with specific fields), and describes optional output modes. 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?

Every sentence earns its place. The description is front-loaded with the main purpose, then covers indexing, output format, and parameter options without unnecessary words. Efficiently structured for an AI agent to quickly grasp key information.

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 adequately explains the return format (fields and structure). It covers all relevant behaviors, options, and usage context for a tool with 6 parameters and multiple output modes, making it a complete and useful reference.

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?

Despite 100% schema description coverage, the description adds meaningful context: explains default behavior for full and summary_only, the effect of all_projects (v3.6.0, adding project fields), and the structure of the default response. This enhances understanding beyond the schema alone, though the schema already provides good 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?

Clearly states the tool performs keyword search on past decisions using FTS5/BM25 with Porter stemming, explicitly distinguishing from semantic search and from browsing tools like list_decisions/list_tags. The verb 'search' plus the specific resource and scope makes it highly distinguishable 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?

Provides explicit guidance on when to use this tool (searching for previous decisions with shared keywords) and when to use alternatives (browsing list_decisions or list_tags for concepts without shared words). Also explains default behavior and key parameters like full, expand, and summary_only.

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 that it writes a single amendment record to .codevira/decisions.jsonl, which goes beyond annotations (which only indicate not read-only and not destructive). This adds meaningful behavioral context about side effects.

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 with zero waste. Front-loaded with version and clear action. Every sentence earns its place, distinguishing from sibling and describing behavior.

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 5-parameter tool with no output schema, the description covers purpose, usage context, behavioral side effect (file write), and parameter intent. No gaps remain given the annotations and schema coverage.

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. The tool description adds high-level context but does not enhance understanding of individual parameters beyond the schema. 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 states it performs a lightweight flag/tag update on an existing decision, specifying the exact resources (tags, do_not_revert, is_outdated) and distinguishes itself from supersede_decision by avoiding a full rewrite. This is a specific verb+resource+scope with clear sibling differentiation.

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 use ('only need to toggle do_not_revert or correct a tag list') and when not to ('for semantic rewrites use supersede_decision'), providing clear context and an alternative 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 indicate a write operation (readOnlyHint=false) with no destruction (destructiveHint=false). The description adds useful context: writes with a prefix, marks old as superseded, and default-hides the old decision. 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?

Three terse sentences that front-load the main action, then detail behavioral traits and search visibility. 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?

Covers the main effects (writing, superseding, hiding) and includes the format prefix. Lacks mention of error cases or prerequisites (e.g., old_id must exist), but with 7 parameters and 3 required, the description is fairly 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 coverage is high (86%) with good parameter descriptions. The description adds specific format for the prefix ('[supersedes #<old_id>: <reason>]'), which is not in the schema, providing additional 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 the action: 'retire old_id and link to a replacement' with specific verb and resource. It distinguishes from siblings like 'reaffirm_decision' and 'record_decision' by explicitly describing the superseding behavior.

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

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

Usage is implied—to retire a decision and create a replacement—but no explicit when-to-use or when-not-to-use guidance is given. Alternatives like 'consensus_propose_supersession' exist among siblings but are not 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description explains that triggers inherit when omitted, old skill becomes hidden in search but retrievable via list_skills(status='superseded'), and the old is marked 'superseded' with a backref. This provides comprehensive behavioral 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?

Three sentences with clear purpose front-loaded. Minor version prefix ('v3.1.0 M3') adds noise but does not significantly impact clarity. 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?

Missing output schema description, no error conditions or prerequisites. Parameter semantics incomplete. Does not place tool in broader workflow among many siblings.

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 0%, so description must compensate. It explains old_id, name, procedure (implied), and triggers inheritance, but does not cover reason, summary, or do_not_revert. Partial value added.

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 creates a new skill version that supersedes an old one, using the verb 'writes' and specifying the resource 'skill'. It distinguishes from sibling tools like 'record_skill' (new without superseding) and 'list_skills' (listing).

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 when to use (when versioning and deprecating a skill) and mentions inheritance and search behavior. However, it lacks explicit exclusions or comparisons with alternatives like 'supersede_decision'.

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 it's not read-only and not destructive. The description adds the timing instruction 'at session end', which is useful context 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 sentences with zero waste: first states purpose, second gives usage timing. Perfectly front-loaded and concise.

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 one-parameter update tool with no output schema, the description adequately covers purpose and timing. It could mention what happens post-update, but the context seems sufficient for agent 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 covers the parameter completely with a description, and the tool description confirms the field name but adds no additional meaning, examples, or constraints 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 'Update' and the specific resource 'roadmap's next_action field', uniquely identifying its function among many sibling 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?

It explicitly says 'Call at session end' providing clear context, but does not mention when not to use or explicitly name alternatives, though sibling tools imply other update options.

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 this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds little beyond repeating the allowed status values from the schema, failing to disclose potential side effects, authorization needs, or what 'current phase' refers to.

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 at two sentences, with the purpose and usage immediately front-loaded. Every sentence adds value, and there is no superfluous 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?

Given the tool has 3 parameters, no output schema, and no explanation of return values or side effects, the description is insufficient. It does not clarify what 'current phase' is (e.g., a session-level state or a phase ID), nor does it mention the conditional requirement for the 'blocker' parameter when status is 'blocked'. The description should explain what happens after a status update.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description repeats the allowed statuses inline but does not add additional meaning, examples, or constraints beyond what the schema provides. It does not mention the conditional 'blocker' parameter when status is 'blocked'.

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 'update' and the resource 'current phase status'. It lists the valid statuses and provides specific usage scenarios ('when starting work on a phase' or 'when blocked'), which helps distinguish it from sibling tools like complete_phase or defer_phase.

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 the tool ('Call when starting work on a phase (in_progress) or when blocked'), providing clear context. However, it does not mention when not to use it or suggest alternative tools for other operations like marking a phase as pending.

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. The description adds behavioral context: it is intra-session, bounded, decay-scored, and stored in a specific file (.codevira-cache/working.jsonl). This goes well 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 two concise sentences with no wasted words. It is front-loaded with the core action and then provides context and alternatives.

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 6 parameters, all documented in schema with 100% coverage, and the description adds behavioral context, it is complete. No output schema is needed as return is implied.

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 meaning of 'observation' and 'goal' in context, and mentions confidence and importance in terms of use cases (errors=7, decisions=8+). This enhances understanding 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 appends one observation or goal to working memory, distinguishing between 'observation' and 'goal' with specific definitions. It also references the sibling tool 'working_promote' for long-term storage, providing differentiation.

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 the tool ('append... to working memory') and provides an alternative ('Use working_promote to move an entry to long-term memory'), giving clear guidance on tool selection.

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. The description adds valuable context: the decay formula, filtering capabilities, and tombstone exclusion, which go beyond the annotations. No contradictions found.

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, compact sentence covering version, purpose, formula, filters, and exclusions. No redundant phrases; every part adds value. It 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?

The description covers the purpose, filtering, exclusion, and scoring logic. It does not explicitly state that results are sorted by decay score (implied by 'Top-K') or mention pagination, but for a read operation with default top_K=10, it is sufficiently 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 coverage is 100%, so baseline is 3. The description mentions 'Filters by kind / session_id' which aligns with parameters but does not add new meaning beyond the schema's own descriptions. The decay formula is not parameter-specific.

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 it retrieves top-K live working-memory entries sorted by a decay score formula, with filters for kind/session_id and exclusion of tombstoned entries. It distinguishes itself from sibling tools like working_add or working_promote.

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 states filtering options (kind/session_id) and that tombstoned entries are excluded, which helps an agent decide when to use it. However, it does not explicitly mention when not to use it or compare to similar getter tools in the sibling list.

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 states it will 'tombstone the source', indicating a destructive action, but the annotation destructiveHint is false. This is a direct contradiction. Additionally, it does not fully disclose other behavioral traits such as permission requirements or side effects beyond tombstoning.

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 three sentences, starting with the core action, then detailing the 'to' options. It is concise and front-loaded, though the version prefix 'v3.1.0 M2' adds minor noise.

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 7 parameters and no output schema, the description covers the 'to' options well but omits details about the return value for 'to=decision', side effects, and preconditions. The annotation contradiction also undermines 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?

The description adds context for key parameters like 'to' (target stores and their status) and 'force' (overrides check_conflict). However, schema coverage is low (43%), and parameters such as tags, context, file_path, and do_not_revert are not explained in the description, leaving gaps in understanding.

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 promotes a working-memory entry to long-term memory and tombstones the source, specifying different behaviors for 'to' targets. It distinguishes itself from siblings by focusing on promotion from working memory, though it does not explicitly contrast with other tools like working_add.

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 each 'to' option: 'to=decision' is fully wired and calls check_conflict, while 'to=skill' and 'to=playbook' are reserved for future milestones and return a deferred response. It also mentions force=true to override conflict checks. However, it lacks general prerequisites 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 indicate a non-read-only, non-destructive operation. The description adds context by specifying the output location and downstream integration with search_decisions(), but it does not clarify whether files are appended or overwritten, naming conventions, or required permissions. Some behavioral context is added, but significant gaps remain.

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 composed of three short, purposeful sentences: the first states the action and destination, the second identifies the caller and trigger, and the third explains the downstream value. 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?

For a tool with 8 parameters and no output schema, the description provides useful context about purpose and integration but lacks details on return behavior, file handling, or the exact structure of the log. It is adequate for a straightforward write operation but not 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?

The schema description coverage is 63%, covering 5 of 8 parameters (task, phase, skill_ids, task_type, session_id), but the description itself does not describe any parameters or add meaning beyond 'structured session log'. Missing descriptions for decisions, files_changed, and next_steps are not compensated for in the description.

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

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

The description clearly states the tool writes a structured session log to a specific directory path .agents/logs/YYYY-MM-DD/. It distinguishes itself from siblings like record_decision by focusing on the entire session log, and mentions its role as the Documenter's end-of-session action.

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 is called by the Documenter at the end of every session, giving a precise trigger and context. It does not mention alternative tools or when not to use it, but the specific caller and timing serve as sufficient guidance.

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