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

With no annotations, the description carries the full burden. It mentions 'pre-computed' implying a read-only, cached operation, but does not disclose any side effects, authentication requirements, or performance characteristics. Critical behavioral traits like freshness of summaries or error handling are omitted.

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 short, consisting of two sentences plus parameter notes. It is front-loaded with the key verb 'retrieve'. While concise, it could be better structured (e.g., using bullet points for parameters). There is no redundant information.

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

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

Given the presence of an output schema, the description does not need to explain return values. However, the tool has 2 optional parameters and moderate complexity. The description covers the basic purpose and parameter hints but lacks usage context and behavioral details, making it adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the three allowed values for 'scope' and notes that 'repo_path' is an optional absolute path. However, it does not describe the format of directory/file paths for scope, nor does it clarify what 'architectural summaries' contain. The description adds some meaning but is incomplete.

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 'retrieve' and the resource 'pre-computed architectural summaries'. It provides parameter explanations, which help clarify the scope. However, it does not explicitly differentiate from sibling tools like 'dependency_graph' or 'subgraph', though the pre-computed nature is a distinguishing factor.

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 basic parameter guidance (scope values, repo_path optional), but lacks any indication of when to use this tool versus alternatives. There are no prerequisites, exclusions, or contextual cues. The agent is left guessing about appropriate usage scenarios.

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

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

No annotations provided, so description carries full burden. It discloses token-bounded output, max_tokens default, and scoping via file/repo_path. Could mention side-effect free or idempotency, but sufficient for non-destructive tool.

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

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

Three concise sentences, no fluff. Core purpose front-loaded, followed by usage guidelines and parameter clarifications. Excellent structure.

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

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

Given 7 parameters and no output schema, description covers key aspects: purpose, when to use, token limit, and two parameters. Missing details on some parameters but overall adequate for basic usage. Could benefit from a brief example.

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 0%, but description explains two parameters (file, repo_path) with usage context. Other parameters (query, max_tokens, include_*) are not elaborated, though names are self-explanatory. Adds some value but incomplete.

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

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

Description clearly states it 'budget-packs code + episodic context into a token-bounded block' for prompt injection. It distinguishes from raw file reads and provides specific usage directives (call before reading files, avoid for short 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?

Explicitly says 'Call this BEFORE reading any source file' and 'Do NOT call for known short files (< 50 lines) — use Read directly instead.' Provides clear when-to-use and when-not-to-use with alternative.

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 discloses important behavioral traits: it requires preregistered repos and returns empty results if none are found. It does not cover output format or performance, but for a search tool these are secondary; the stated edge case (empty results) is valuable.

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

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

The description is concise and well-structured: a one-line purpose, a two-line parameter explanation, a precondition statement, and a bullet list of invocation scenarios. Every sentence adds unique value without redundancy.

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

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

For a tool with three parameters and no output schema, the description covers the main purpose, parameter scope, prerequisites, and common use cases. It could be enhanced by specifying what constitutes 'knowledge' (e.g., code, documentation) and the result format, but current information is sufficient for most agent decisions.

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%, so the description must compensate. Only the 'scope' parameter receives meaningful explanation (with examples of 'project' and 'org'). The 'query' and 'top_k' parameters are entirely undocumented in text, leaving the agent without guidance on their semantics beyond type/name.

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

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

The description clearly states the action ('Search knowledge') and the resource ('sibling repositories'). It further disambiguates from sibling tools like 'lookup_symbol' by referencing its role in the workflow and explicitly describing scope options that differentiate it from org-wide searches.

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 conditions for when to invoke the tool (e.g., after 'lookup_symbol returned empty', for cross-service architecture questions) and when to use sparingly (broader scope). It also mentions the prerequisite ('repos linked via cognirepo init'), offering clear decision support for the 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, the description effectively discloses key behaviors: direction options, symbol reporting, prerequisite, and empty return condition. It is thorough for a read-only traversal tool, though it could mention if the traversal is recursive or cached.

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

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

The description is well-structured with a clear opening, direction options enumerated, and usage guidance. It is moderately concise; while it could be slightly shorter, every sentence adds value and is 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?

Given 4 parameters, no output schema, and no annotations, the description covers purpose, directions, symbol, and prerequisites. However, it lacks information on the return format (e.g., list of repos, dependency details), which is needed for an agent to fully understand the tool's output.

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

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

Schema coverage is 0%, so the description must explain parameters. It clearly details 'direction' with examples and explains 'symbol' behavior. However, 'start_repo' and 'depth' are not explicitly described, leaving ambiguity. The description partially compensates but misses full parameter clarity.

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

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

The description uses a specific verb ('traverse') and resource ('org dependency graph') to clearly state the tool's function. It differentiates from sibling tools like 'dependency_graph' or 'org_dependencies' by focusing on cross-service relationships and providing direction options for navigating dependencies.

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 with concrete user queries ('which services use X?', 'what does auth-service depend on?') and a use case ('tracing a bug across service boundaries'). It also notes a prerequisite ('Requires repos linked via cognirepo init'), guiding proper usage.

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

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

No annotations are present, so the description must convey behavioral traits. It explains parameter semantics but does not disclose side effects, performance implications, or whether the operation is read-only. The agent lacks information about what to expect from the tool's behavior.

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

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

The description is extremely concise, with four short lines covering purpose and parameter details. Every sentence adds value, and the structure is front-loaded with the main 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?

Without an output schema, the description should explain the return format or structure, which it does not. It also lacks information on error handling, prerequisites, or example usage. The agent may struggle to use the tool effectively.

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%, so the description carries the full burden. It explains direction (with allowed values), depth (meaning of depth), and repo_path (optional absolute path). However, the 'module' parameter is not described (e.g., format or specification), leaving a gap.

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

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

The description clearly states 'Return import/dependency relationships for a module,' which is a specific verb-resource pair. It distinguishes the tool as focusing on dependencies, differentiating it from siblings like 'who_calls' or 'subgraph.' However, it does not explicitly contrast with similar 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?

No guidance is provided on when to use this tool versus alternatives. The description only lists parameters without explaining the ideal use case or context, leaving the agent to infer.

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?

Without annotations, the description carries the full transparency burden. It discloses meaningful behavior: archived-only search, default live-store scope, and the archived hit tag. It does not mention return format, pagination, or side effects, but for a read-only search tool this is acceptable yet not comprehensive.

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

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

The description is compact and front-loaded, opening with a one-sentence purpose. The parameter notes are concise and each adds specific value (archived behavior, repo_path usage). 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?

Without an output schema or annotations, the description should provide more context about return values, default limit behavior, or query semantics. It covers the main options well but leaves out important details like the default limit of 10 and the nature of the keyword matching.

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

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

Schema coverage is 0%, so the description must compensate. It explains include_archived and repo_path in detail, adding real meaning beyond the schema. However, it offers no explanation of the required 'query' parameter or the 'limit' parameter, leaving a clear gap for two of four params.

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 ('Return') and a specific resource ('past episodic events matching a keyword query'), making the core function clear. It does not explicitly contrast with sibling search tools like org_search or semantic_search_code, but the 'episodic events' scope provides some 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 gives useful context about include_archived and repo_path, implying when those options matter. However, it does not explicitly state when to use this tool over alternatives or when not to use it, leaving the guidance primarily implied rather than stated.

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

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

No annotations are provided, so the description carries full burden. It discloses the core behavior (cross-referencing git history and episodic memory) but omits details like side effects (none implied), error conditions, performance impact, or dependencies. Adequate but lacks depth.

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, highly concise. The first sentence conveys the main purpose, the second provides one parameter detail. However, it sacrifices clarity for brevity, making it insufficiently informative. Still, 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 4 parameters, no output schema, and no annotations, the description is incomplete. It does not explain return values, how cross-referencing works, or input constraints like target format. Users are left without enough context to use the tool effectively.

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%, yet the description only briefly mentions repo_path. It does not explain target (format?), since (units?), or max_commits. The description adds minimal value beyond the schema, leaving users to guess parameter meanings.

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: 'Explain what changed in a file or function recently by cross-referencing git history with episodic memory events mentioning the same target.' It uses a specific verb (explain) and resource (changes), and the method (cross-referencing) distinguishes it from siblings like episodic_search or search_docs.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context for use. The only extra detail is a parameter note about repo_path, which is not 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?

With no annotations, the description fully carries the burden of behavioral disclosure. It explains the algorithm (weighted Dijkstra with specific weights), that it can cross service boundaries via org graph, auto-detection of repos, and the return format (path, hops, etc.). This is comprehensive and 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 well-structured with a summary paragraph then parameter bullet points. It is slightly verbose but every sentence adds value (algorithm details, return format). A minor improvement would be to trim the algorithm weight explanation, but it is still efficient.

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

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

Given no annotations and no output schema, the description covers all necessary information: purpose, algorithm, parameter behavior, return structure, and error handling. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 0%, so the description must add meaning for all parameters. It explains that from_symbol and to_symbol are source/destination names, and from_repo/to_repo are absolute paths or auto-detected. This adds crucial context beyond the schema's type/title only.

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 finds the shortest call-graph path between two symbols, crossing service boundaries when needed. It uses a specific verb 'find' and resource 'call-graph path', and distinguishes from siblings like 'lookup_symbol' or 'who_calls' which do not find paths but rather look up symbols or callers.

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

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

The description implies when to use: when you need the shortest path, possibly crossing services. It does not explicitly state when not to use or list alternatives, but the algorithm description (weighted Dijkstra) and mention of crossing service boundaries give context for appropriate use. Sibling tools are available but not contrasted.

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 must carry the behavioral transparency burden. It does so well by stating that the tool creates/updates an HTML report, sources only from real records, sacrifices returns only a pointer, and lists the exact response fields. It doesn't detail whether existing reports are overwritten or hit authorization requirements, but the disclosed constraints are enough to set expectations.

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

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

The description is compact and well-structured: purpose first, then output constraint, then parameter definitions. Every sentence earns its place and there is 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 that there is no output schema, the description covers the key return format and instructs the model on proper post-call usage. It contains the main input parameters, the source constraint, and an clear description of the pointer-based result. Minor gaps are the exact file handling semantics and failure behavior, but these are non-critical for a report-generation tool.

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

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

Schema coverage is 0%, so parameter explanations in the description are essential. 'since' is explained as a history window with an example and default ('90d'), and 'repo_path' is explained as an optional absolute path. This adds semantic meaning beyond the bare schema, though it could have been more explicit about the time format and whether '90d' means days.

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 action ('Generate/update') and resource ('repo insights HTML report'), and downgrades explicitly what it contains (timeline, decisions, challenges, branch/commit activity, index health). This clearly distinguishes it from the sibling search/memory/graph 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 for use: when you need a human-readable 'what happened in this repo' summary, with only real stored records as source. It also includes a direct instruction to Claude to surface the path/link and not to quote or reconstruct report content. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and largely meets it: it discloses the payload size (~300 tokens), describes edge-case behavior such as 'neutral/empty on sparse data' and 'empty if tracking off', and documents the merged timeline query surface. It stops short of explicitly stating side-effect/read-only guarantees, but the 'get' semantics and return-oriented structure strongly imply a non-mutating 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?

Well-structured and front-loaded: purpose and usage guidance come first, followed by a compact bulleted list of return fields, ending with the parameter definition. Every block earns its place and there is no filler or duplication of schema information.

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

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

Given there is no output schema, the description thoroughly documents the rich return payload with examples and types. It also covers usage timing, alternatives, sparse-data behavior, and points to timeline.py::merge() for extended query surface details. This is comprehensive for a bootstrap tool of this 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%, but the only parameter is simple and optional. The description adds meaningful semantics beyond the schema's 'Repo Path' title: 'optional absolute path to the target repository'. It could further explain the default behavior when omitted, but for an optional single path this is adequate.

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?

States a specific verb plus resource ('get_agent_bootstrap') and explains it as a single-call session bootstrap replacing a 4-call sequence. It explicitly differentiates from sibling tools like get_session_brief, get_last_context, get_user_profile, and get_error_patterns by naming them and describing the consolidation.

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

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

Provides explicit usage instructions: call ONCE at session start instead of the 4 individual calls, and use individual tools only when full detail is needed. This is unambiguous when-to-use guidance with clear 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 exist, so description must cover behavioral traits. It discloses the return format (fields like error_type, count) but omits potential caveats such as performance impact, rate limits, or whether it requires permissions. Adequate for a read-only tool, but not rich.

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

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

Two short paragraphs, no extraneous info. Purpose stated first, then details. Every sentence provides value.

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

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

No output schema, but description explains return fields. Tool has low complexity (2 optional params). Usage context and edge cases are covered, making it complete enough for an agent.

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

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

Schema description coverage is 0%, so description must explain parameters. It does: min_count's effect and default, repo_path's purpose as optional absolute path. This adds substantial meaning beyond the schema's type/default fields.

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 'recurring error patterns with prevention hints' and lists each entry's fields. This verb+resource definition distinguishes it from sibling tools like architecture_overview or cross_repo_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?

Explicit guidance: 'Use this to guide Claude away from solutions that have historically failed.' This clarifies the context. Does not explicitly state when not to use or name alternatives, but the context is strong.

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?

Describes return values and the no-context case. Lacks explicit mention of read-only nature but implies it through 'Return' and no side effects. No annotations 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?

Well-structured with clear sections, but slightly verbose with instructions to Claude. Each sentence adds value.

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

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

Comprehensive for a single-parameter tool: covers return values, error state, usage timing, and parameter. No output schema 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?

Parameter 'repo_path' is described as optional absolute path, adding meaning beyond schema type info. With 0% schema coverage, this explanation is valuable.

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

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

The description uses specific verb 'Return' and resource 'most recent context snapshot', clearly distinguishing it from the sibling tool 'context_pack' which writes the snapshot.

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

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

Explicitly states when to call (at session start for known projects) and when not to (fresh projects without context_pack). Also mentions the alternative context_pack.

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, but description implies read-only behavior; could explicitly state non-destructive nature. Returns format helps.

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?

Very concise: purpose, parameter, return format, and error case in just a few sentences.

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

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

Complete for a simple tool: covers all needed info despite no output schema or annotations.

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

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

Schema has 0% description coverage, but description adds meaning: absolute path, defaults to current project.

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

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

Description clearly states it returns HTTP endpoint registry for a service, distinguishes from sibling tools like dependency_graph or cross_repo_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?

Provides parameter description with default, but no explicit guidance on when to use vs. alternatives.

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

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

No annotations provided, so description carries the burden. It accurately describes the tool as a read-like operation (generates a brief) and lists what it returns. Does not disclose potential side effects or auth needs, but the nature of the tool implies it is safe and non-destructive. No contradiction with any implicit annotation.

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

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

The description is concise and well-structured: first sentence states the action, second series describes returns, then usage instructions. Every sentence adds value, and the most critical information (when to use) is front-loaded.

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

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

Given the tool's low complexity (single optional param, no output schema, no annotations), the description is complete. It explains purpose, return components, usage guidelines, and parameter meaning. No significant gaps remain for 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 coverage is 0%, but the description adds meaning to the single optional parameter: 'optional absolute path to the target repository.' This clarifies usage beyond the bare schema definition (anyOf string/null). The description compensates well for the lack of schema descriptions.

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

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

Clearly states it generates a session bootstrap brief for agent orientation, listing specific return components (architecture summary, entry points, recent decisions, etc.). Distinguishes from siblings like get_agent_bootstrap and get_session_history by emphasizing session start usage and project map focus.

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

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

Explicitly says 'call this at the START of a session on an unfamiliar project, or when resuming after a long break' and includes 'Do NOT call this repeatedly; call once at session start only.' Provides a comparison to alternatives: 'faster than reading files or running grep.'

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 for behavioral disclosure. It explains the return format (fields like session_id, created_at, message_count, last_exchange) and parameters. However, it does not explicitly state side effects or idempotency; the name implies read-only but could be more explicit about no mutations.

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 paragraphs: first defines purpose and output, second adds parameter details. Every sentence adds value, no fluff, and key information is front-loaded.

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

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

Despite having no output schema, the description fully covers what the tool returns (list of entries with specific fields) and when to call (at session start). With only 2 parameters (both explained) and no annotations needed for this read-like tool, it is contextually 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 0%, so the description must fully explain parameters. It does: 'limit: number of most-recent sessions to return (default 10)' and 'repo_path: optional absolute path to the target repository.' This adds meaning beyond the schema's type 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 the tool's action ('Return recent conversation session exchanges') and its purpose ('for context continuity'). It specifies the resource (conversation sessions) and differentiates from siblings like 'get_last_context' and 'get_session_brief' by detailing the output fields and usage scenario.

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 at session start to resume context,' providing clear guidance on when to use the tool. It does not explicitly mention when not to use it or alternatives, but the context of resuming continuity is sufficient.

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 and does so thoroughly. It discloses output contents, sparse-data behavior, persona-related conditional payloads, byte-identical backward compatibility, and the fact that persona suggestions are never auto-enabled. This is unusually 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 primary purpose is front-loaded, and conditional details are organized into readable paragraphs. The description is fairly long, but nearly every sentence adds distinct behavioral information an agent needs; little is wasted.

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

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

There is no output schema and no annotation support, so the description must stand alone. It covers payload fields, mood signal structure, precedence, persona variants, optional suggestion behavior, and the only parameter. An agent has enough information to call the tool and interpret its result.

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 has 0% description coverage and only provides type/default for repo_path. The description compensates with a concise, meaningful definition: 'optional absolute path to the target repository.' It could say more about behavior when omitted, but the optional-path semantics are clear.

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: 'Return the user's interaction style profile for Claude to adapt its responses.' It clearly distinguishes this from sibling tools by focusing on interaction-style calibration rather than memory retrieval, search, or org context.

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

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

The description gives an explicit trigger: 'Call this at the start of a session to calibrate response style.' It also explains precedence rules for how the profile should be applied. It doesn't explicitly name alternatives or state when not to use it, but it provides clear enough 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 full burden for behavioral traits. It does not disclose whether the operation is read-only, what the health summary includes, or any potential side effects. The description is too minimal for a tool with no annotations.

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

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

The description is two sentences: purpose first, then parameter explanation. No redundant information, well-structured and efficient.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the basic purpose and parameter. However, it lacks details on the return format or any behavioral context, making it minimally adequate.

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

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

With 0% schema coverage, the description adds value by specifying that repo_path is an optional absolute path. However, it does not elaborate on the format or constraints, only restating what is already in the schema schema.

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

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

The description clearly states the tool returns a health summary of the graph state, which is a specific purpose. However, it does not differentiate it from sibling tools like dependency_graph or subgraph that also analyze graph state.

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

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

No guidance on when to use this tool versus alternatives. The description only explains what it does, leaving the AI agent to infer usage context without any exclusions or prerequisites.

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 adequately discloses behavioral traits: it records a dependency, lists relationship types, and specifies the return format ({linked: True, edge: {src, dst, kind}}). It does not mention idempotency or error handling, but the core behavior is 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 concise: a single-sentence purpose, a use-case statement, a warning, and a parameter list. It is front-loaded and every sentence serves a 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?

For a tool with 7 parameters and no output schema, the description sufficiently covers purpose, usage, and parameter semantics. It mentions the return format and a prerequisite condition. Minor gaps: no error behavior or update semantics, but overall adequate.

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

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

With 0% schema description coverage, the description compensates well by explaining the meaning of most parameters (src_repo, dst_repo, relationship, service_type, port, api_base_url) and their types/options. It misses the 'note' parameter, but overall adds significant value beyond the schema.

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

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

The description clearly states the tool records a dependency relationship between two repos, with a specific verb and resource ('Record a dependency relationship'). It provides a clear use case ('Call this when you discover that one repo imports from or calls another'), distinguishing it from sibling tools like dependency_graph or org_dependencies.

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 the tool ('when you discover that one repo imports from or calls another') and when not to ('Do NOT call for repos not yet registered via cognirepo init'). This provides clear guidance on appropriate 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 burden. It does not disclose behavioral traits like auth needs, rate limits, or side effects. However, since it is a simple read-only context retrieval, the lack of deeper disclosure is acceptable but not exemplary.

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

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

The description is four sentences: purpose, directive, usage instruction, and role in workflow. Every sentence adds value with no waste, and the structure is clear and front-loaded.

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

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

Given no parameters and no output schema, the description fully explains what the tool returns and how to use it in context. It is complete for its simple role.

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 zero parameters, so the baseline is 4. The description does not need to add parameter info, and it correctly omits irrelevant details.

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 shows org, project, and sibling repositories for the current repo, with a specific verb 'Show' and resource 'org context'. It distinguishes from siblings like cross_repo_search by providing 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 explicitly instructs to call this tool first for cross-service/repo queries, and how to use the result to decide on cross_repo_search and scope. This provides clear when-to-use and alternatives.

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

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

No annotations are provided, so the description bears full responsibility. It indicates the tool logs to episodic memory and is retrievable later, but lacks details on whether events are immutable, overwritten, or any side effects. It 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?

Four sentences, each earn their place: purpose, examples, retrievability, and prohibition/alternative. No filler. 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?

Despite good purpose clarity, the description omits parameter details and return behavior. For a simple logging tool with no output schema and sparse parameter descriptions, an agent lacks sufficient information to correctly construct invocations.

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 parameters ('event', 'metadata', 'repo_path'). An agent receives no guidance on how to populate these fields beyond their types.

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

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

The description clearly states the purpose: 'Log a structured episodic event to the episodic memory store.' It provides concrete examples ('bugs found, code explored, agent actions') and distinguishes from the sibling 'record_decision' by explicitly stating it's for recording 'what happened'.

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 ('Use to record what happened') and when not to use ('Do NOT use for architectural decisions') with a direct alternative ('use record_decision instead').

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns locations with details, optionally expands to sibling repos with include_org, and defaults repo_path to server's project directory. It does not mention side effects or permissions, but the read-only nature is implied. Slightly missing potential edge cases.

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

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

The description is concise with three paragraphs: first states purpose and output, second gives usage guidelines, third explains parameters. Every sentence adds value. No fluff.

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

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

For a 3-parameter tool with no output schema, the description is mostly complete. It explains return format, parameter behaviors, and exclusion criteria. It could add pagination info or result limits, but it sufficiently covers typical use cases.

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

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

The description adds significant meaning beyond the input schema: it explains that 'name' should be exact/near-exact, 'include_org' triggers sibling repo search, and 'repo_path' defaults to project directory. Schema coverage is 0%, so the description provides all contextual semantics.

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 all locations (definitions and calls) of a symbol with file, line, and type. It distinguishes itself from sibling tools by specifying exact or near-exact symbol names, contrasting with semantic_search_code for broad concepts.

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

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

The description explicitly instructs when to use (exact/near-exact symbol names) and when not to (broad concepts), and provides a specific alternative: semantic_search_code. This is exemplary 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?

With no annotations provided, the description carries the burden. It explains depth hops and edge kinds, but lacks details on read-only nature, authentication requirements, rate limits, or what happens at edge cases (e.g., depth=0). It provides moderate transparency.

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

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

The description is concise (about 100 words), well-organized with a clear purpose, then breakouts for edge kinds, and a usage hint sentence. No unnecessary information.

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

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

For a tool of moderate complexity, the description covers the core function, parameter, edge types, and usage scenarios. Lacking an output schema, the agent may need to infer the return format, but the purpose is sufficiently clear for call 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?

The only parameter, depth, is described as controlling the number of hops, with a default of 2 indicated in the schema. However, the description does not clarify constraints (e.g., maximum depth, allowed values) or behavior for invalid inputs. Schema coverage is 0%, so the description adds some but not complete value.

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

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

The description clearly states the tool returns 'the bidirectional inter-repo dependency graph' for the current organization, specifying it shows dependencies and dependents up to a depth. It also enumerates the three edge kinds (IMPORTS, CALLS_API, SHARES_SCHEMA), distinguishing it from sibling tools like dependency_graph and who_calls.

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 call the tool: 'when the user asks about service dependencies, what depends on X, or when investigating cross-service call chains.' This provides clear usage context, though it does not explicitly state when not to use it.

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

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

No annotations provided; description only mentions 'text-match search' and that it returns results with source repository. Lacks details on side effects, required permissions, rate limits, or other behavioral traits beyond basic functionality.

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

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

The description is concise, with no wasted words. Key information is front-loaded in the first sentence.

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

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

For a simple tool with two parameters and no output schema, the description covers the tool's role and usage context well, but lacks parameter details and behavioral transparency.

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 query or top_k parameters, leaving the agent without guidance on input format 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 states the tool is a fallback text-match search across org repos, clearly distinguishing it from org_wide_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?

Explicitly says when to use (when org_wide_search returned 0 results or index is sparse) and when not to (do not call as primary cross-repo search). Names the alternative sibling 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?

Describes return structure but does not explicitly state that it is a read-only operation with no side effects. Since no annotations exist, description carries full burden; could be more transparent about non-destructiveness and potential costs (e.g., rate limits).

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

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

Concise: three short sentences cover purpose, usage, return structure, and a note for Claude. No unnecessary words; front-loaded with primary function.

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?

Adequate but missing parameter explanations and error handling. Returns structure is helpful, but without clarifying 'top_k' meaning or potential limitations, an agent may not use it correctly in all contexts.

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

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

Schema coverage is 0% (no descriptions in input schema). The description does not explain the parameters (query, top_k) at all, failing to compensate for the lack of schema documentation. Agent has no guidance on what 'query' or 'top_k' mean.

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

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

Clearly states verb 'searches' and resource 'memories across ALL registered repos'. Distinguishes from siblings: org_search (legacy fallback) and cross_repo_search (for explicit scope control).

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

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

Explicitly instructs when to use this tool: default for cross-repo queries, prefer over org_search, use cross_repo_search for scope control, fallback to org_search if empty. Provides clear alternatives and conditions.

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

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

With no annotations, the description carries full burden. It states the data is stored in episodic memory, retrievable via episodic_search, and the return format. It does not disclose idempotency, overwrite behavior, or side effects, but covers basic behavioral aspects.

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

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

The description is four sentences, front-loaded with the purpose, then storage info, usage guidelines, and return format. Every sentence is necessary, 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?

The tool has 4 parameters, 1 required, no output schema. The description provides return format but lacks full parameter explanation. It differentiates from routine changes but not explicitly from similar sibling tools like log_episode or store_memory.

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%, so description should compensate. The description explains 'summary' and 'rationale' implicitly but does not mention 'affected_files' or 'repo_path'. Adds some value but not comprehensive.

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 records architectural decisions, bug fix rationales, or 'why we did X'. It specifies the verb 'Record' and the resources, and distinguishes from routine changes by emphasizing non-obvious decisions.

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

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

The description explicitly says when to call (non-obvious decisions, bug root-causes, user requests to remember) and when not to call (routine changes). It does not name alternative tools but provides clear context for usage.

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

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

No annotations are provided, so the description carries full burden. It discloses the return value (prevention hint) and a truncation limit (300 chars) for message. It does not discuss auth, side effects, or idempotency, but the behavior is fairly 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 with a clear purpose statement followed by parameter explanations. Every sentence adds value, and it is front-loaded with the main action.

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

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

With no output schema, the description only states 'Returns: the prevention hint' without details on format or structure. The tool has 5 parameters, and while the description covers them, the return value is minimally described. Adequate but not 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 0%, but the description compensates by explaining each parameter: error_type, message, file_path, query_context, repo_path. This adds meaning beyond the schema field names.

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 records an error for future avoidance, using a specific verb and resource. It distinguishes itself from siblings like get_error_patterns (retrieval) and record_decision (different action).

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

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

The description implies usage when an error occurs, but does not explicitly state when to use this tool vs alternatives, nor does it mention conditions or prerequisites. Usage is implied but lacks explicit 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 present, so the description carries the full burden. It discloses persistence across sessions, where values are stored (explicit_preferences, query_rewrites, active_persona), the rejection of unknown persona values with response shape, and persona precedence.

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?

Organized with bold headings and short bullets; dense but every sentence adds operational value. The purpose is front-loaded before detailed call patterns.

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?

This is a high-complexity tool with no output schema and no annotations, yet the description covers all call patterns, storage surfaces, guardrails, and error behavior. The missing repo_path semantics is minor and does not prevent correct invocation.

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

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

Schema coverage is 0%, but the description compensates strongly by explaining preference_key semantics, valid persona values, and how preference_value/context map to query-rewrite corrections. The only gap is that repo_path is not described.

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

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

Clearly states the action ('Store') and resource ('explicit user preference or query-rewrite correction'), then breaks out the three key categories. It differentiates itself from sibling record/logging tools by defining what counts as a preference vs a one-off answer.

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

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

Explicit call conditions are provided: user corrections, repeated preferences, and query clarifications. It also gives an explicit exclusion: 'Do NOT call for one-off answers' and requires opt-in for persona 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?

With no annotations provided, the description partially carries the burden. It discloses the retrieval behavior and the effect of 'include_org', but fails to mention potential limitations, authentication requirements, or whether the operation is read-only. The description is adequate but not comprehensive.

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

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

The description is very concise, consisting of two sentences and a line for 'repo_path'. Every sentence provides essential information without fluff, and the key behavior is front-loaded.

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

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

Given the absence of an output schema, the description does not explain return values or define what constitutes a 'memory'. It is adequate for a simple retrieval but lacks completeness for a tool with 4 parameters and many siblings.

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

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

The schema description coverage is 0%, so the description must add meaning. It explains 'repo_path' in detail (optional, defaults to server directory), but provides no explanation for 'query', 'top_k', or 'include_org'. This partial coverage is mediocre.

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

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

The description clearly states the action ('Retrieve the top-k memories'), the resource ('memories'), and key modifiers ('most similar to the query', 'include_org=True'). This effectively distinguishes it from sibling tools like 'semantic_search_code' or 'episodic_search' by focusing on '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 lacks explicit guidance on when to use this tool versus alternatives. It mentions the 'include_org' option but does not provide criteria for when to use this tool over other search or retrieval tools in the sibling list.

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

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

No annotations provided, so description carries full burden. It clearly indicates read-only semantic search on indexed docs, but does not explicitly mention auth, rate limits, or performance constraints. Still sufficiently transparent for a search 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?

Two sentences plus one param hint, all front-loaded. Every sentence adds value with no redundancy.

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

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

Given no output schema and simple param set, description covers core behavior, usage guidance, and file type constraints. Minor gap in parameter explanation but overall sufficient.

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

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

Schema coverage is 0%, but description only explains repo_path as 'optional absolute path to the target repository.' Query and top_k are not described; top_k could benefit from explanation of result count.

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?

States it searches documentation files by semantic similarity, specifies file types (*.md, *.rst, *.txt), and distinguishes from code search by naming sibling tool semantic_search_code.

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 what it should be used for (README explanations, architecture docs, decision logs) and what it should NOT be used for (code), with direct reference to alternative.

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 full burden. It explains that the tool finds words in names, docstrings, and comments, and specifies the return format (list of {file, line} dicts sorted by file path). It does not mention performance or side effects, but the description is transparent about its behavior.

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

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

The description is well-structured: purpose, distinction, examples, return format, and parameter clarification. Every sentence adds value without redundancy.

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

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

Given the tool has 2 parameters and no output schema or annotations, the description covers purpose, distinction, return format, and parameter details. It is complete for the tool's complexity, though additional context about performance or scope could further enhance 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 description coverage is 0%, so description must explain parameters. The examples illustrate usage of 'word', and the description notes 'repo_path' as an optional absolute path. This adds meaning beyond the schema's minimal type 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 word-level reverse-index search and explicitly distinguishes itself from lookup_symbol() by specifying it finds any word in symbol names, docstrings, or inline comments. This provides a specific verb-resource scope that differentiates it from siblings.

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

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

The description compares itself to lookup_symbol() and provides examples, implying when to use it (full-text search across code). However, it does not explicitly state when not to use it or list alternative tools, but the distinction is clear enough for an agent to select appropriately.

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. The description discloses it operates only on code symbols (no episodic memory) and is read-only by nature, but lacks details on rate limits, authentication, or default behavior. Acceptable but could be improved.

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 with front-loaded purpose and no extraneous information. Every sentence adds value.

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

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

Moderate complexity with 4 parameters and no output schema. The description covers purpose, scope, and exclusions, but could benefit from hinting at return format (e.g., file paths, snippets) to fully compensate for missing output schema.

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

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

Schema description coverage is 0%. The description adds meaning for 'language' (lists examples) and 'repo_path' (optional absolute path), but does not explain 'query' or 'top_k' beyond what is implicit. Compensates partially for low coverage.

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

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

The description clearly states 'semantic vector search over indexed code symbols only' and distinguishes from sibling tools like episodic_search. It provides a specific verb (search) and resource (code symbols), with optional filtering by language.

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

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

Explicitly tells when to use ('for concepts and natural-language queries') and when not to ('Do NOT call for exact string matches') with alternatives (search_token or grep), providing clear context and exclusions.

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

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

No annotations provided, so description carries full burden. Discloses that response includes a 'conflicts' list and that repo_path defaults to the server's project directory. Does not explicitly state that the tool creates a new memory (mutating) or potential side effects, but the conflict mechanism is a notable behavior.

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

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

Three well-structured sentences: purpose, conflict explanation, and one parameter. No filler or repetition; each line adds value.

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

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

Covers purpose, conflict handling, and repo_path default. However, without an output schema, it does not fully describe the response (e.g., success indicator, memory ID). Given the complexity of memory storage, a bit more detail on the return format 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?

Description explains 'repo_path' in detail. 'source' is briefly described as 'optional source label', but 'text' is only implied by the tool's purpose and is not explicitly described. With 0% schema description coverage, the description only partially compensates for the lack of parameter 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?

Clearly states 'Store a semantic memory with an optional source label', specifying the verb and resource. Distinguishes from sibling tools like 'retrieve_memory' and 'supersede_learning' by referencing the latter for conflict resolution.

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

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

Provides explicit context for when to use the alternative tool: if conflicts are detected, use 'supersede_learning'. However, lacks broader guidance on when to use this tool versus other storage tools like 'log_episode' or 'record_decision'.

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

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

No annotations provided, so the description must disclose behavioral traits. It adds minimal context: returns nodes and edges, and mentions the optional repo_path. But it omits details like limits, performance, or behavior when entity is not found.

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

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

The description is very short with two sentences. It is front-loaded with the main purpose, followed by a parameter note. Efficient but could be slightly more 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?

With 3 parameters (1 required) and no output schema, the description is incomplete. It does not explain the depth parameter's effect or the exact format of nodes and edges. More context is needed for a complete understanding.

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

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

Schema coverage is 0%, so the description must compensate. It explains the repo_path parameter but does not clarify entity or depth beyond the schema. This adds some value but not enough for full coverage.

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

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

The description clearly states the tool returns the local neighbourhood of a concept or symbol as {nodes, edges}. It is specific about what it does, though it does not explicitly differentiate from sibling graph tools like dependency_graph or graph_stats.

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. There is no mention of when not to use it or what prerequisites are needed.

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

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

Without annotations, the description carries the full burden. It discloses that it deprecates old memory and creates new one, and returns {found_old: bool, new_id: str}. However, it does not explain potential side effects (e.g., deletion, reversibility), how learning_type affects behavior, or error cases if old_id is not found.

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

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

The description is short and front-loaded with the main action and usage context. It includes parameter explanations and return type. Minor redundancy: 'old_id is the ChromaDB document ID' could be integrated into the first sentence, but overall efficient.

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

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

Given no output schema and no annotations, the description is somewhat incomplete. It explains the return type but not error handling or behavior when old_id is missing. The reference to store_memory provides context, but learning_type remains undefined, and side effects are unmentioned.

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

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

Schema coverage is 0%, so description must compensate. It adds meaning for old_id (ChromaDB document ID from conflicts) and repo_path (optional absolute path). However, it fails to describe new_text (assumed from context) and learning_type (non-obvious, with default 'fact'), leaving a gap for agent understanding.

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

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

The description clearly states the tool deprecates an existing memory and replaces it with corrected text, explicitly referencing the source as the conflicts list from store_memory, which distinguishes it from siblings like store_memory itself.

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 when store_memory returns a conflict that contains incorrect or outdated information', providing clear context. However, it does not mention when not to use it or alternative tools beyond the implied store_memory.

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 fully discloses behavior: two-step search (AST graph then string-literal grep), dynamic dispatch pattern detection, labeling of fallback results, and cost warning. This covers all key behavioral traits an agent needs.

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 adding distinct value: purpose, method, fallback details with labeling, and usage warning. No redundancy, front-loaded with the core action.

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

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

The description covers behavior well but omits details on the output format (e.g., list of call sites with locations). Given no output schema, a brief note on what the result contains would improve completeness. Still, for the complexity, it is largely sufficient.

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

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

Schema coverage is 0%, but the description adds meaning for both parameters: function_name is implied as required, and repo_path is described as 'optional absolute path to the target repository.' It doesn't specify format or constraints, but provides enough context to use correctly.

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

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

The description explicitly states 'Return every caller of a function across the indexed repo,' providing a specific verb and resource. It clearly distinguishes from sibling tools like cross_repo_search or semantic_search_code by focusing on caller discovery.

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

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

The description includes when to use (needing callers), when not to use ('Do NOT call if you already know the callers'), and notes that it is 'Expensive on large graphs,' guiding cost-aware usage. It also explains the fallback strategy, implicitly advising against calling when simpler alternatives exist.

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