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

With no annotations, the description carries the transparency burden. It discloses return semantics (violations list, empty = pass), the trigger timing, and the exclusion for CLEAR 1 tasks. It does not explicitly state read-only/side-effect behavior, but the 'check' verb and return-focused wording 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?

Three sentences, front-loaded with the core action and result. Every sentence adds value: the purpose, the return format/interpretation, and the trigger/exclusion rules. 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?

The description covers the tool's purpose, output semantics, and trigger conditions, and an output schema exists to define return structure. However, the lack of parameter documentation prevents an agent from confidently assembling a correct invocation, making it only partially 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 explain the three required parameters. It only vaguely hints at session_id via 'session EvidenceBundle' and task_marker via 'CLEAR 1 tasks', but provides no explicit explanation for any parameter, especially persona_id.

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 ('Run') and resource ('7-criteria Anti-Ambiguity gate over the session EvidenceBundle'), making the tool's purpose immediately clear. It does not explicitly contrast with sibling tools, so it misses the highest distinction criterion.

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 the tool fires ('PLAN→EXECUTE') and when it should be skipped ('CLEAR 1 tasks skip this check'). This provides clear usage conditions and exclusions, which is more than most tool descriptions offer.

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 burden. It adds valuable behavioral information: under 500ms, cached per task_marker, and takes optional memory/graph context. It does not mention side effects, but for an extraction tool this is likely non-destructive.

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

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

The description is compact and front-loaded. Three sentences: first states purpose and inputs, second gives historical context, third provides performance/caching. 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?

An output schema exists, reducing the need to describe return values. The description covers purpose, performance, caching, and input sources, but the 0% parameter coverage leaves a significant gap, making it incomplete for full usage.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at 'prompt' and 'task_marker' (via caching), leaving complexity, dimensions, session_id, and project_dir completely unexplained. This is insufficient for 6 parameters.

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 a specific verb ('Extract') and resource ('TaskSignals') from a prompt with optional context, listing the signal fields. It also differentiates from legacy 'persona keyword matching', making its purpose distinct 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?

It provides clear context: use this to extract structured TaskSignals from a prompt, and explicitly states it replaces persona keyword matching. However, it does not offer explicit when-not-to-use guidance relative to sibling tools like cos_classify_prompt.

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 responsibility for behavioral disclosure. It provides valuable context: return fields, advisory thresholds (≥3/≥5 backtracks), the dependency of suggested_action on root_cause, and per-cause session counts. It does not mention side effects or error conditions, but the disclosed behavior is substantial.

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

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

The description is concise and well-structured. It opens with the primary action, lists the return object, then uses three short sentences to explain each return field's meaning. Every sentence adds information without redundancy.

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

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

The description covers key behavioral logic (thresholds, conditional suggested_action, session-scoped summary) and return values, but it omits usage context and parameter semantics for a tool with 10 parameters and no annotations. It is adequate for basic invocation but incomplete for nuanced handling.

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 for ten undocumented parameters, but it only clarifies root_cause ('when root_cause is supplied') and indirectly session_id ('this session'). Most parameters (reason, from_formula, to_formula, hypothesis, etc.) remain unexplained, leaving a significant gap.

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

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

The description clearly states the action ('Record a backtrack event') and identifies the specific resource type. It distinguishes itself from siblings by the term 'backtrack event,' though it does not explicitly contrast with other logging/query 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 explicit guidance is given about when to use this tool versus alternatives like cos_observation_record or cos_log_query. The intended use is only implied by the phrase 'Record a backtrack event,' with no exclusions, prerequisites, or alternative tool references.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool is heuristic, sub-second, deterministic, makes no LLM call, and optionally writes a gate marker. This gives a clear safety and performance profile, though the effect of the `record` parameter on persistent state is not explicitly described.

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 core purpose and output, followed by the side effect and key performance characteristics. Every sentence adds distinct value with no redundancy or filler.

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

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

The presence of an output schema covers return-value details, so the description's focus on behavior, side effects, and workflow replacement is appropriate. The main gap is the missing explanation of `record` and `agent_dir`, which prevents it from being fully self-contained for parameter-level usage.

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

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

Schema coverage is 0%, so the description must compensate. It explains `prompt` as the user prompt being read, and loosely implies `record` via the optional gate-marker write. However, `agent_dir` is completely unexplained, and the role of `record` remains ambiguous. The description provides partial but not complete parameter 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 a specific action ('classifies', 'reads', 'returns', 'writes') and identifies the exact resource and output structure ({complexity, dimensions, reasoning, signals}). It also distinguishes itself from sibling tools by defining its unique role as a heuristic classifier with an optional gate-marker side effect.

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 it replaces a manual `write-state.sh .thinking_os-gate` step, giving concrete when-to-use context tied to the enforce-task-start.sh workflow. It does not list alternative tools to use instead, but the guidance is strong enough to understand the primary use case.

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

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

Since no annotations are provided, the description carries the full burden. It discloses the internal decision strategy ('situation override > preset match > per-role scoring composer > hard fallback') and states the return type with provenance fields (preset_id, preset_version, effective_threshold, activations). This adds meaningful behavioral detail, though it does not mention side effects, error handling, or permission requirements.

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

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

The description is two sentences and every word adds value. The first sentence states the core purpose, the second provides the strategy and output details. No redundant or filler content exists, making it efficient and well-front-loaded.

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

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

The tool has four parameters, no annotations, and a schema with zero descriptions. The description gives a high-level overview and mentions the return type (with an output schema available), but it omits critical input details and usage prerequisites. It is not fully complete for a tool with 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%, meaning the schema provides no parameter descriptions. The description does not explain the meaning or structure of signals_json, nor how session_id, situation_id, or preset_min_score map to the strategy. It only vaguely references concepts like 'situation override' and 'preset match' without tying them to specific parameters. Since the description fails to compensate for the missing schema documentation, parameter semantics are weak.

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

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

The description clearly states what the tool does: 'Compose an ordered formula-role chain from TaskSignals.' It uses a specific verb ('compose') and a specific resource ('formula-role chain from TaskSignals'), and the strategy details further clarify the behavior. This distinguishes it from sibling tools, which are mostly about tasks, graphs, or learning rather than chain composition.

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

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

The description implies when to use this tool by explaining the composition strategy and the output provenance, but it does not explicitly state usage conditions, prerequisites, or alternative tools. There is no mention of when not to use it or how it relates to sibling tools like cos_dispatch_formula_run. The usage context is implied rather than explicitly guided.

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

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

Annotations provide no safety profile (all hints false), so the description carries the burden. It states 'Get' and 'Returns: str: JSON with full record,' signaling a retrieval operation, but it does not explicitly address whether the call is read-only, what happens on missing IDs, or any error 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 compact with a clear one-line purpose and separate Args/Returns sections. Every sentence earns its place, with no unnecessary filler.

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

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

For a simple 2-parameter details fetch with an output schema, the description covers the arguments and return format sufficiently. It could add an example or note about error cases, but the current level is adequate for selecting and invoking the tool.

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

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

The description adds real meaning beyond the bare schema by explaining pattern_id as 'Row ID (or task_id string for task_outcomes)' and source as 'observations, learned_patterns, or task_outcomes.' The possible type mismatch with the schema's integer pattern_id is a minor concern, but the special case is still useful.

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

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

The description opens with 'Get full details of a pattern, observation, or task outcome,' using a specific verb and specifying the resources. It is clear about the operation, though it does not explicitly differentiate it from sibling query tools like cos_search or cos_graph_query.

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: given a row ID and a source table, retrieve the full record. It does not state when to choose this tool over alternatives, nor does it mention exclusions or prerequisites, so the guidance remains implicit.

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

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

Beyond the annotations (idempotent, non-destructive), the description reveals the digest's size limit, rolling-content nature, and the fact that it can be truncated. It also sets expectations with the return envelope `{path, size_chars, truncated, status}`.

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

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

The description is front-loaded with the core action, then provides compact context, Args, and Returns sections. Every sentence contributes value with no repeated 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?

For a single-optional-param tool with an output schema, the description covers purpose, file location, content semantics, parameter behavior, and return shape. No meaningful gaps remain.

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 fully compensates by explaining `project_root` means "Override project root" and that an empty/default value uses cwd. This is exactly the semantic information an agent needs beyond the bare schema.

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

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

The description opens with a specific verb+resource: "Refresh `.coding-os/digest.md` from current memory state," which is precise and distinct from all sibling tools. It further explains what the digest contains, leaving no ambiguity about the tool's function.

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

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

The description states the digest is read at session-startup to provide a memory anchor before retrieval, giving clear context for when regeneration is relevant. It does not explicitly name alternatives or exclusions, but no sibling tool competes with this digest-regeneration function.

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 burden but only discloses the immediate effect of the 'decision' parameter (triggers backtrack recommendation vs stores for later). It doesn't mention side effects, permissions, or what the returned data looks like, though an output schema exists. This is partial disclosure but provides some behavioral context.

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

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

The description is concise (two sentences) and front-loads the core purpose. It avoids redundancy and is easy to scan. However, it's arguably underspecified, but that's a completeness issue, not a conciseness issue.

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

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

With 7 required parameters, zero annotations, and an output schema present, the description should provide more context on what constitutes a discovery and how the fields relate. It only addresses the decision field, leaving significant gaps in how to fill the other required parameters and what the tool returns.

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 explain parameters. It only clarifies 'decision' with two example values ('backtrack_now', 'record_for_later'); the other 6 required parameters (kind, summary, impact_assessment, session_id, task_marker, persona_id) are completely undocumented in both description and schema. This leaves the agent guessing at their 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 a verb ('Capture') and resource ('mid-work discovery'), and it distinguishes two decision modes ('backtrack_now' vs 'record_for_later') that give the tool a specific identity compared to sibling tools like 'cos_observation_record' or 'cos_backtrack_log'. However, it doesn't precisely define what qualifies as a 'discovery', leaving some ambiguity.

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

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

The description implies usage context ('mid-work discovery') and describes two decision paths, but it doesn't explicitly state when to prefer this tool over siblings like 'cos_observation_record' or 'cos_backtrack_log'. The alternative 'record_for_later' vs 'backtrack_now' provides internal branching but no external guidance on when to use this tool.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It clearly states a crucial trait: 'returns prompt text only' and explicitly denies spawning. This reveals the non-side-effect nature of the tool, though it omits preconditions or error behavior. Given no annotations, this is a solid disclosure.

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

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

The description is three short, focused sentences with no fluff. It front-loads the main action and uses the final sentence to clarify a critical behavioral caveat. 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?

Although an output schema exists and the description covers the core purpose and non-spawning behavior, the complete absence of parameter semantics and minimal usage guidance leaves significant gaps. With 5 parameters and 4 required, the agent needs more context to call this 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% and the description contains no parameter explanations. Required parameters like `formula_id`, `session_id`, `task_marker`, and `persona_id` are not defined in either the schema or the description, leaving the agent without any semantic grounding for correct invocation.

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 precise resource ('rendered agent prompt and input slice for a formula-agent'). It also distinguishes itself from the likely sibling `cos_dispatch_formula_run` by explicitly stating 'Does NOT spawn the subagent'.

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

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

It provides clear usage context: 'The main agent uses this to construct the subagent dispatch.' It also gives a clear exclusion with 'Does NOT spawn the subagent.' However, it does not explicitly name an alternative tool for when spawning is desired, so it's not fully explicit.

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

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

The description discloses that the tool costs ~5k tokens, rebuilds context, is opt-in, and returns status='skipped' without an SDK. These behavioral details go beyond what annotations typically provide, and since no annotations are present, the description carries the full burden effectively. The context rebuild penalty and opt-in nature are valuable 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 structured with a clear hierarchy: purpose, cost/behavior, alternative, use conditions, and fallback. Each sentence adds value, and the length is justified by the amount of guidance. It's front-loaded with the core action, making it easy to scan.

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

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

Despite having an output schema, the 10-parameter input with zero schema documentation leaves the agent guessing about required arguments. The description covers when to use the tool but not how to properly invoke it, making it incomplete for a complex tool with this many parameters. The guidance focuses on decision-making rather than invocation details.

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

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

The input schema has 10 parameters with 0% description coverage, and the description provides no details on the meaning of formula_id, session_id, task_marker, persona_id, or optional fields like model/effort. The only allusion is 'role' which loosely maps to persona_id but is never explicitly connected. This is a critical gap for a tool with four required parameters.

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 'EXPLICIT, OPT-IN sub-agent spawn for one role' which identifies the action (spawn) and resource (sub-agent for one role). It distinguishes from siblings like cos_dispatch_parallel_run by specifying 'for one role' and from cos_dispatch_formula by noting this is the explicit/opt-in variant. The fallback behavior further clarifies the tool's purpose.

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

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

The description explicitly says 'PREFER lazy-loading' and gives an alternative approach with reasoning ('same accuracy, far fewer tokens'). It provides two concrete conditions for using this tool: '(a) the role's work is long-running' or '(b) you explicitly want a separate session for parallelism.' It also explains when to skip if no SDK is available. This is exemplary usage guidance.

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

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

No annotations are provided, so description bears the full transparency burden. It discloses concurrency (asyncio.gather), side effect of persisting outputs to the bundle, and return behavior (list in input order). This is useful, though it omits failure semantics and permission requirements.

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

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

Three sentences deliver purpose, trigger, and behavior without padding. Front-loaded main action, efficient.

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

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

The description covers core context but, with 10 parameters and no schema descriptions, lacks parameter semantics; output schema mitigates return-value ambiguity. Failure handling and edge cases are absent, so it's not fully complete for a parallel-dispatch tool.

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

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

Schema description coverage is 0%, and the description offers almost no parameter-level explanation. 'Formula-agents' loosely maps to formula_ids, but values like session_id, task_marker, persona_id, model, effort, intensity, timeout_s, and complexity remain unexplained.

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?

Specific verb 'spawn' plus 'multiple formula-agents concurrently' clearly identifies what the tool does. The mention of asyncio.gather distinguishes it from sibling cos_dispatch_formula_run, which likely handles single dispatch.

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?

Description explicitly states 'Use when the supervisor returns action='dispatch_parallel'' (with example context), providing a clear trigger. It does not name alternatives or exclusions, so it stops short of a full 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the key behavioral trait that the body is not read, which is useful efficiency context beyond the annotations.

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

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

One sentence, front-loaded with the action and resource, with zero waste. It is highly concise and well-structured.

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

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

For a simple read operation with one parameter and an output schema, the description plus the annotations title provides sufficient context. It does not need to explain return values because the output schema exists.

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 'path' parameter. Although the parameter name is self-explanatory, the description fails to compensate for the lack of schema documentation.

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

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

The description clearly states the tool returns a single doc's header without reading the body, using a specific verb and resource. This distinguishes it from siblings that read full docs or multiple headers.

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 a clear use case: fetch only the header for efficiency. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full marks.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context that the scan is 'header-only' and 'frontmatter' filtered, which is useful. However, it does not disclose behaviors like default limit handling, ordering, or whether frontmatter filters combine via AND/OR, leaving some gaps beyond the annotations.

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

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

The description is a single compact sentence with no filler or redundancy. It is front-loaded with the key action ('Bulk header-only scan') and gives the filtering context. It is slightly telegraphic, but for a short description it is appropriately concise.

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

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

The description leaves significant gaps for a tool with six optional parameters and zero schema coverage. Although annotations cover safety and an output schema exists, the lack of parameter guidance makes it hard to know how to construct a correct filtered scan. The description is too minimal to be considered complete for correct invocation.

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

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

Schema coverage is 0% for six parameters, yet the description only mentions the high-level idea of frontmatter filtering. It does not explain how root, ssot, layer, limit, domain, or since_iso map to filtering behavior or how they should be used, so the description does not compensate for the missing schema descriptions.

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

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

The description states a specific action—bulk header-only scan—on doc headers with frontmatter filtering, making the core purpose clear. It is not tautological and the title reinforces 'List Doc Headers by Frontmatter Filter.' It lacks explicit sibling differentiation, but 'bulk header-only' helps distinguish from singular or search tools like cos_doc_header and cos_doc_search.

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

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

The description implies usage when a bulk, header-only scan of documents filtered by frontmatter is needed. It does not explicitly state when to prefer alternatives or when not to use this tool, so no exclusions or alternative guidance are provided.

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

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

The description adds significant behavioral context beyond the annotations: it explains the stage-1 metadata pre-filter, how auto_context soft-defaults domain from the active task's swimlane, and that filter_hints are heuristic suggestions never auto-applied. It also discloses the two-stage search process and response meta fields. This goes far beyond the readOnly/idempotent annotations and provides rich behavioral 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?

Although lengthy, the description is well-structured and every sentence earns its place. It front-loads the core purpose, then systematically explains the pre-filter logic, parameters, and response meta. For a 9-parameter tool with no schema documentation, this level of detail is necessary and appropriately organized with an Args section and clear examples.

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 is complete for the tool's complexity. It covers parameter semantics, behavioral edge cases (e.g., stale docs, superseded specs), response format (JSON envelope with listed fields), and the decision-making flow for filter hints. The presence of an output schema does not negate the need for this semantic richness, and the description delivers it fully.

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 fully compensates by explaining each parameter (query, source_types, limit, mode, domain, layer, since_iso, include_inactive, auto_context) with examples, defaults, and behavioral nuances. For instance, it clarifies that 'domain' is 'Indexed' and 'include_inactive' hides chunks marked is_active=0. This is a model 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?

The description clearly states the tool performs 'Semantic + lexical search over project documentation chunks.' It specifies the resource (project documentation) and distinguishes itself from generic search tools like cos_search by emphasizing metadata pre-filtering and stage-1 filtering. The title 'Search Project Documentation' reinforces the purpose.

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

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

The description provides clear context for when to use the tool, including a mental model ('Filter → Search → Summarize') and specific guidance for parameters like since_iso ('Use when the agent asks about recent or current state') and include_inactive ('Set True for decision-history retrieval'). It does not explicitly name alternative tools or exclusions, but the usage context is well implied for a documentation search tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds beyond annotations by noting the migration v25 requirement and that 'domain' is reserved for future use. No contradiction with annotations.

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

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

The description is compact yet well-structured with separate paragraphs for purpose, usage, Args, and Returns. Every sentence adds value and no information is redundant.

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 and three parameters, the description covers purpose, usage timing, prerequisites, parameter semantics, and return format. It leaves no important gaps for selecting or invoking the tool.

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

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

The input schema provides zero descriptive text (0% coverage), but the description compensates with a full Args section: explains 'root_cause' filter values, 'domain' reserved status, and 'limit' range/default. This fully clarifies parameter meaning.

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

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

The description uses a specific verb ('Aggregate') and resource ('backtrack_events'), and clearly states the output (root_cause categories with examples). It distinguishes itself from sibling query tools by focusing on failure anatomy from backtrack events.

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 'Use before planning to avoid known failure modes' and notes the prerequisite migration v25. It does not mention when not to use the tool or alternatives, but the context is clear.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by noting that betweenness is expensive and that degree is the cheap default, plus describing the return envelope. There are no contradictions with annotations.

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

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

The description is compact and front-loaded, with a clear one-line summary followed by a terse usage context and parameter list. Every sentence adds value, and no redundant information is included.

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 an output schema present and all parameters explained, the description covers the essential semantics needed to invoke the tool correctly. It even notes the difference in computational cost between metrics, which is useful for selecting between degree and betweenness. No critical gaps remain.

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

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

Despite a 0% schema description coverage, the description fully explains all three parameters: metric (with values and default), top (max nodes and default), and kind (with example and empty behavior). This compensates entirely for the missing schema annotations.

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

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

The description opens with 'Hub detection — surface high-degree (or high-betweenness) nodes', using a specific verb and resource. It clearly distinguishes this tool from sibling graph tools by focusing on centrality metrics, and it ties to concrete use cases (chokepoints, refactor priorities).

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

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

The description provides clear context for when to use the tool ('Use to identify chokepoints / refactor priorities / nodes that demand extra review') and explains the trade-off between metric choices (cheap degree vs expensive betweenness). However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is known. The description adds one useful behavioral detail: the response key is `processes` rather than `communities`. However, it doesn't disclose other behavior such as pagination, sorting, or limits beyond the default parameter values.

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 short, but this is under-specification rather than efficient structure. The phrase 'Louvain process clusters' is cryptic and reads like a fragment, not a clear explanatory sentence. It lacks a proper subject-verb-object structure and doesn't front-load the key information an agent needs.

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

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

Given the tool has 3 parameters with no descriptions and no stated return shape beyond one key, the description is grossly incomplete. It fails to explain the purpose, the meaning of parameters, or the overall response structure. Even with an output schema present, the description adds almost no context for an agent to correctly select and invoke the tool.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It doesn't mention any of the three parameters (top, min_size, max_members), their meanings, or how they affect results. The agent is left guessing from parameter names 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 'Louvain process clusters' is a noun phrase with no verb, making it unclear whether the tool computes clusters, returns clusters, or does something else. It vaguely gestures at community detection via Louvain but doesn't clearly state the action or resource. It also doesn't distinguish this from sibling graph tools like cos_graph_centrality or cos_graph_ranking.

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?

There is no guidance on when to use this tool versus alternatives. No context is provided about typical use cases, prerequisites, or conditions under which this tool is preferred. The only hint is about the response key, which is operational, not about usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds significant behavioral context beyond that: include_content reads source text capped at 2000 chars with a truncation flag, is silently skipped if file missing; include_evidence costs ~2× tokens; include_spine pulls the CONTAINS-ancestor chain. These details are not inferable from annotations and help the agent anticipate side effects and costs.

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

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

The description is front-loaded with a one-sentence purpose, then organizes parameters in a clear Args block. The formatting is tight, using code spans and concise explanations. No fluff; every sentence adds technical detail. The length is justified by the number of parameters and the complexity of the UID scheme.

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

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

Given the tool's complexity (6 parameters, UID resolution, optional content/evidence/spine) and the presence of an output schema, the description is highly complete. It covers param behavior, edge cases (missing file, fuzzy match), cost implications, and workflow (run cos_graph_query first). The output schema obviates the need to describe return structure, so the description correctly focuses on inputs and side behaviors.

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 compensates thoroughly: uid_or_name is explained with a complete UID scheme, examples, auto-resolution rules, and fallback; direction lists values; depth explains BFS; include_content and include_evidence describe concrete effects; include_spine explains what it pulls. Every parameter is semantically enriched beyond the raw schema.

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

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

The description opens with a specific, action-oriented statement: 'Return callers + callees + siblings + referenced docs around a symbol.' This clearly identifies the resource (a symbol in the code graph) and the scope (callers, callees, siblings, referenced docs), distinguishing it from sibling tools like cos_graph_query (which discovers candidates) and cos_graph_references (likely narrower).

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

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

The description gives explicit workflow guidance: 'Run cos_graph_query first to discover candidates.' This tells the agent when to use this tool relative to a direct alternative. It also clarifies the auto-resolution and fuzzy fallback behavior for uid_or_name. However, it does not explicitly contrast with other graph tools (e.g., cos_graph_trace, cos_graph_impact), so there is still some ambiguity about when to choose this over those.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope of enumeration (handler types) but does not disclose output format, filtering behavior, or potential performance implications. It provides some contextual value without contradicting annotations.

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

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

The description is a single, focused sentence that front-loads the core action and clearly states the resource. There is zero wasted verbiage, making it highly concise and well-structured.

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

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

Despite having an output schema and annotations, the description is too sparse to support full invocation. It does not clarify how the parameters work, what 'scope' means, when to set include_test_sources, or whether the output includes details beyond handler names. With 3 parameters and 0% schema coverage, this description leaves significant gaps 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%, and the description does not explain any of the three parameters. Parameter names (kinds, scope, include_test_sources) offer some hints, but values, defaults, and effects are undefined. For example, 'scope' defaults to 'all' but its possible values are not explained, and the interaction between 'kinds' and 'scope' is unclear. The description fails to compensate 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?

The description uses a specific verb 'Enumerate' and clearly identifies the resource: 'every handler declared in the graph' with explicit handler types (HTTP / MCP / gRPC / events / WS). This distinguishes it from sibling tools like cos_graph_query or cos_graph_context, making the purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only states what the tool does; it does not mention any exclusions, prerequisites, or relationships to other graph tools (e.g., cos_graph_entrypoints, cos_graph_search). An agent would have to infer usage context from the tool name and 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?

Annotations already establish the read-only, idempotent safety profile. The description adds valuable behavioral context: the distinction between import cycles as a design smell and call cycles that may be legitimate, plus the exact return envelope structure. No contradiction with annotations.

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

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

The description is tight and well-structured using Args/Returns sections. Every sentence contributes meaningful information without redundancy.

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

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

The description covers purpose, parameter semantics, and return envelope, which is complete for a read-only graph query tool. The output schema exists, so detailed return field descriptions are not required, and none are missing.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: scope's two values, top as a cap on returned cycles, and min_size as a filter threshold. This is sufficient for correct parameter selection.

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 and resource: 'Detect circular dependencies as strongly-connected components.' It clearly identifies the tool's function and distinguishes it from sibling graph tools by focusing on cycles/SCC analysis.

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

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

The description provides clear context for the scope parameter (imports vs calls) and explains what each represents, guiding when each mode is appropriate. However, it does not explicitly contrast with sibling graph tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds valuable behavioral nuance: it defines what counts as a reference, notes that results are candidates (not authoritative), and explains the include_tests flag alters edge counting. This exceeds mere scope scouting.

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 topic sentence, a caveat paragraph, and labeled Args/Returns sections. Every sentence adds value: the purpose, the nuance about candidates, parameter semantics, and return envelope info. No fluff or redundancy.

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

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

Given the moderate tool complexity, 0% schema coverage, and no param enums, the description fully compensates: all three parameters are defined, the return format is mentioned, and critical caveats about false positives are included. The existence of an output schema further reduces burden, making this highly complete.

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

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

Schema coverage is 0%, so the description carries full parameter burden. It explains `kind` as a filter (function|method|class, empty=all three), `top` with default 50 and max 500, and `include_tests` as 'Count test-sourced edges + include test files'. This adds meaning far beyond the raw schema.

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

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

The description opens with a specific verb+resource: 'List in-repo symbols with zero non-test inbound references' and clarifies it as 'dead-code candidates'. It further distinguishes itself from siblings by noting it is 'the inverse of centrality', immediately separating it from related 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 explicitly warns that results are 'Candidates only' and that dynamic-dispatch/CLI-registered/externally-called symbols may appear, advising to 'verify with cos_graph_references before deleting'. This names the alternative tool and provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar for additional disclosure is lower. The description adds useful behavioral details: empty files produce an empty envelope, analyze_downstream walks transitive blast radius, and scope is 'Label only' with allowed values. However, 'Label only' is ambiguous and the effect of scope on results is not explained, so transparency is only partially enhanced.

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 highly efficient: one front-loaded purpose sentence followed by a compact Args list. Every sentence adds value, and there is no repetition of annotation or schema information. This is a model of concise tool documentation.

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

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

The description covers all three parameters, the empty-input edge case, and the core analysis dimensions (symbols, downstream tasks, risk level). Since an output schema exists, not detailing return values is acceptable. Minor gaps remain around the meaning of 'scope' and how risk level is determined, but overall the description is adequate for a three-parameter tool.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter semantics. It explains files as comma-separated paths with empty-input behavior, lists valid scope labels, and describes analyze_downstream as transitive blast-radius traversal. The scope explanation is limited to 'Label only' plus allowed values without defining what each scope means, preventing a perfect score.

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

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

The description opens with a specific verb and resource: 'Map changed files to affected symbols + downstream tasks + risk level.' This clearly identifies the tool's purpose as change-impact analysis. It does not explicitly differentiate from sibling tools like cos_graph_diff or cos_graph_impact, but the unique output dimensions (downstream tasks, risk level) make the purpose clear enough.

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

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

Usage is implied by the phrase 'changed files' and the annotation title 'Graph Pre-Commit Self-Review,' and the Args block provides practical input guidance. However, the description never explicitly states when to use this tool instead of sibling graph tools, nor does it mention any exclusions or alternatives. This is implied usage rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which cover safety. The description adds context by detailing the use of `git diff --name-only`, mapping to symbols and downstream consumers, and the ability to walk transitive consumers, which goes beyond the annotation baseline.

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: a one-line summary, a method paragraph, an Args list, and a Returns section. Every sentence contributes to understanding, with no unnecessary repetition or fluff.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description is sufficiently complete. It explains the workflow, parameters, and return envelope keys, and provides enough context for an agent to select and invoke the tool, though it could benefit from a brief example or note on interpreting risk_level.

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

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

The input schema has 0% description coverage, but the description compensates with an Args section that explains each parameter (base, head, analyze_downstream) and provides defaults and semantics. This adds meaningful 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's function: 'Graph blast-radius of a git revision range (base..head)' with a specific verb and resource. It further explains the process and output, distinguishing it from sibling graph tools that focus on other analyses.

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 context via 'PR/review view' but does not explicitly state when to use this tool over alternatives or mention any exclusions. No sibling tool is named as a fallback or alternative, leaving some ambiguity.

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

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

The description states that setting fix=true will 'attempt safe repairs (delete dangling edges)', which is a destructive/write operation. However, annotations declare readOnlyHint=true and destructiveHint=false, creating a direct contradiction. This is a severe inconsistency that could mislead the agent into thinking the tool is safe and read-only when it can modify data.

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 and well-structured: purpose is front-loaded, usage trigger is given, parameters and returns are clearly bulleted. Every sentence earns its place with no waste.

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

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

Given the tool's simplicity (one optional parameter) and the presence of an output schema, the description covers all necessary aspects: purpose, when to call, parameter semantics, and return envelope. It even mentions the safe usage pattern (report-only first), making it complete for an agent to invoke correctly.

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

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

The schema only provides the parameter name 'fix' with a default, but the description fully explains its meaning, including conditional behavior (repair vs. report-only mode) and a recommendation to use report-only first. This 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's purpose as a 'Graph health snapshot' and lists specific issue types (orphans, dangling edges, duplicates, backend status). This distinguishes it from sibling graph tools like cos_graph_query or cos_health by focusing on integrity diagnostics rather than querying or general health.

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

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

It provides explicit trigger conditions: 'Call when graph queries return nothing or meta.backend_fallback=true.' This gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small amount of behavioral context by mentioning 'scored' and the entry point categories, but it does not explain how scoring works, if any sorting is applied, or how pagination/limits behave.

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

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

The description is a single sentence with no padding, which is concise. However, the trailing '— TASK-081.' is irrelevant for tool invocation and adds noise. The structure is minimal but not optimally informative.

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 4 parameters with no schema descriptions, an output schema, and many graph-related siblings, the description is inadequate. It does not explain how parameters affect results, what 'scored' means, or how this tool differs from alternatives, leaving significant gaps for an agent to navigate.

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 provides no information about the four parameters (top, kind, diversify, min_score). It does not compensate for the missing schema descriptions, leaving the AI agent to infer meanings solely from parameter 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 identifies the resource as 'entry points' and the action as returning 'Top-N scored' items, which clearly indicates a ranked list retrieval. It is distinct enough from sibling tools like cos_graph_ranking by focusing on entry point types (main/cli/http/cron/test), though an explicit verb like 'list' or 'get' is absent.

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?

There is no guidance on when to use this tool versus alternatives such as cos_graph_ranking, cos_graph_search, or cos_graph_query. The description provides no context about appropriate scenarios or exclusions, offering only a bare statement of what it returns.

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

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

Annotations already declare readOnly/idempotent/non-destructive. Description adds behavioral context: max_nodes hard cap, include_spine ancestor-chain behavior, mode view-blend semantics, and exclude_kinds sentinel defaults. These go beyond annotations, though references like 'S3' and 'TASK-141' are insider-cryptic.

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?

Lead sentence states purpose, then a compact arg list. Each param earns its place. Slight deduction for cryptic inline refs ('S3', 'TASK-141') that could be clarified without bloat.

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 7-param export tool with rich annotations and an output schema, the description covers behavior and defaults well. Missing explicit return-value prose, but output schema covers that; lack of when-vs-alternatives keeps it from 5.

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

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

Schema has 7 params at 0% description coverage, so the description carries full burden. It explains every parameter: format values, root_uid semantics, edge_types filter, max_nodes cap, include_spine chain, mode options, exclude_kinds sentinel. This substantially adds meaning beyond the bare schema.

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

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

Description opens with 'Export a subgraph as json | mermaid | dot', a specific verb+resource+output formats. It clearly differentiates from sibling graph tools (query, search, context) by focusing on export. The formatting and parameter list reinforce purpose.

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

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

The description implies usage through the export verb and parameter explanations (e.g., root_uid empty, mode when no root pinned), but never explicitly states when to choose this over alternatives like cos_graph_query or cos_graph_search. No when-not or alternatives named.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: BFS-based traversal (depth and visit_limit), edge filtering by confidence_min, and the risk-tier grouping output. It also explains the truncation signal (meta.walk_truncated) that indicates when to increase limits. This goes beyond annotation information without contradicting it.

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: a one-sentence purpose that front-loads the core function, followed by a compact Args block. All parameter explanations are precise and useful, with no filler or redundancy. The format makes it easy to scan and locate key details like uid schemes and defaults.

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

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

Given the tool's complexity (5 parameters, graph traversal, risk tiers), the description is comprehensive. It covers every parameter with examples and edge cases, references a sibling tool for uid discovery, explains default behavior (confidence_min 0.3, visit_limit 500), and describes the risk-tier output. The presence of an output schema means return-format details are not needed from the description.

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

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

The schema provides only parameter names and defaults (0% coverage), but the description fully documents each parameter in the Args block. uid includes a detailed scheme with examples and auto-resolution behavior; direction explains downstream vs upstream semantics; depth is defined as a BFS hop limit; confidence_min is tied to edge scores; visit_limit is clarified as a node-visit cap with a tuning hint. This far exceeds schema-level 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 opens with a specific action ('Group affected nodes by risk tier') and names the concrete outcome categories (will_break / should_review / context). This clearly distinguishes it from sibling graph tools like cos_graph_query or cos_graph_trace, which focus on traversal or search rather than impact classification.

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 running cos_graph_query first when unsure about the uid, naming a direct alternative. It also explains how to choose direction ('downstream (callers — break if uid changes)' vs 'upstream (deps uid calls/imports)') and provides a practical hint to raise visit_limit when meta.walk_truncated is true. This is actionable guidance for selecting and tuning the tool.

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

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

Adds meaningful behavioral context beyond annotations: describes BFS depth limit (max_hops) and auto-resolution of raw paths. The annotations already indicate read-only and idempotent behavior, so the description enriches that with algorithmic details, though failure behavior is not covered.

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

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

Highly concise: a one-sentence purpose followed by clear bullet-style parameter descriptions. Every line adds value with no redundancy or filler.

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

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

Covers the essential aspects: purpose, parameter behavior, and algorithmic constraints. The output schema handles return details. Missing only explicit guidance on when to prefer this over sibling graph tools, but overall is complete for practical use.

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

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

Schema coverage is 0%, so the description fully compensates by explaining all three parameters: source_uid and target_uid resolution rules, and max_hops as a BFS depth limit with default 5. This provides semantics the schema lacks entirely.

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 'Shortest path between two nodes (either direction)' with a specific verb and resource. It distinguishes from sibling graph tools like cos_graph_trace and cos_graph_search by focusing on the path computation and bidirectional nature.

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

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

Provides clear context for when to use (finding shortest paths between two nodes), but does not explicitly state exclusions or direct alternatives to other tools. It references cos_graph_impact for the resolution scheme, which is a helpful pointer but not a usage 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that the tool performs lexical + graph expansion, falls back to direct uid lookup when lexical pass returns nothing, and returns weaker matches for long natural-language queries due to index limitations. This adds meaningful behavioral context.

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

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

The description is structured with purpose, alternative, tip, UID scheme, fallback behavior, and args. Although long, each section serves a distinct purpose and no sentence is wasted; the 'S3' typo is a minor blemish but doesn't detract.

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

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

For a 6-param tool with output schema, the description covers query semantics, UID formats, fallback behavior, parameter meanings, and return envelope. It also references external docs for deeper details. This is adequate for correct invocation.

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

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

Schema has 0% description coverage, but the description's Args section fully specifies all 6 parameters with types, examples (e.g., kinds comma-separated), and behavioral notes (e.g., NL queries degrade). This fully compensates for the schema gap.

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

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

The description clearly states the tool looks up symbols by a KNOWN short term, path, or uid, with a specific verb and resource. It explicitly distinguishes itself from cos_graph_search, which handles natural-language descriptions. The UID scheme adds further precision.

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

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

The description explicitly says when to use this tool (known term/path/uid) and when not to (natural-language descriptions, use cos_graph_search instead). It also provides a TIP about preferring short terms and explains the trade-off with long NL queries. This is clear when/when-not guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context: empty query = global PageRank, optional personalization, and the return format ('JSON envelope with nodes ranked'). This is sufficient beyond annotations.

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

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

The description is compact and well-structured: a one-line definition, a 'Use for' section, structured Args, and a Returns line. No redundant words or repeated schema details.

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

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

For a moderate-complexity tool with 5 optional parameters and an existing output schema, the description covers purpose, all parameters, and return shape. The 'use for' section provides application context, making it complete for an agent to decide and invoke correctly.

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

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

The schema provides zero description coverage (all params are just names with defaults), so the description carries full burden. It explains all five parameters: query (personalisation, empty=global), top (max nodes), kind (filter), damping (PageRank damping factor), iterations (power-iteration count). This adds rich meaning beyond the schema.

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

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

The description opens with 'PageRank — node importance, optionally personalised by query,' clearly identifying the tool as a node-importance ranking algorithm with personalization support. It distinguishes itself from sibling graph tools (e.g., cos_graph_centrality) by naming PageRank and listing concrete use cases.

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?

Three explicit use cases are given: knowledge condensation, query-personalised search ranking, and documentation sourcing. This provides clear context for when to use the tool, though it does not name alternatives or 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavioral context: raw repo paths are auto-resolved, the default 'kinds' behavior selects specific edge types per node kind, and the limit parameter caps results. No contradictions with annotations.

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

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

The description is front-loaded with a one-line purpose, followed by a well-organized Args section. Each parameter's documentation is dense but relevant. The 'R4-02' reference is a minor distraction but does not detract from overall 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?

For a graph tool with complex uid schemes and edge type selection, the description comprehensively covers required parameters, default behaviors, and parameter interactions. An output schema exists, so return structure is already specified and need not be repeated.

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 thoroughly explains each parameter: uid with a detailed scheme and examples, kinds with comma-separated edge types and per-node-kind defaults, and limit with a default value. This fully compensates for the lack of schema-level descriptions.

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

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

The description opens with a specific verb and resource: 'List inbound edges — "who references this?"'. This clearly defines the tool's function and distinguishes it from sibling graph tools like cos_graph_trace or cos_graph_impact, which focus on other aspects of graph traversal.

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?

Clear context is given: this tool is for finding who references a given node. It also explains that an empty 'kinds' parameter automatically selects appropriate edge types per node kind, offering concrete usage guidance. However, it does not explicitly mention alternatives or scenarios where another tool should be preferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds value by detailing what the plan covers (call-sites, docs, tests, strings) and mentions 'risk', giving extra context about the expected behavior beyond the annotations. No contradiction with annotations.

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

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

The description is short, front-loaded with the purpose, and uses a clean Args list. Every sentence contributes meaningful information with no redundancy. It is an example of efficient 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 the presence of an output schema and annotations, the description does not need to explain return values or safety. It covers the tool's purpose, all parameters, and the scope of the plan. This is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema provides only field names with no descriptions (0% coverage). The description fully compensates by explaining each parameter: uid's scheme formats and auto-resolution, new_name as replacement symbol name, and check_strings as an option to scan string literals. This is crucial for correct invocation and well above the baseline.

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

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

The description starts with 'Plan a rename — call-sites, docs, tests, strings, risk.' This clearly states the tool's function with a specific verb and resource, and it uniquely identifies what the tool covers. It is not a tautology and distinguishes itself from sibling graph tools by focusing on rename planning.

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 the use case: when you need to plan a rename and assess its impact across call-sites, docs, tests, and strings. It does not explicitly name alternatives or provide exclusion criteria, but the context is clear enough for an agent to select it for rename planning. A small deduction for not mentioning 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?

While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description enriches behavioral understanding by disclosing the exact fallback resolution sequence (direct uid → path/qualname → FTS5 → LIKE) and the return envelope with a 'strategy' field, which is beyond structured 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 well-structured with sections for purpose, usage, UID scheme, args, and return value. Every sentence contributes necessary information—no filler—while the front-loaded first line immediately conveys the tool's 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?

Given the tool's complexity (multiple UID formats, fuzzy resolution) and the absence of parameter descriptions in the schema, the description is remarkably complete. It covers the UID scheme, resolution order, all arguments, and return format, leaving no critical gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter's meaning and valid inputs. It details 'q' as natural language, label, path, or qualname; 'kinds' as a comma-separated filter; and 'top' with max results and default. This is essential given the minimal schema metadata.

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

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

The description opens with a specific verb and resource: 'Resolve a natural-language label, path, or partial uid to canonical uids.' This clearly states the tool's purpose and differentiates it from siblings by positioning it as the UID resolver to use before other cos_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?

Explicitly states when to use: 'Use this BEFORE other cos_graph_* tools when you don't know the exact uid.' It also details the resolution strategy order, adding practical guidance on how the tool handles different query types.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds meaningful behavioral context beyond annotations: it explains the search strategy (semantic + lexical + centrality) and the constrained range for top_k. It does not describe return format or pagination, but the output schema covers return structure, so no significant gap remains.

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: a single purpose statement, one alternative-direction sentence, and two terse parameter explanations. Every sentence earns its place, and the most important information (what it does) is front-loaded. No filler or redundant content.

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

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

Given the tool's moderate complexity (two params, output schema present, generous sibling context), the description covers purpose, usage boundaries, parameter semantics, and relationships to alternatives. The output schema handles return-value documentation. The description is complete for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly: 'query' is explained as 'Natural-language or code-ish query' with an example, and 'top_k' is given a numeric range (1–50) that is not present in the schema. This adds real semantic value beyond the bare type and default.

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 ('Find') and resource ('code symbols'), and clearly indicates the input type (natural-language description) and approach (semantic + lexical + centrality). It also distinguishes itself from the sibling tool cos_graph_query by explicitly scoping to natural-language searches, making its purpose unambiguous.

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

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

The description provides an explicit usage guideline: 'For a KNOWN name / path / uid, use cos_graph_query instead.' This clearly tells when NOT to use this tool and points to the correct alternative. This is exactly the kind of guidance that helps an agent select correctly among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description builds on that by adding concrete behavior: difflib baseline, auto-resolution of raw repo paths to code:file:/doc:file:/folder: namespaces, and a confidence threshold. This exceeds the structured hints without contradicting them, though it does not detail output shape or error 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 a tight docstring with a one-sentence purpose followed by structured, scannable argument definitions. Every sentence adds value 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 the rich annotations and existing output schema, the description covers input semantics and safety sufficiently. The main gap is lack of mention of behavior when uid is not found or confidence_min is outside bounds, but the tool is still well-positioned for correct selection and invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden for parameter meaning. It defines uid as fully-qualified with auto-resolution, top_k as the number of similar nodes, and confidence_min as a 0.0–1.0 similarity threshold. This adds substantial semantics beyond the bare schema 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 opens with a specific action: 'Return the top-K nodes most similar to `uid`', naming the resource (nodes), the operation (similarity retrieval), and the algorithm (difflib baseline). This clearly distinguishes it from sibling graph tools like cos_graph_search or cos_graph_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 provides how to call the tool (uid resolution, top_k, confidence_min) but gives no explicit guidance on when to use this tool versus alternatives. The only cross-reference, 'see cos_graph_impact for scheme', is about UID format, not usage selection or exclusions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing that results are heuristic ('Candidates only') and explicitly excluding shell scripts ('Shell excluded'), which is beyond what annotations provide. It does not discuss auth or rate limits, but these are less critical for a read-only query.

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 Args and Returns sections, front-loading the core purpose. Each sentence provides necessary information—purpose, limitations, parameter details, and return format—without redundancy. It is concise yet informative.

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

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

For a read-only graph analysis tool with an output schema, the description is nearly complete. It covers the purpose, parameters, return envelope, and the nuance of indirect exercise. It could mention whether any prerequisites exist (e.g., graph must be pre-built), but this is not essential for basic use.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining both parameters: 'kind: Optional filter — function | method | class. Empty = all three.' and 'top: Max returned (default 50, max 500).' This adds meaning beyond the bare schema field names and 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 tool's function: 'List prod function/method/class with zero inbound edge from any test (untested symbols).' This uses a specific verb ('List'), a specific resource (prod function/method/class), and a specific condition (zero inbound edge from any test), making it distinct from sibling 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?

It provides context on when to use this tool by explaining that 'Candidates only: indirect exercise (CLI / fixtures / dynamic dispatch) may not appear as a graph edge. Shell excluded (no call-graph).' This clarifies the tool's limitations and interpretive caution. However, it does not explicitly contrast with alternative tools or 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context such as the auto-resolution of entry_uid (file → code:file: then entry-point heuristic), the meaning of terminal edge labels, and the max_steps cap. It does not contradict annotations, but omits details about include_external 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 a one-line summary followed by a focused Args list. It is concise, front-loaded, and provides necessary parameter details 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?

The tool is moderately complex with four parameters and an output schema. The description covers the required entry_uid and the key behavioral controls (terminals, max_steps) well, and defers to cos_graph_query for uid resolution. The missing include_external parameter and lack of output format discussion (though output schema exists) keep it from being fully complete.

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

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

The schema has 0% description coverage, so the description's Args section is essential. It explains entry_uid with an example and resolution logic, defines terminals as edge labels, and describes max_steps. However, it omits the include_external parameter, leaving it undocumented in both schema and description.

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

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

The description states 'Forward execution walk from `entry_uid` until terminals', which clearly identifies the tool as a forward graph traversal from a given uid. It includes an example uid format and differentiates from sibling tools like cos_graph_query and cos_graph_path by focusing on execution tracing.

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

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

It provides clear usage context: use when you need to trace execution forward from a known entry_uid. It advises running cos_graph_query first if unsure, which is an explicit prerequisite. However, it does not name alternative traversal tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the exact statistics returned and noting the return type (JSON string with keys tables, schema_version, fts5_available, db_size_bytes, rag). This goes beyond annotations and helps the agent understand the tool's output.

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

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

The description is concise and front-loaded: a one-line summary, a usage sentence, and a Returns block. There is no redundant filler. The Returns block is slightly redundant given the output schema but provides immediate clarity for the agent.

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

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

For a zero-parameter, read-only health-check tool, the description is complete. It covers what the tool does, when to use it, and what it returns, while annotations cover safety and idempotency. No gaps are evident, and the output schema and return key list make the contract clear.

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

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

The input schema has zero parameters, so description cannot add meaning beyond the schema. Baseline for 0 params is 4, and the description correctly does not invent parameter details. It does not confuse the agent about arguments.

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 that the tool returns database health stats, listing specific metrics (row counts per table, schema version, DB size, FTS5 availability, embeddings status). This is a specific verb+resource combination that distinguishes it from sibling tools focused on tasks, graphs, and retrieval. The phrase 'verify the thinking_os database is operational' reinforces its purpose.

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

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

The description explicitly says 'Use this tool to verify the thinking_os database is operational and to get a quick summary of stored data volume,' providing clear context on when to use it. It does not mention alternatives or exclusions, but for a health-check tool with no parameters, this 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?

Annotations indicate a non-read-only, idempotent operation. The description adds a concrete side effect: inserting new patterns into learned_patterns with calculated confidence. It does not contradict the annotations and provides useful behavioral context beyond them.

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

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

The description is concise and well-structured, with a clear purpose, effect, args section, and return type. It contains no redundant information and each sentence serves a purpose.

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

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

For a single-parameter tool with an output schema, the description covers the core aspects: purpose, detected patterns, insertion behavior, parameter meaning, and return format. It could be more detailed about the analysis stats, but is largely complete given the available structured data.

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 explains the only parameter (min_occurrences) as the minimum occurrences to consider a pattern, with a default of 3. This adds meaningful semantic information beyond the raw schema type and default.

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 scans task outcomes to discover recurring patterns, listing specific pattern types (domain_rework, skill_correlation, complexity_mismatch). It also mentions inserting into learned_patterns, distinguishing it as an extraction/write tool, though it doesn't explicitly compare to sibling learning tools like cos_learn_suggest.

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

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

The description implies usage for discovering patterns from task outcomes, but provides no explicit guidance on when to use this tool versus alternatives such as cos_learn_suggest or cos_learn_validate. It lacks exclusions or alternative recommendations.

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

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

The description states it 'Creates a high-impact learned pattern' and discloses the return format (status, history_id, pattern_id), adding value beyond the annotations. The annotations already indicate a write operation (readOnlyHint false), and the description aligns with that without contradicting it.

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-organized: purpose, trigger, bullet points of what to capture, args, and returns. Each section is concise and serves a clear function, though slightly longer than strictly necessary.

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 purpose, usage context, parameters, and return value. It does not address the relationship with other learn tools or clarify the optionality of key_insight, but the presence of an output schema and annotations partially compensates. Overall it is sufficiently complete for an agent to select and invoke the tool.

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

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

All four parameters are described with brief explanations, which is critical given 0% schema coverage. However, the description marks key_insight as 'required' while the schema lists it as optional with a default, and fails to note that task_id is the actual required parameter. This inconsistency could mislead the agent during invocation.

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

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

The description opens with 'Record what was learned from a difficult task (breakthrough narrative),' providing a specific verb and resource. It clearly distinguishes itself from sibling learn tools by focusing on post-rework success narratives and capturing failure/success/insight.

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

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

It gives an explicit trigger: 'Call this after a rework→success breakthrough.' This tells the agent exactly when to use it. However, it does not mention alternatives or exclusions, so it lacks the explicit 'when not to use' that would merit 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?

Beyond the readOnly and idempotent annotations, the description explains the spaced repetition mechanism (fading patterns with 0.2-0.4 confidence) and the return format, giving valuable insight into how results are prioritized. This goes well beyond the annotations.

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

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

The description is well-structured and concise: a clear one-sentence purpose, a single behavioral note, then a structured Args list and Returns. 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?

For a read-only tool with four optional parameters and an output schema, the description covers the purpose, behavioral details, parameter semantics, and return format. The only missing detail is a fuller definition of 'current task context', but that is likely implicit. It is complete enough for reliable invocation.

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

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

The schema has zero property descriptions, so the Args section is essential. It provides meaningful explanations for each parameter, including examples for domain and task_type and a range for limit. The complexity parameter could be more explicit about allowed values, but overall it compensates well for the schema gap.

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

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

The description clearly states the tool returns relevant patterns for the current task context, specifying the action and resource. It distinguishes itself from siblings like cos_learn_extract and cos_learn_validate by focusing on suggestion rather than extraction or validation.

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

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

The description provides clear context by mentioning 'current task context' and the spaced repetition prioritization, indicating when to use it. However, it does not explicitly contrast with alternatives or state when not to use, preventing 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?

Beyond the annotations (which only indicate readOnlyHint=false), the description details the behavioral mechanics: it updates confidence using 'brain-inspired formulas' with specifics like LTP diminishing returns and LTD proportional penalties. It also discloses the return value (JSON with old/new confidence and validation status). This adds rich context beyond what annotations provide.

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

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

The description is well-structured and concise: a single-sentence purpose, a compact bullet list for formulas, followed by Args and Returns sections. Every sentence earns its place, and the main action is front-loaded. It is neither bloated nor under-specified.

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

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

Given this is a simple two-parameter tool with an output schema (has output schema: true), the description is complete. It covers purpose, behavioral nuance, parameter semantics, and return format. There is no missing critical information for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description fully carries parameter meaning. It explains pattern_id as 'ID in learned_patterns table' and was_helpful as 'Whether the pattern was useful (default True).' This is precise and adds meaning beyond the bare type/default in the schema.

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

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

The description opens with a clear, specific action: 'Record whether a suggested pattern was helpful.' This distinct verb-resource pair unambiguously states the tool's function and distinguishes it from siblings like cos_learn_suggest (which suggests) and cos_learn_extract (which extracts).

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 context is clearly implied: this is for providing feedback on a suggested pattern, whether it was helpful or not. However, it does not explicitly name alternatives (e.g., 'use cos_learn_suggest to generate suggestions') or state when not to use it. This is clear context without explicit exclusions, so a 4 is appropriate.

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