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

With no annotations, the description carries the full burden of disclosing behavior. It transparently outlines the internal pipeline (concept lookup, investigate fan-out, refs/impact) and explicitly notes the output format ('structured answer with evidence — no generated prose'). It does not mention edge cases or performance implications, but the core behavioral traits are covered.

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

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

The description is concise and front-loaded, with the core purpose in the first sentence and usage guidance in the final sentence. The parenthetical breakdown of actions is efficient, though slightly dense. It avoids redundancy and stays focused, earning a 4 rather than a 5 due to minor jargon ('sverklo's existing primitives').

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?

No output schema exists, so the description appropriately notes the return type ('structured answer with evidence'). It also covers the three parameters implicitly via the mode and scope hints in the schema, and it explains the tool's role in the broader toolkit. While it does not detail the exact structure of the answer, it provides enough context for an AI agent to understand what to expect.

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

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

The input schema already provides 100% parameter coverage, so the description does not need to repeat parameter details. The description adds some contextual meaning by framing the query as a natural-language question and referencing the overall router behavior, but it does not go beyond the schema's descriptions. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 identifies 'ask' as a natural-language router that maps a question to specific actions (concept lookup, investigate fan-out, refs/impact), distinguishing it from sibling tools by explicitly naming search/investigate/refs for finer control. It also states the output type (structured answer with evidence, no prose), 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 provides explicit when-to-use guidance: 'Use when you want a single keystroke that exercises the whole stack.' It also gives an explicit when-not-to-use with alternatives: 'for fine-grained control prefer search / investigate / refs,' which directly addresses tool selection relative to 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?

With no annotations, the description discloses a key behavior: it requires ast-grep on PATH and falls back to a clear error if missing, which is important for invocation. It also indicates it performs structural matching beyond text. However, it does not explicitly state whether the tool is read-only or what it returns, though 'Find' implies read-only.

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) with the main purpose front-loaded. It packs examples, usage guidance, and prerequisite into a compact format 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?

Given the tool's complexity (AST matching) and the absence of an output schema, the description provides sufficient context: purpose, usage, prerequisites, and fallback. It could mention the result format or limitations, but the schema covers parameters and the purpose is clear. It is reasonably complete for an agent to decide when to use 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?

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining the AST pattern concept with examples ('every console.log($X)') and clarifying how it differs from text search, which directly informs how to construct the pattern parameter. It also mentions language options, though the schema already lists them.

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

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

The description clearly states the tool's purpose: 'Find code by AST shape, not text' with concrete examples ('every console.log($X)'). It explicitly distinguishes from siblings by saying 'Pick this over search when... and over Grep when...' which provides clear 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 provides explicit when-to-use guidance: 'Pick this over search when you need exact structural matches... and over Grep when you need to ignore identifier names or whitespace.' It also mentions the prerequisite (ast-grep on PATH) and fallback error, offering practical usage context.

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

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

No annotations are provided, so the description carries the full disclosure burden. It adequately conveys the tool performs a read-only aggregation health report, listing the specific analyses it computes. It adds cost/behavioral context ('Cheaper than running...'). Minor gap: doesn't give output format or state that it returns a summary report vs. counts, but for a read tool the behavior is sufficiently 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, fully front-loaded with the core purpose. Each sentence earns its place: the deliverable, the pairing guidance, and the cost tradeoff. Zero filler 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 medium complexity (an aggregating report tool), the description covers what output is produced, how it relates to sibling tools, and the use case. Even without an output schema, the description enumerates the report contents (god nodes, hub reports, orphans, stats), which is enough. Could mention whether the output is a summary text vs. a JSON structure, but description does the job.

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 there is only one parameter (token_budget) fully described as 'Max tokens to return (default: 4000)'. The description adds no additional meaning beyond the schema, so it meets the 3 baseline without needing 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 states a specific verb with a resource: 'One-call codebase health report' listing concrete outputs (god nodes, hub files, orphan symbols, language/memory stats). It explicitly names what makes this tool distinct from siblings by comparing it to 'impact' (blast-radius) and 'deps' (fan-in/fan-out), making the purpose 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?

Explicitly states when to use it: 'Use as the seed for a code-quality pass — pair with impact for blast-radius and deps for fan-in/fan-out.' It even gives the cost-based exclusion: 'Cheaper than running overview + impact + dependencies separately,' letting the agent decide between this consolidated call and running multiple sibling tools.

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

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

With no annotations, the description carries full burden. It explains the algorithm, output shape, and a limitation (small repos uninformative), but doesn't explicitly mention side effects or permission requirements. It's read-only in nature but not stated as such, so I give 4.

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 compact sentences, front-loaded with an action verb, no redundancy, 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 single-parameter tool with no annotations/output schema, the description adequately covers purpose, usage context, and return shape, though it could detail the hub file concept more.

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 fully documents min_size with default value, and the description doesn't add parameter-specific semantics, 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 the tool groups files into modules via label propagation on the import graph, returns 3+ clusters with a hub file, and differentiates it from siblings like concepts by explicitly positioning it for first contact.

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 (first contact with unfamiliar repo) and when to skip (fewer than ~20 source files), and advises pairing with concepts after running sverklo concept-index.

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 the read-only nature indirectly as a search, the requirement of a pre-built index, and the bootstrapping message when index is missing. It does not mention rate limits or performance, but these are less critical for a search tool. Overall, it provides beyond the bare minimum.

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, dense with information: purpose, return type, prerequisite, and behavior when index missing. No fluff, well-structured.

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?

Provides necessary context: requires index, explains return (clusters+hub files), and mentions fallback message. Doesn't specify output format or potential errors beyond missing index, but for a search tool this is adequate. Slightly more detail on usage context (e.g., when to prefer over other search tools) would push 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?

Both parameters (query and limit) are described in the schema with 100% coverage. The description reinforces that query is a semantic query, and limit has a default. No ambiguity or missing information.

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 performs semantic search over LLM-labeled subsystem concepts, with a specific verb (search) and resource (concepts). It distinguishes from sibling tools like 'search' or 'diff_search' by emphasizing the semantic nature and the output of clusters with hub files.

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

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

It provides clear context that an index must be built first, and mentions what happens if the index is missing. It does not explicitly name alternative tools, but the description implies this is the go-to for concept-level queries. The prerequisite is a strong guideline.

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 transparency burden. It discloses that results arrive in one round trip, that budget mode returns a PageRank-pruned repo map, and that the bundle includes code, symbols, and memories. It implies a read-only operation without explicitly stating side-effect status, but the described behavior is otherwise well covered.

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 dense, purposeful sentences. It front-loads the core concept, then gives usage timing, then highlights the budget mode. Every sentence earns its place with no repetition or filler.

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

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

For a 5-parameter tool with no annotation and no output schema, the description provides a solid mental model: what the bundle contains, when to use it, and how budget changes the result. It could be more explicit about output structure or failure modes, but the described contents and mode guidance are sufficient for initial 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 description coverage is 100%, so the baseline is 3. The description adds minimal parameter-level value beyond naming budget as the key switch, while the schema already explains task, scope, budget, exclude, and detail_level in detail.

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

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

The description clearly states what the tool does: it takes a task description and returns a curated bundle containing codebase overview, relevant code, symbols, and memories. It positions itself as an 'umbrella' bundler for first-call orientation, but it does not explicitly differentiate itself from sibling tools like overview or search.

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

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

The description gives strong usage guidance: 'Use this as the FIRST call when you start working on a new task and want to orient quickly.' It also recommends passing budget for unfamiliar codebase orientation. It does not name sibling alternatives or explicit when-not cases, but the first-call 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?

Given no annotations, the description carries full responsibility. It explicitly states the tool is deterministic and makes no LLM call, which is important behavioral info. However, it does not explicitly state whether it modifies state or is read-only, though the nature of a coverage check implies no 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 concise sentences with no fluff. The description is front-loaded with the key purpose and structure, making it easy to scan.

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 parameters, no output schema, and no annotations. The description adequately explains the input usage and general output type (structured critique), but lacks detail on the exact output structure, which could aid an agent. Still, it covers the core functionality well.

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 narrative context beyond schema descriptions, explaining that evidence_ids come from fenced blocks and symbols are discussed names, enhancing understanding of how they are used.

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

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

The description clearly identifies it as a deterministic coverage check for an agent's answer, specifying the exact inputs (evidence ids and symbols) and outputs (verification of currency, missed hubs/definitions/mentions). It distinguishes itself from sibling tools like 'ask' or 'verify' through the deterministic, no-LLM-call nature.

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 what the tool does but does not explicitly guide when to use it versus alternatives. It implies use for coverage analysis after an answer is produced, but lacks when-not or comparison to sibling tools.

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

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

With no annotations provided, the description carries the transparency burden and does well by stating that it operates on cached data, performs no second retrieval, and returns the narrowed body inline. It does not discuss edge cases like no matches or invalid regex, but the schema partially covers the regex fallback.

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 short sentences, front-loaded with the primary action, and every clause adds useful information. No filler or redundant restatement of the tool name.

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 filter tool with no output schema and no annotations, the description covers purpose, key behavior, and return style ('narrowed body inline'). It is complete enough for invocation, though it could briefly clarify what a 'result block' is.

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 67%, covering 'head' and 'pattern' but not 'uri'. The description implicitly links 'uri' to 'context handle' but adds little parameter-specific meaning beyond what the schema already provides. This is adequate but not exceptional.

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 ('Filter') and a clear resource ('result blocks of a context handle') with a defined criterion ('by regex'). It also adds distinctive behavior ('Operates on the cached body — no second retrieval') that separates it from retrieval-heavy 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?

The description gives clear context on when this tool is appropriate: when you want to filter an already-cached context handle without triggering a new retrieval. It does not name explicit alternatives or exclusions, so it falls just short of a 5.

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

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

No annotations are provided, so the description must fully disclose behavior. It lacks details about error cases (invalid response_id, out-of-bounds index/offset), read-only nature, and return format. This is insufficient for safe usage.

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 and usage. Every sentence adds value with no waste.

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 4 required parameters, no annotations, and no output schema, the description should cover return value details and error behavior. It only mentions the basic function, leaving important 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 75%, so baseline is 3. The description adds no additional meaning beyond the schema parameter descriptions, which is adequate but not helpful.

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

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

The description clearly states the tool returns a byte-slice from a prior tool call's result block, uses specific verb and resource, and distinguishes from siblings by mentioning inspecting specific offset without full body.

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 ('when the agent needs to inspect a specific offset without the full body'), but does not provide exclusions 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?

No annotations are provided, so the description carries full burden. It discloses that the tool returns 'expired' if the handle's SHA no longer matches, which is a key behavioral detail. However, it does not explicitly state it is read-only or non-destructive, nor mention other potential behaviors.

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 the primary purpose. No unnecessary words 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?

The description does not specify the format of the returned byte-slice (e.g., hex, base64) or error cases beyond 'expired'. Given no output schema, this gap leaves room for ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema, only reinforcing the concept of a byte-slice. It does not elaborate on parameter syntax or formats.

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 returns a byte-slice of a context handle, using the specific verb 'return' and resource 'ctx://<tool>/<id>'. This distinguishes it from siblings like ctx_grep and ctx_peek.

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

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

The description provides explicit usage context: 'Use to drill into the body without rerunning the original retrieval.' It suggests a scenario but does not compare with other sibling tools or specify 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the key non-consuming behavior and lists what the inspection reveals. It does not cover authentication, error cases, or side effects, but for a simple inspect tool this is reasonable and non-destructive.

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?

One concise sentence front-loads the action, names the resource, and packs in the returned metadata fields. There is no redundancy or filler.

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

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

The tool is simple (one parameter, no output schema, no annotations), and the description adequately lists return fields and the non-consuming guarantee. It could improve by explicitly relating itself to sibling tools like ctx_peek or ctx_slice, but the description is functionally complete for its complexity.

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

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

Schema description coverage is 0%, and the description does not explain the 'uri' parameter format, how to reference a context handle, or any constraints. The parameter name is self-evident at a surface level, but the description adds no compensating detail or example.

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 ('Inspect') with a clear resource ('a context handle') and enumerates the exact attributes returned (tool, age, block count, byte size, fresh/expired). This distinguishes it from consuming operations and other context inspection siblings like ctx_peek, ctx_slice, or ctx_grep.

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 clearly implies use when you need metadata about a context handle without consuming it, but it does not explicitly state when to use this tool over alternatives or provide exclusions. Sibling tool names suggest distinctions, but the description does not name or contrast them.

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?

Given the absence of annotations, the description takes on the burden of disclosing consequences by explaining that archived memories are 'only retrieved on demand via recall — not automatically injected.' This is meaningful behavioral context beyond the action itself, though it stops short of discussing reversibility or 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?

Three concise sentences: action, consequence, and usage suggestion. No fluff; every word earns its place.

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

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

For a tool with one simple parameter and no output schema, the description covers the purpose, behavior, and when to apply it, fully addressing the likely questions an agent would have.

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 already describes the single 'id' parameter as 'Memory ID to demote' (100% coverage). The tool description does not add parameter-specific details, only context about the overall operation, so the baseline of 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 phrase 'Demote a memory from core to archive tier' uses a specific verb+resource pair, clearly distinguishing it from sibling tools like promote. The additional sentence about archive retrieval semantics further disambiguates what demoting entails.

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 states 'Use for memories that no longer need to be in every session,' giving a clear when-to-use signal. However, it does not mention when not to use it or name alternative tools such as 'promote' or 'forget'.

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, so the description carries the burden. It says 'Show', implying read-only, but doesn't disclose any specific behaviors like rate limits, output size limits, or side effects. It's a safe read but lacks detail.

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 purpose, no fluff or repetition.

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

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

With no output schema and 4 parameters, the description is minimal. It doesn't explain output format or how depth/direction affect results, but the core purpose is clear. Could be more complete for a tool with 4 parameters.

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 100% of parameters with descriptions, so baseline 3. The description adds no extra semantics beyond what schema already provides. It doesn't explain interplay of depth/direction.

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 states it shows imports and dependents, which is clear and specific. It doesn't explicitly differentiate from siblings like 'refs' or 'impact', but the verb+resource is clear.

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 vs alternatives. The mention of 'impact of changing a file' implies use for change analysis, but it doesn't compare to similar tools or exclude cases.

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 burden of explaining behavior. It discloses the scoped search behavior, optional dependency closure, and noise-reduction intent. However, it does not mention output format or potential limitations, which keeps it from being fully transparent.

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

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

The description is three sentences, front-loaded with the core definition, followed by usage context and concrete examples. Every sentence contributes value, with no redundant or filler content.

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

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

The tool has 5 parameters, no output schema, and no annotations, so the description needs to cover return behavior and limitations. It explains scope and use case well, but omits what the results look like and any edge-case constraints, making it adequate but 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 100%, so the baseline is 3. The description adds meaningful context beyond the schema by clarifying that 'dependency closure' relates to include_callers and by giving example queries that illustrate the query parameter's intended use.

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

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

The description names a specific verb and resource: 'Semantic search scoped to files in a git diff (and optionally their dependency closure).' It clearly distinguishes itself from global search by emphasizing 'only within the changed files, not the entire codebase' and provides concrete example queries, making its purpose 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?

It explicitly states when to use the tool: 'Use this when reviewing an MR/PR and you need to find code related to a query — but only within the changed files.' This gives clear context and implies the alternative of global search, but it does not explicitly name sibling tools or provide precise when-not-to-use 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?

No annotations are provided, so the description carries the full burden. It clearly states the destructive nature ('Permanently delete') and the consequence of losing the audit trail, which is critical behavioral context. It doesn't mention any other side effects or permissions, but for a simple delete operation, this is 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?

The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It efficiently covers purpose, usage guidance, and a critical behavioral warning without any fluff.

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

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

For a simple tool with one parameter, 100% schema coverage, and no output schema, the description is complete. It explains the purpose, when to use it, how to get the ID, and the key behavioral trade-off (losing audit trail). No additional information is needed.

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 already provides 100% coverage for the single parameter 'id' with a description ('Memory ID to delete (from recall results)'). The tool description reinforces this by saying 'Get IDs from recall or memories.' The description adds minimal extra meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Permanently delete a memory after recall returned a stale or wrong entry.' It uses a specific verb (delete) and resource (memory), and distinguishes it from the sibling 'remember' tool by explaining the difference in handling supersession.

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 this tool vs. alternatives: 'Prefer remember (with the new content) over forget+remember when superseding a decision — supersession preserves the audit trail via valid_until_sha + superseded_by; forget loses it.' It also tells the user how to get IDs: 'Get IDs from recall or memories.'

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 that it operates on cached text (no second retrieval), requires a prior response_id, and uses regex with fallback to literal. With no annotations, it provides key behavioral details, though it does not cover error handling for invalid response_ids.

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 no wasted words. Front-loaded with the action and key behavior, then provides necessary parameter context.

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

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

Given the tool's simplicity (2 params, no output schema, no annotations), the description covers the purpose, usage, and parameters adequately. It lacks details on output format or errors, but the tool is straightforward.

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 repeats the schema's parameter descriptions exactly, adding no new semantic value beyond what the schema already provides.

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

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

The description clearly states the verb 'Filter', the resource 'result blocks of a prior sverklo tool call', and the mechanism 'by a regex pattern' with the nuance of operating on cached text, distinguishing it from siblings like search or recall.

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 use: when you have a response_id from a prior search/refs/impact call and want to filter without re-retrieving. It does not explicitly state when not to use, but the context is clear and sufficient for an AI agent.

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 fully disclose behavior. It states the core action (keep top N blocks) and implies it is cheap. However, it does not detail error handling, idempotency, or side effects. The disclosure is adequate but not thorough.

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 and very concise. The first sentence fronts the main purpose, 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?

Given the simplicity of the tool (2 required params, no output schema, no nested objects), the description is somewhat complete. However, it lacks details on error cases (e.g., invalid response_id) and assumes knowledge of 'sverklo tool call.' It is minimally sufficient for a straightforward 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 description coverage is 50%, but the tool description adds no extra meaning to parameters. The 'n' parameter is already described in the schema, and 'response_id' has no description in either place. The description does not 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 clearly states the tool's purpose: 'Keep only the top N result blocks of a prior sverklo tool call.' It also provides context ('Cheap way to shrink a chatty response') and distinguishes from sibling tools like grep_results and ctx_slice.

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 it: 'when you just need the top hit.' It implies a simple filtering use case, but does not explicitly mention when not to use it or name 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?

No annotations are provided, so the description must disclose behavior. It does not state whether it's read-only, what output format to expect, or how partition_threshold affects results. The hint 'Run before editing' implies safety but doesn't explicitly confirm non-mutating 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?

Two sentences, front-loaded with the core purpose, no filler. Every word earns its place.

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

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

The tool has 4 parameters and no output schema, and the description does not explain output format, partition behavior, or limitations. It's insufficient for a complex analysis 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 covers 100% of parameters, so baseline is 3. The description adds a hint about cross_repo, which adds some value, but doesn't explain other parameters 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 it finds callers of a symbol with confidence scoring, giving a specific verb and resource. It distinguishes from siblings like 'refs' by mentioning confidence scoring and cross-repo capability.

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 'Run before editing' and suggests using cross_repo:true for workspace impact, giving clear usage context. However, it does not mention alternatives or when not to use it.

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

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

With no annotations provided, the description carries the full behavioral burden. It explains the internal parallel retrieval strategy (BM25, embeddings, symbol lookup, reference expansion), RRF fusion, the per-hit provenance signal, latency trade-offs, and the optional fifth retriever. It does not explicitly mention side effects or permissions, but this reads as a read-only research operation, so the disclosure is solid.

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

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

The description is front-loaded with the core purpose, uses a short actionable paragraph, and provides the key usage guidance in a single clearly marked sentence. Every sentence adds value; no redundancy or fluff.

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

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

The tool is complex, has six parameters, and no output schema, but the description covers the main return shape, provenance, and use case well. It could be even more complete by noting response contents or edge cases, but overall it gives an agent enough context to decide when to call it and what to expect.

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 every parameter already has a thorough description. The tool description adds contextual framing like budget affecting fusion breadth and expand_graph being a fifth retriever, but it mostly reinforces rather than substantially extends what the schema already provides.

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

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

The description is built around a specific action: a single-call research primitive that fans out to multiple retrievers, fuses them, and returns one ranked bundle with provenance. It clearly distinguishes itself from search and refs/lookup, so the tool's purpose is unambiguous and unique among siblings.

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

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

The description explicitly states when to use the tool: open-ended questions where the answer could live in code, callers, or documentation. It also gives an exact alternative condition: use search instead when pure text/semantic retrieval is wanted, and notes this approach is cheaper than chaining search + refs + lookup.

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 provided, so description carries burden. It discloses it returns definition, signature, location, but does not mention behavior on not found, partial matches, or token budget constraints.

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

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

Two efficient sentences with no waste.

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?

Adequately covers purpose and output for a lookup tool with 4 parameters. No output schema, but description states return contents.

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. Description adds minimal extra meaning beyond what schema already provides.

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

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

The description clearly states it looks up a symbol by name and returns definition, signature, and location. It distinguishes from sibling tools like 'search' or 'grep' which are more generic.

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. With many sibling tools, explicit usage context is missing.

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 full behavioral disclosure burden and does so well. It reveals that default mode shows health metrics (staleness, confidence, access frequency), that only decision/preference/pattern categories are considered in conflicts mode, and that the bi-temporal model preserves both memories—making this explicitly non-destructive.

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

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

The description is two sentences, front-loaded with the primary action, and every clause adds useful behavior or context. There is no filler or repetition of schema details.

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

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

Despite having no output schema and no annotations, the description is complete enough for a moderately complex two-mode tool. It explains the default behavior, the conflict criteria, the reasoning behind preserving conflicts, and the expected action (review prompt), covering what an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaningful context beyond the schema by explaining what the default mode reports and what conflict pairs represent. It doesn't need to restate the other parameters since the schema already documents them clearly.

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

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

The description clearly states the tool lists memories for the current project and can surface conflict candidates, using specific verbs and resources. It effectively differentiates the two modes, though it does not explicitly reference sibling tools like search or recall.

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 each mode: default for memory health overview, conflicts for surfacing potentially contradictory active memories. It also clarifies that the conflicts mode is a review prompt rather than auto-resolution, which helps the agent decide when to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the output nature (dependency-importance ranking via PageRank) and implies read-only via 'Get,' but it does not explicitly state that there are no side effects, nor does it disclose potential token costs or limitations beyond what the schema provides. There is useful behavioral context, but some 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 two sentences: the first states the tool's purpose, and the second provides usage guidance. It is front-loaded, concise, and every sentence earns its place. No fluff or redundant explanation.

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 relatively simple, has all parameters documented in the schema, and no output schema exists to explain. The description covers the core behavior and usage context. It could also mention that the read operation is safe and that token_budget controls output size, but given the schema covers the latter and the purpose is clear, this 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 description coverage is 100%, so the baseline is 3. The description does not add any new parameter-level meaning beyond the schema, but the schema itself fully documents `path`, `depth`, and `token_budget`, including the progressive disclosure pattern. The description's reference to 'structural map' indirectly relates to `path`, but it does not go 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's purpose: 'Get a structural map of the codebase.' It specifies the output ('most important files and their key symbols ranked by dependency importance (PageRank)') and distinguishes itself from siblings by focusing on high-level structure and ranking. This is a specific verb+resource combination with a clear 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 gives explicit when-to-use guidance: 'Use this FIRST when starting work on an unfamiliar codebase or directory.' This is clear and context-rich, but it does not mention when not to use it or name alternative tools. The guidance is strong but lacks the 'when-not/alternatives' component for a full 5.

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

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

There are no annotations, so the description carries the transparency burden. It discloses that the data is LLM-derived, that the tool requires a prior enrich-patterns command, and that calling with no arguments returns taxonomy counts. Behavior around error states or stale indexing is not detailed, but the key prerequisite and mode-dependent behavior are present.

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

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

The description is two sentences, front-loads the main purpose, and uses compact clauses to pack in prerequisites, required arguments, and the no-arg behavior. Every phrase contributes useful information without redundancy.

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

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

For a simple optional-parameter query tool with no output schema, the description covers tool purpose, argument semantics, invocation modes, and the prerequisite command. It slightly under-specifies edge cases like behavior when only `limit` is passed with no pattern, but overall it gives enough context for correct use.

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 already documents both parameters with 100% coverage, so the baseline is 3. The description adds actual semantic value by explaining that omitting arguments returns the taxonomy plus counts, and by reinforcing that `pattern` must come from a closed taxonomy. It could be slightly clearer about passing `limit` alone, but overall it enriches 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 has a specific verb ('Query') and a clear resource ('LLM-derived design-pattern annotations on indexed symbols'), and elaborates the two main usage modes: filtering by a pattern or seeing the taxonomy and counts. This clearly distinguishes it from sibling tools like 'search' or 'lookup' because it targets a closed taxonomy of design-pattern annotations.

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 tells the agent when to use this tool ('to list every symbol tagged with a pattern') and explicitly covers the no-arg case for discovering the taxonomy and counts. It also notes an important precondition (`sverklo enrich-patterns`). No explicit alternatives are named, but guidance is clear enough for a single-purpose query 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?

With no annotations, the description is the only source of behavioral information. It discloses the key outcome (pinned memories surface automatically when recalling by path/symbol) but does not mention whether pinning is idempotent, reversible via unpin, or has any side effects beyond surfacing. This is adequate but incomplete.

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?

A single sentence that front-loads the action and includes the most important behavioral detail. 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?

Given only two simple parameters, no output schema, and no annotations, the description covers the core purpose and effect well. Minor gaps remain around return behavior and duplicate pinning, but these are not critical for this simple operation.

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

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

Schema description coverage is 100%, with both parameters clearly described. The tool description adds no meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Pin') and resource ('a memory to a specific file or symbol'), and clearly distinguishes itself from sibling tools like unpin and recall. It also states the functional consequence, which removes ambiguity.

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 this tool: to attach a memory to a file path or symbol so it surfaces automatically during recall without semantic search. It does not explicitly list exclusions or compare against alternative approaches, but the context is clear enough for an agent.

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 full burden of behavioral disclosure. It goes beyond the action by explaining the consequence: core memories are auto-injected into every session via the sverklo://context resource. It adds meaningful context about the tool's effect, though it does not mention reversibility or permission requirements.

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: two sentences that front-load the primary action and then provide essential context about the core tier and usage. Every word contributes, with no filler or repetition.

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

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

For a simple single-parameter tool with no output schema, this description is fully sufficient. It covers what the tool does, when to use it, and the behavioral effect (auto-injection), even including the specific resource URI. No critical information 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?

The schema already documents the 'id' parameter with a clear description ('Memory ID to promote from recall/memories results'), giving 100% schema coverage. The tool description does not add any additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Promote a memory to the core tier' with a specific verb and resource. It further explains what 'core tier' means (auto-injected into every session) and provides example use cases (style rules, framework conventions), distinguishing it from other memory operations like pin or demote.

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

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

The description gives explicit usage guidance: 'use for project invariants that should always be in the AI's context'. This tells the agent when to use the tool. It does not explicitly mention when not to use it or alternative tools, but the context is clear enough to guide 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?

Despite no annotations, the description transparently discloses the three search modes, their behaviors, and how they depend on the query parameter. It implies a read-only, semantic search operation. Explicitly stating it is non-destructive or idempotent would raise the score, but the current description is still clear.

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 (4 sentences), front-loaded with the primary purpose, and well-structured. Each sentence adds distinct information: purpose, mode description, usage guidance. No redundant or filler content.

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

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

The description lacks information about the return value format or structure. Given no output schema, the agent must infer what the tool returns (e.g., list of memories with relevance). Including a brief note like 'returns a list of matching memories with scores' would improve completeness.

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

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

With 100% schema coverage, the description adds significant value beyond the schema by illustrating when to use each mode and explaining the difference between 'core', 'archival', and 'all'. It also clarifies that 'query' is optional for 'core' mode, which is not obvious from 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 'Search memories semantically' with specific verb and resource. It distinguishes the tool's purpose by listing what it finds (decisions, preferences, patterns) and describes three specialized modes with distinct behaviors, differentiating it from sibling tools like 'search' and 'memories'.

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

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

The description explicitly advises when to use each mode: 'core' for project-wide invariants at session start, 'archival' for historical decisions. It does not, however, compare this tool to alternatives like 'search' or 'investigate', which would improve context for tool selection among many 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It clearly states the tool is read-only (finding references) and explains the matching behavior (default whole-identifier, optional substring). It does not mention performance or indexing, but the key behavioral traits are covered.

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 no fluff. The first sentence states the purpose, the second explains matching behavior and the optional parameter. Every sentence earns its place, and 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 does not explain what the return format looks like (e.g., list of files with line numbers). Since there is no output schema, the agent needs this context to use the result effectively. For a query tool, this is a notable gap.

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

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

Schema coverage is 100% (all parameters described). The description adds value by providing a concrete example of the default matching behavior ('embed does not match embeddingStore'), which reinforces the schema's explanation of the 'exact' parameter. For other parameters, it largely restates schema info, but the example enhances 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 'Find all references to a symbol across the codebase' with specific details on what kinds of references (imported, called, used). It differentiates itself from siblings like 'search' or 'grep_results' by focusing on symbol references, but does not explicitly contrast alternatives.

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

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

The description explains when to use the tool (to find references) and describes the exact matching behavior, but it does not provide explicit guidance on when not to use it or how it compares to sibling tools like 'search' or 'grep_results'. Usage is implied but not fully elaborated.

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 full burden. It discloses a key behavioral trait: auto-invalidation of conflicting prior memories. However, it does not detail the invalidation process or authorization requirements.

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 redundant information. It is front-loaded with the core action and key 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 tool with 8 parameters and no output schema, the description is relatively short. It covers the essential purpose and a key behavior but lacks deeper context on parameter relationships or usage patterns that would aid an agent.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the 'git state' context but does not elaborate on individual parameter usage beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves a persistent memory tied to git state and auto-invalidates conflicting prior memories. This distinguishes it from sibling read tools like 'memories' and 'recall'.

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 saving memories but provides no explicit guidance on when to use this tool versus alternatives like 'pin' or 'memories'. No exclusions or alternatives 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?

No annotations are provided, so the description carries the full burden. It discloses the tool's behavior well: it returns a structured bundle of diff analysis, including semantic delta, dangling references, impact set, and similarity detection. It also implies a read-only operation (no mutation mentioned). However, it doesn't disclose potential side effects like token consumption or performance implications, but given the tool's nature (analysis), this is adequate. The description adds value beyond the schema by explaining what the tool does with the diff.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence earns its place. The first sentence defines the tool and its outputs; the second provides usage guidance and value proposition. No fluff or repetition.

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

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

Given the tool's complexity (diff analysis with multiple output types) and the absence of an output schema, the description does a good job of explaining what the tool returns. It covers the main use case (MR/PR review) and the key outputs. It could be more complete by mentioning the format of the response (e.g., JSON structure) or how to interpret the impact set, but the description is sufficient for an agent to decide to invoke it. The lack of an output schema is partially compensated by the description's enumeration of outputs.

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 'ref' parameter in context ('git ref or range') and the overall purpose of the tool, which helps understand how parameters like max_files and token_budget relate to the output. However, it doesn't add much beyond the schema for individual parameters, but the schema already covers them well. The description's mention of 'semantic delta' and 'impact set' gives context for why token_budget matters.

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: 'Diff-aware context bundler for code review' with a specific verb ('Takes a git ref or range') and resource ('code review'). It enumerates the exact outputs (changed files, semantic delta, dangling references, impact set, similar-symbol detection), which distinguishes it from siblings like diff_search, ast_grep, and grep_results. The description also positions it as a high-level aggregator, not a low-level search tool.

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

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

The description explicitly says 'Use this FIRST when reviewing an MR/PR' and contrasts it with alternatives: 'Replaces 10-20 grep+read calls with one structured response' and 'surfaces blast radius and convention violations grep cannot see.' This gives clear when-to-use guidance and implicitly when-not-to-use (when you need raw grep results or specific symbol lookups).

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 discloses the hybrid search mechanism, PageRank ranking, confidence signal, fallback hint behavior, and the mode/format options' payload tradeoffs. It doesn't mention auth, rate limits, or side effects, but for a search tool these are less critical. The description adds substantial behavioral 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 front-loaded with the core purpose, then uses clear WORKS WELL/STRUGGLES WITH sections for guidance, and ends with a note about the confidence signal. It's slightly long but every sentence earns its place. The structure is scannable with clear section markers.

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 (10 params, 3 enums, no output schema), the description covers the key decision points: when to use vs alternatives, mode/format tradeoffs, repo scoping, and the confidence/fallback behavior. It doesn't describe the return format in detail, but the schema covers parameter semantics and the description covers the behavioral aspects. Slightly more detail on the confidence signal's format would push it 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 the baseline is 3. The description adds value by explaining the mode parameter's payload tradeoff ('refs returns hits without bodies... ~half the payload tokens'), the repo parameter's purpose ('query a sibling project... avoids falling back to grep'), and the current_file ranking boost. It also explains format's hub+count grouping. This goes beyond the schema's terse 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 tool performs hybrid semantic + text search with PageRank ranking, and explicitly distinguishes it from siblings by listing what it works well for (exploratory questions, anti-pattern discovery, cross-file semantic matches) and what it struggles with (framework registration/wiring questions, for which it recommends grep). This is a specific verb+resource with clear 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 provides explicit when-to-use guidance: 'WORKS WELL for' exploratory questions, anti-pattern discovery, and cross-file semantic matches; 'STRUGGLES WITH' framework registration/wiring questions, and explicitly recommends an alternative ('For those, grep the specific annotation...'). This is exemplary 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?

No annotations are provided, so the description carries the burden. It discloses the return format (ctx:// handle), the top-200 cap, and the latency tradeoff (~50ms). It does not explicitly state read-only behavior, but 'search' context implies it, reducing but not eliminating ambiguity.

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: purpose, return/value, and usage guidance. Every sentence earns its place, and key information is front-loaded. No fluff 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?

Despite the absence of an output schema, the description adequately explains return values (ctx handle, refinement hints), describes the intended use case, and covers performance. It is sufficient for an agent to judge invocation and next steps without external details.

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

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

Schema description coverage is 75%, so the schema handles most param meanings. The description adds context about the top-200 pool and refinement hints, but does not elaborate on the parameters beyond the schema. It provides no extra semantic value for the query parameter, which lacks a schema 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?

Description clearly defines a 'Wider-pool, iterative-friendly variant of search', distinguishing it from the sibling 'search' tool. It specifies the resource (candidate pool) and the action (returns a ctx:// handle with refinement hints).

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: 'hard multi-hop questions' and when not to: 'for single-shot lookups use search'. It also names alternative tools (ctx_grep, ctx_slice) for refinement, giving clear usage boundaries.

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

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

No annotations are provided, but the description indicates the tool returns data. It does not mention side effects or safety, but given it has no parameters and seems purely informative, the description is adequate.

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

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

The description is two sentences, front-loading the key information and providing usage guidance without any 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 tool with no parameters and no output schema, the description covers purpose and usage. It could benefit from a brief note on return structure or examples, but is largely 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?

There are no parameters, so the baseline is 4. The description adds context about the returned data but no parameter information is needed.

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

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

The description clearly states the tool returns project state (index health, memory summary) and tool recommendations, and distinguishes itself from siblings by explicitly recommending it as the first call in a session.

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

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

The description explicitly says 'Call this first when starting a new session to understand what sverklo knows about the project,' providing strong usage guidance and 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 carries the full burden. It discloses the heuristic nature: 'Coverage is heuristic — sverklo doesn't run code, so treat results as candidates, not ground truth.' This is a key behavioral caveat beyond the obvious read-only mapping operation.

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

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

Four sentences, each earning its place: the first states the core purpose, the second details outputs, the third gives usage context, and the fourth adds a critical caveat. It is front-loaded and free of 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?

With no output schema, the description adequately summarizes what the tool returns (lists, flags, shows). It covers defaults via the schema and adds usage context and caveats. A more precise return format would be nice, but it's not necessary for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description adds slight context by aligning 'name heuristics + import graph' with include_importers and 'ref/range' with ref, but it doesn't provide new syntax or format details 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 opens with 'Map a git diff to its test coverage,' a specific verb+resource pair. It then enumerates distinct outputs (lists likely tests, flags untested files, shows modified test files), making its purpose unmistakable and distinguishing it from sibling diff/search 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 advises using this tool 'during MR/PR review to answer...' and contrasts it with 'without grepping the whole repo.' However, it doesn't provide explicit 'when not to use' guidance or name alternative tools, so it lacks the full exclusion criteria for a 5.

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

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

No annotations are provided, so the description carries the full burden. It states the action (remove) but doesn't disclose any side effects, such as whether the pin is permanently deleted or if there are any restrictions (e.g., cannot unpin if memory is in use). It also doesn't mention if the operation is reversible or what happens if the pin doesn't exist.

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

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

The description is a single sentence, concise and to the point. It's appropriately sized for a simple operation. 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 is simple (2 params, no output schema), the description is minimal but lacks context about the effect of unpinning, any prerequisites, or what happens after. It doesn't explain the relationship between memory_id and target, or whether both are required together. The description is adequate for a trivial tool but could be more complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what the schema provides. The baseline is 3, and the description doesn't add extra context like parameter relationships or constraints.

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 'Remove a pin from a memory' clearly states the action (remove) and the resource (pin from a memory). It distinguishes from the sibling tool 'pin' which presumably adds a pin. However, it doesn't explicitly mention the target parameter (file path or symbol name) which is part of the purpose, but the schema covers that.

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 vs alternatives. It doesn't mention that it's the inverse of 'pin' or when unpinning is appropriate. The description is minimal and doesn't provide context on prerequisites or typical use cases.

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 full burden of behavioral disclosure. It reveals the output statuses, implying the tool is safe and read-only without explicitly stating side effects. It also clarifies the purpose (combating hallucinated citations), which adds context beyond the tool name. Minor gap: does not explicitly confirm no mutations, but the verification nature makes this unlikely.

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, the first explaining what the tool does and returns, the second stating the use case. No fluff, zero wasted words, and the most critical information (purpose and output) is front-loaded. This is a model of concise, well-structured documentation.

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 only two parameters and no output schema, the description is complete: it defines the input (evidence ids from prior search), the output categories, and the scenario in which it is useful. There are no missing behavioral traits or obscure edge cases that the description should cover for a tool of this simplicity. It fully supports an agent in selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (evidence_ids list and optional claim). The description adds nothing beyond the schema; it reuses the id format and does not elaborate on behavior or edge cases for either parameter. Baseline 3 is appropriate because the description does not add extra meaning beyond the structured 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 function: checking whether evidence ids still point to the same code, with explicit output categories (unchanged/moved/modified/deleted/file_missing). It also distinguishes itself from sibling search tools by referencing 'prior search-family tool' and targeting post-retrieval verification, making its specific verb+resource purpose unambiguous.

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

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

The description explicitly says 'Use this to prevent hallucinated citations after code changes', giving a clear when-to-use context. It implicitly distinguishes from search tools by stating it operates on prior evidence, but does not explicitly mention when not to use or name alternative tools. Still, the guidance is concrete enough for an agent to decide.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly explains the output (a summary), its size (500 tokens), and its intended use case. It implies a read-only operation, though it does not explicitly state whether it modifies anything or require permissions. The context about 'they return more and stay in budget' adds useful behavioral nuance.

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

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

The description is two sentences, front-loaded with the core purpose, and every word earns its place. It provides key facts about the output size and when to use it without any fluff or repetition of the schema.

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

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

The tool is simple: two optional parameters, no output schema, no nested objects. The description fully covers its purpose, use case, and alternatives, making it self-sufficient for an agent to decide when and how to use 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?

The input schema covers 100% of the parameters with descriptive text. The description adds no new parameter semantics beyond what the schema already provides; the mention of '500-token' and 'intentionally small for system-prompt use' echoes the default value for max_tokens. Thus, the schema does the heavy lifting, and the description contributes minimal additional meaning.

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

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

The description clearly states the tool generates a '500-token codebase summary' for pasting into system prompts, providing a specific action (generate summary) and resource (codebase). It also differentiates from sibling tools by explicitly directing MCP-connected agents to prefer 'status and the richer per-tool surfaces.'

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 integrating sverklo intelligence into Cursor, Codex, or a CI bot that can't run the MCP server') and when not to use ('For MCP-connected agents, prefer status and the richer per-tool surfaces'). This gives clear alternatives and exclusions.

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