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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains the append/non-destructive timestamped behavior and the search-to-place mechanism, which is useful context. However, it doesn't specify whether the file is modified in-place destructively, whether existing content is preserved, or any side effects on the wisdom file structure—gaps that matter given zero 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?

The description is compact—three sentences that efficiently convey purpose, usage trigger, and mechanism. The analogy ('sticky note for future sessions') is evocative and aids comprehension. 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 tool creating a sidecar file modification with no output schema and no annotations, the description covers the core behavior adequately. It explains placement logic (search vs append-to-end), the timestamping behavior, and the use case. However, it doesn't clarify the relationship between 'section' and 'file_path' parameters (which target different file types) or what happens on no-match, which are meaningful gaps for correct invocation.

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

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

Schema coverage is 100%, so all four parameters have descriptions. The description adds the search-to-placement behavior (that 'search' locates where to place the annotation) and explains 'comment' is the sticky-note text. This adds behavioral context beyond the schema but doesn't significantly enrich parameter semantics beyond what schema already documents.

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 (annotate/add) and resource (existing wisdom), and explains it's for corrections, clarifications, or new context. It distinguishes from siblings like save_wisdom (which presumably adds new wisdom entries) by focusing on augmenting existing entries, though it doesn't explicitly name the sibling alternative.

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

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

The description provides explicit when-to-use guidance ('when you discover a previous assumption was wrong, needs clarification, or has new context') and explains the mechanism (timestamped, appended below matching entry, like a sticky note). However, it doesn't explicitly state when NOT to use it versus save_wisdom for brand-new knowledge, which is an implied but not explicit distinction.

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

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

The description reveals it saves a timestamped copy for later restore, and clarifies the backup destination directory. It doesn't describe potential side effects, what happens to existing backups, or disk behavior, but the primary behavior (copying a file to a backup dir) is non-destructive and reasonably transparent.

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

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

Three sentences, zero wasted words. The description is front-loaded with the core action and location, then adds discovery guidance for the parameter and a brief rationale. Every sentence earns its place.

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

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

For a simple file-copy backup tool with no output schema and no annotations, the description covers the essential points: what, where, why, and how to find the required parameter. It's missing potential edge-case guidance (e.g., what happens if the destination dir doesn't exist), but for a low-complexity tool the description is largely 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 description coverage is 100%, so both parameters (plan_name and source_path) are already documented in the schema. The description adds value by explaining where plan_name comes from (the plan mode system prompt) and when source_path is needed (non-default directory), which slightly exceeds baseline but schema carries most of the burden.

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

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

The description states a specific verb+resource: 'Back up your current Claude Code plan file to .wisdom/plan-backups/'. It clearly explains what gets backed up (the plan file), where it goes, and why (so you can restore later). It differentiates from the sibling restore_archive_backup and backup-related tools.

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

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

The description clearly indicates when to use it (when backing up the plan file before modifications) and tells the user how to find the plan name ('in your plan mode system prompt'). It implies usage context (backup before plan changes) but doesn't explicitly name alternative tools or when NOT to use it, though siblings are mostly unrelated.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses a key behavior: 'Only reports problems — confirmed symbols are counted but not listed.' This tells the agent it won't get a full report of confirmed items, which is important for setting expectations. It also characterizes the 'fuzzy match' behavior as typo detection. Some gaps remain (e.g., what happens with partial hits, whether it errors or returns gracefully), but the provided behaviors are genuinely useful.

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

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

The description is two sentences, tightly written, and front-loaded with the core purpose. Every clause adds value: the output types, the when-to-call guidance, and the reporting behavior. Zero 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?

Given this is a query-style tool with 100% schema coverage and no output schema, the description covers the purpose, usage timing, and reporting behavior. It could mention edge cases (nonexistent project path, empty symbol list) but for a verification tool the provided context is adequate. The report behavior disclosure compensates for the lack of an output schema.

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

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

Schema description coverage is 100%, so all three parameters already have schema-level descriptions. The description adds the 'verbose' toggle behavior ('also list all known symbols') and the overall return semantics, but doesn't substantially add per-parameter meaning beyond the schema. Baseline 3 is appropriate since the schema documents everything adequately.

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 verifies symbol names and explains the output types (confirmed, fuzzy match, unknown). It distinguishes its purpose well: 'Verify symbol names you just used are real.' This is a specific verb+resource with clear output semantics.

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

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

The description explicitly tells the agent when to call it: 'Call this after writing code that references existing symbols, especially in unfamiliar parts of the codebase.' It gives clear trigger context. It doesn't explicitly name alternative tools, but siblings like refresh_symbols serve a different purpose (populating the registry, not querying it), so the usage context is reasonably clear without exclusion statements.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses what the tool reports (message count, tokens, bloat indicators) and the actionable threshold (>70%). It doesn't describe return format or side effects, but as a read-only diagnostic, this is reasonable. Minor gap: doesn't explicitly state it's non-mutating, though this is strongly implied.

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 that each earn their place: what it does, when to call it, and what to do based on the result. Efficient, front-loaded with purpose, zero 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?

The tool is simple (1 optional param, no output schema). The description provides the tool's report contents and a decision threshold. It doesn't describe the output structure, but since there's no output schema and the tool is informational, describing the exact return format would be valuable. Minor gap only; for this simplicity level, it's quite 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 the parameter (conversation_id) has a thorough schema description including the fallback behavior when omitted and how to find the ID. The description itself doesn't add parameter detail, but the schema fully compensates. The only minor addition would be explaining why you'd target a different conversation, but this is well-covered already.

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 ("Check") and resource (context usage), and elaborates on what it shows: message count, estimated token usage, and bloat indicators. It clearly defines the purpose without tautology, and because it's a diagnostic tool, it doesn't need sibling differentiation since no sibling performs this specific function.

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 it (starting a complex task, when suspecting context is large) and gives actionable follow-up guidance (if >70%, consider prune_context). It also effectively references the sibling tool prune_context as an alternative follow-up action, providing clear when-to-use context.

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

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

No annotations are provided, so the description must carry the full burden. It discloses two meaningful behaviors: the tool auto-runs reindex_project if no index exists, and it produces a compact map. It doesn't mention potential cost, whether it's a read-only operation, or response size, but given zero annotations this is respectable disclosure.

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, tightly written, no filler. The description front-loads the core purpose and then adds usage guidance and a side-effect note. Slightly more could be dropped, but it's efficient and earns every sentence.

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 a single optional well-documented parameter, no output schema, and no annotations, the description covers purpose, contents, when-to-call, cost tradeoff, and a side-effect. It's a simple tool and the description is complete for the context. Could mention return format size/limits, but that's minor.

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

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

Schema coverage is 100%, so the single optional parameter is already well documented in the schema. The description reinforces that project_path can be auto-detected when omitted, which adds a useful behavioral nuance beyond the schema's default text. Baseline 3 plus the auto-detect hint justifies 4.

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

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

The description uses a specific verb ('Get') targeting a specific resource ('compact map of the project') and enumerates concrete contents: file tree with line counts, all classes/types, and all exports. It clearly distinguishes from siblings like reindex_project, check_symbols, and file-reading 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?

Explicit guidance: 'Call this early in a session to orient yourself in an unfamiliar codebase.' It also contrasts with alternatives ('Much cheaper than reading individual files') and discloses a side effect (auto-runs reindex_project). This is strong when-to-use guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool 'loads' knowledge and mentions it returns an overview vs specific results, which adds some transparency. However, it never mentions read-only nature (though implied), potential for large payloads, or side effects. It's reasonable but not richly transparent.

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

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

Four sentences, front-loaded with the purpose statement. The workflow guidance is useful but slightly verbose; it could be tightened. Overall efficient and well-structured without waste, though not maximally 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?

With 5 parameters and no annotations/output schema, the description does a good job tying usage together through the recommended workflow. It explains the overview→file→keyword progression and hints at what results contain (accumulated project knowledge). It's not exhaustive for all 5 parameters but provides a functional mental model for the core workflow.

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 semantic distinction between call modes (overview vs file_path vs keyword) in the recommended workflow, which goes beyond the individual parameter schema descriptions. This workflow context adds real meaning to how parameters combine.

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

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

Description uses a specific verb+resource ('Load relevant wisdom') and clearly states the tool's purpose: retrieving accumulated project knowledge from previous sessions. It distinguishes itself from siblings by describing the context-loading use case, which is distinct from list_wisdom (which presumably lists) and save_wisdom (which writes).

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

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

Provides an explicit recommended workflow with a call sequence: get_wisdom() overview → get_wisdom(file_path) → get_wisdom(keyword). This gives clear when-to-use guidance for different call modes and explains the drill-down pattern, which is effectively guidance for distinguishing between this and alternative approaches.

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

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

With no annotations, the description carries the full burden. It discloses the branch creation behavior, the auto-/resume trigger via dashboard, and the prompt injection detection concern with guidance to avoid markers. This is meaningful behavioral context beyond what structured fields would provide. It doesn't mention destructive aspects of prune_orphans, which would have been useful.

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

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

Three sentences, front-loaded with the core purpose. Each sentence earns its place: purpose+branch, use case, behavioral constraint. Could arguably merge the injection-detection note into the schema description since the schema repeats it, but the duplication is minor.

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 4-param tool with 100% schema coverage and no output schema, the description adds meaningful context: branch semantics, dashboard auto-trigger, and the injection-detection constraint. It's complete enough for an agent to select and invoke correctly. A minor gap is the lack of clarity on what 'new branch' means for existing context flow and whether it replaces or adds to current state.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the natural-sounding content requirement (prompt injection detection) and the conversation ID lookup fallback behavior. The prune_orphans deletion semantics are disclosed. Slight gap: doesn't clarify how 'new branch' interacts with the session parameter.

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

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

The description states a specific verb+resource ('Inject curated context into the conversation as a new branch') with clear intent (restoring context after pruning or seeding sessions). It distinguishes from siblings like restore_context and compact_context by clarifying this creates a new branch rather than replacing or compacting existing context.

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 clear when-to-use guidance: 'restore important context after pruning or seed a session with relevant knowledge.' It implies alternatives exist (restore_context for actual restores, compact_context for compaction) though it doesn't explicitly name them as exclusions. The dashboard auto-trigger behavior is also disclosed.

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?

No annotations are provided, so the description carries the full burden. It implies a read-only browse operation ('Browse what wisdom exists'), which communicates non-destructive behavior reasonably well. However, it doesn't disclose return format, whether output is flat or nested, ordering, or pagination behavior. The description is adequate but provides minimal behavioral depth for a listing tool.

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 plus a filter enum list, all in one line. Efficient and front-loaded: it states the purpose first, then the options. Minimal waste, though arguably restating the enum values duplicates the schema. Overall well-sized for a simple one-parameter tool.

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

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

For a simple read-only list tool with one fully documented parameter, the coverage is mostly adequate. The main gap is not explaining what 'global' means as a filter relative to the others, and not describing the structure of what gets returned. However, given the tool's simplicity and the absence of an output schema, the description does not need to be extensive.

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

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

Schema coverage is 100%, with the single 'filter' parameter fully documented via its enum of valid values and default. The description reinforces this by restating the filter options ('all, sections, plans, patterns, sidecars, global'), but adds essentially nothing beyond what the schema already specifies. The description re-lists what the schema's enum provides.

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

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

Purpose is clear: 'Browse what wisdom exists in the project' with a specific verb (list/browse) and resource (wisdom). The filter options enumerate the distinct categories (sections, plans, patterns, sidecars, global), which helps distinguish it. It doesn't contrast with sibling tools like get_wisdom or save_wisdom, but the read-only list purpose is unambiguous.

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

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

The description says what it does and lists filter options but never states when to use it vs alternatives. Given siblings like get_wisdom and save_wisdom exist, explicit guidance on when to use list over get would add value. The 'Default: all' note gives some operational context but no exclusion criteria or alternative 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?

No annotations are provided, so the description carries full burden. It reveals that pruning is destructive (warnings about saving findings first), works live without restart, and explains the trim mechanics across modes. However, it doesn't disclose what happens to pruned messages (recoverability, whether they're in inspect_pruned_messages), which would be valuable given the destructive nature. The 'orphaned' and 'becomes the new root' details are helpful behavioral transparency, but recovery information is missing.

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 tightly written with actionable guidance in two sentences plus a workflow example. Every sentence earns its place. Minor deduction: the workflow example partially repeats what the parameter descriptions already cover, but it's compact and illustrative rather than padding.

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 destructive operation with 5 parameters and no output schema, the description does well: explains when to use, what the workflow should be, how each mode works. However, it doesn't mention whether pruned messages can be recovered or inspected afterward (sibling inspect_pruned_messages suggests they might be), and there's no mention of output/return behavior. Given the destructive nature and no output schema, slightly more behavioral detail would push this to 5.

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 mode mechanics ('trims before a specific message number', 'everything before it is orphaned') and by clarifying the workflow ordering. It also adds practical context to conversation_id (how to find it in the status bar). The description does repeat some schema content, but the additional usage context (1-indexed, new root behavior, status bar hint) elevates it above baseline.

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

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

The description uses a specific verb+resource: 'Free up context by trimming old messages.' It clearly states the purpose and differentiates from siblings like compact_context by describing the live-no-restart behavior and the explicit workflow with save_wisdom. The sibling tools (compact_context, inject_context) are distinct in purpose.

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

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

Provides explicit when-to-use guidance ('when context_status shows >70% usage'), names the prerequisite save_wisdom step, and gives a typical workflow sequence. This is exceptionally actionable guidance that tells the agent exactly when and how to invoke the 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?

No annotations are provided, so the description carries the burden of disclosing behavior. It tells the agent this is a scanning/mutation operation that refreshes a registry, which is reasonable disclosure. However, it does not mention whether this is reversible, whether it could be slow for large projects, or what the return/result looks like—acceptable but not rich.

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, zero wasted words. The first sentence states what it does, and the second explains when to use it and why. Front-loaded with the action verb immediately.

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 3 optional parameters, full schema coverage, and no output schema. The description clearly states its purpose, usage trigger, and relationship to check_symbols. For a relatively simple refresh operation, this is complete enough—it tells the agent exactly when and how to use it. Could theoretically mention performance implications for large projects, but that's a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters well (max_depth, max_files, project_path all have descriptions). The description adds the project-wide context and the auto-detection behavior for project_path is already in the schema. Baseline 3 is appropriate since all parameter meanings are captured in the schema and the description doesn't need to compensate.

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+resource pair ('Re-scan the project and update the symbol registry') with a clear action scope. It distinguishes itself from check_symbols by explicitly explaining its relationship: refresh_symbols updates the registry so check_symbols can work against the latest state.

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

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

The description gives explicit 'when to use' guidance ('Run this after you have made code changes') and implicitly distinguishes it from check_symbols by framing it as the prerequisite for check_symbols to work correctly. It even references the sibling tool by name, making the workflow 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?

No annotations are provided, so the description carries the full transparency burden. It discloses the parsing methods (AST for JS/TS, regex for Python/Go/Rust), which is useful, and gives a performance benchmark (~350 files in under 2 seconds). However, it doesn't disclose whether reindexing is destructive (does it clear the old index first?), whether it's safe/reversible, or any state side effects beyond the index itself.

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

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

Four sentences with zero waste. Front-loaded with the core action, then scope, then usage guidance, then performance benchmark. Every sentence earns its place.

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

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

Good coverage for a tool with no output schema and no annotations. The description covers purpose, method, when to use, dependencies on it, and performance. Minor gap: doesn't mention what the return value/result looks like (which could matter since there's no output schema), but for a side-effect-style reindexing tool this is acceptable.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining what project_path does beyond the schema ('If omitted, auto-detects from cwd'), which enriches the schema's terse description. max_depth and max_files are adequately covered by the schema defaults.

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 specific verb+resource: 'Build or refresh the project symbol index' with explicit scope (functions, classes, variables, exports). Distinct purpose from siblings like check_symbols and get_project_overview, which are consumers of this index rather than builders.

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

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

Explicit when-to-use: 'Run this when starting work on a project for the first time, or after significant code changes.' Also explains it powers check_symbols and get_project_overview, making the dependency chain clear and helping decide between reindexing vs calling consumers.

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

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

With no annotations, the description discloses key behaviors: async execution (after turn), destructive effect (summarizes and trims history), and environment prerequisite (DASHBOARD_URL). Could mention reversibility or error handling, but sufficient.

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

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

Three concise sentences, front-loaded with action and mechanism. No unnecessary words; each 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 no annotations and no output schema, description covers purpose, usage, behavior, and prerequisites. Lacks return value or error info, but acceptable for an async trigger tool.

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

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

Schema coverage is 100%. Description adds fallback behavior for both parameters (lookup by conversation ID, auto-detect), enhancing understanding beyond 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?

Clearly defines the action (request compaction), resource (session), mechanism (sends /compact via dashboard), and timing (after current turn). Differentiates from sibling tools like prune_context and save_wisdom.

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 (context getting large, proactive) and important precaution (save important findings with save_wisdom first). Provides clear context for usage.

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

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

No annotations exist, so the description carries the full burden. It discloses sidecar creation behavior ('creates sidecar'), file location paths (.wisdom/sections/, ~/.claude/wisdom/), and storage semantics via the schema's parameter descriptions. The description itself is lighter on behavioral details but the schema descriptions compensate with path-level transparency.

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, all substantive, front-loaded with purpose and practical guidance. The 'future you will thank present you' closing is light filler but harmless. Could trim the encouraging phrase, but overall it's efficient and informative without redundancy.

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

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

For a write/persist tool with 6 params, full schema coverage, and no output schema, the description reasonably covers when, why, and how to route entries. The annotate_wisdom sibling handles enrichment separately. Missing minor details like whether existing wisdom gets overwritten or appended, but this isn't critical for correct tool 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% and each parameter has substantive descriptions (scope enum with default paths, file_path sidecar behavior, section path, wisdom_type enum). The description adds value by explaining the routing logic across file_path/section/scope:global. Given full schema coverage, the baseline of 3 is elevated by the description's clear parameter usage guidance.

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 specific language ('Persist a lesson, pattern, caution, edge case, or decision') with concrete examples of what to save and why. It clearly establishes this is a write/persistence operation distinct from siblings like get_wisdom, list_wisdom, and annotate_wisdom which are read/manipulation 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?

Explicitly states when to use ('Save when you discover something non-obvious: a tricky bug, an important constraint, a pattern that works well, or a decision rationale') and provides routing guidance across the main parameters (file_path for file-specific, section for project area, scope:global for cross-project). This is excellent usage guidance with concrete conditions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains the merge-vs-replace behavior is in the schema (the 'replace' parameter), but the description itself doesn't disclose mutation behavior, authorization needs, or consequences. The description is functional but doesn't add rich behavioral context beyond what the schema provides, such as whether plans are idempotent or what happens on conflict.

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 purpose, then guidance, then storage details. Each sentence earns its place. It's appropriately concise for a moderately complex tool with 8 parameters. Not overly verbose, 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 8 parameters at 100% schema coverage, no output schema, and moderate complexity (plans with multiple field-based construction options), the description adequately covers the tool's purpose and usage. It could be more thorough about the merge/append semantics and how fields combine into a plan file, but overall it provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the schema documents all 8 parameters fully. The description adds some value by indicating 'content' replaces the entire file (matching schema) and 'description' is used when building from fields. However, the description doesn't clarify the relationship between 'content' and the other field-based params or how merge/append works, which is a nuanced behavior the schema doesn't fully explain.

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 documents/updates feature plans, what to include (files, design decisions, status), and where plans are stored (.wisdom/plans/). It uses a clear verb ('update'/'document') with a specific resource (feature plans). It doesn't explicitly differentiate from siblings, but the resource is distinctive enough given the sibling list contains unrelated tools like prune_context and inject_context.

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 clear context on when to use: 'when you complete or change direction on a feature' and 'Update existing plans when you complete or change direction.' It explains the storage location and cross-referencing. However, it doesn't explicitly name alternative tools or say when NOT to use this tool, though the siblings are largely unrelated.

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