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

No annotations exist, so the description carries the full burden. It explicitly declares 'Read-only,' describes the exact return shape, explains that 'status="skipped"' indicates a missing prerequisite, and clarifies the raw-versus-formatted result distinction. This is substantial behavioral disclosure, though it stops short of describing error behavior or potential delays.

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 with a front-loaded summary, a prominent return-format warning, and clear Args/Returns sections. It is concise overall, though there is minor redundancy between the first paragraph listing the dict fields and the Returns section repeating 'DepCheckResult fields via asdict.'

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 an output schema exists and both parameters are fully documented in the schema, the description covers the essential additional context: read-only behavior, raw vs. formatted output, status interpretation, and parameter selection. It lacks edge-case guidance (e.g., what happens if both params are provided) but is complete enough for an agent to call it correctly in normal cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context about mutual exclusivity ('Give one of the two, not both') and auto-detection of project_root from CWD, but the argument text closely mirrors what is already in the schema. It does not meaningfully compensate beyond the schema, so no higher score is warranted.

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

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

States a specific verb and resource: 'Run the full dependency audit.' It adds 'Read-only' and clarifies that it returns raw per-check dicts, not the formatted 'doctor' table, which distinguishes it from potential sibling tools like get_environment_status or check_ollama. The purpose is immediately recognizable and 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?

Usage context is implied: call this when you need a dependency audit. It gives guidance on choosing between 'project' and 'project_root' and refers to list_projects for project names, but it never explicitly names alternatives or says when NOT to use this tool. No sibling differentiation is provided, so the agent must infer selection from the purpose.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it meets it with 'Read-only: yes. No side effects.' It also exposes the complete status/return behavior, including error/disabled states, external chat API replacement, and conditional fields. It does not mention timeout or network-failure behavior explicitly, but the 'error' status and message field cover that outcome.

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 purpose and usage before moving to arguments and return values, which is good structure. The returns block is long but justified because there is no output schema to document the response shape. The only minor redundancy is repeating the schema parameter descriptions nearly verbatim.

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 fully compensates for the missing output schema by listing the complete return dict with field types and meanings, including optional/conditional fields. It also documents parameter selection rules, auto-detection, and mutual exclusivity. Nothing essential for invoking check_ollama correctly is missing.

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

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

Both parameters are already fully documented in the input schema with 100% coverage, so the description adds little beyond restating the same project_root/project semantics. A baseline of 3 is appropriate because the schema carries the semantic weight and no additional syntax or format details are needed.

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

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

The first sentence states a specific verb ('Check') and resource ('LLM backend... embedding/chat model installed'), which makes the tool's purpose unmistakable. It also names the sibling tools it should precede, helping distinguish it from search/analysis tools. This goes beyond a vague restatement of the tool name.

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

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

The description explicitly says 'Call before smart_search, semantic_search, or explain_symbol' and includes the on-demand fallback condition, which is strong usage guidance. It does not explicitly discuss alternatives like check_dependencies or get_environment_status, so the when-not-to-use guidance is slightly incomplete. Overall, the timing and conditional exception are clear enough for correct agent routing.

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

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

With no annotations provided, the description carries the full burden and meets it: it discloses the write location, that it does NOT modify global/shared config, that it makes a test API call, that the call is skipped when LLM is disabled, and that external chat_api_base URLs send source-code snippets to that host.

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 opening, security warning, Args list, and Returns dict. Despite covering nine parameters, it stays dense and front-loads the most important behavioral facts before the parameter list.

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

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

Given the absence of an output schema and annotations, this is complete: it explains side effects, conditional test behavior, security implications, and the full return dict shape with keys for success/error cases. An agent can invoke it without needing additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The Args block is mostly a condensed restatement of the schema's parameter descriptions; it adds a 'Bearer token' qualifier for chat_api_key, but for chat_api_base it even defers to 'description for format details' without including those details in the description body.

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 and resource — 'Configure LLM settings' — and immediately clarifies the precise mutation target: 'Writes to <project>/.fw-context/local.toml ONLY'. It also states what it does not affect, which clearly separates it from the surrounding read/search sibling tools.

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

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

It gives clear context for when to call it (per-developer LLM configuration) and explicit non-targets (global config, shared config.toml). It also points to list_projects for project IDs and warns to prefer local Ollama/internal proxies; it stops short of naming an alternative configuration tool because none exists among the siblings.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It states 'Read-only. No side effects,' explains the pre-computed versus on-demand LLM fallback, and details warning, stale, ambiguous, failure, and outside-root candidate behaviors.

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

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

The description is well-structured with a clear opening, routing section, Args list, and Returns breakdown. However, it repeats the pre-computed/on-demand fallback sentence twice and restates 'It is separate from warning, which the LLM error paths use' for both stale and ambiguous warnings, so a small amount of tightening was possible.

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

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

There is no output schema, so the description must explain return values, and it does so comprehensively: dict keys, macro fallback fields, warning semantics, stale-file markers, ambiguous matches, and failure candidates. For a tool with this behavioral complexity, nothing essential is missing.

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

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

Though schema coverage is 100%, the description adds significant meaning beyond the schema: examples like 'uart_init' and 'ModemMsg::send', auto-detection of project_root, the mutual exclusivity of project and project_root, the conditional use of context_lines, and the per-build semantics of variant.

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: 'Explain what a C/C++ symbol does in plain English — libclang-aware analysis.' It distinguishes itself from sibling tools such as lookup_symbol and get_symbol_context by stating that it returns an explanation, not just metadata or raw 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?

Explicit routing is provided: 'For raw source code use get_source. For symbol metadata without explanation use lookup_symbol. For body + callers + callees use get_symbol_context.' It also gives concrete parameter guidance, such as when to use project versus project_root and when image is required.

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

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

With no annotations, the description carries the full burden and delivers richly: it discloses read-only/no side effects, BFS traversal, deduplication at shortest distance, the ambiguous-name resolution limitation, the error/info fallback dict, the absence of line numbers and why, and multi-match warning behavior. This goes far beyond a typical tool definition.

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 appropriately sized for a complex tool with 7 parameters and multiple edge cases. It is front-loaded with the core purpose and edge types, then flows logically into usage, limitations, parameters, and return format. Each section earns its place with no filler; bold headers and paragraphs improve scannability.

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 an output schema, the description adds vital context an agent needs: the warning/error/info dict shapes, the no-line-number behavior, deduplication, multi-symbol ambiguity resolution, and build/variant relationships. For a tool with this complexity, nothing essential is left unexplained.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic context beyond the schema: 'Give one of the two, not both' for project/project_root, 'One query answers for ONE build', and 'Required when the variant holds several' for image. It also clarifies auto-detection and qualification nuances. These additions push it above baseline but not to 5 since much of the Args section repeats 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 opens with a specific verb and resource: 'Find all transitive C/C++ callers — who calls *name*, directly or indirectly', and details the traversal through libclang call graphs with specific edge types. It clearly differentiates itself from sibling tools by naming find_callers and find_callees_recursive and stating their different scopes.

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

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

Explicitly states when to use the tool: 'Use for impact analysis: if I change this function, how far does the ripple go?' Then gives direct alternatives with conditions: 'For a flat, single-level caller list use find_callers (faster). For the reverse direction use find_callees_recursive.' Also recommends verification tools (search_bodies, find_indirect_targets) for a known limitation. This is model guidance.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It explicitly states 'Read-only. No side effects.', discloses the reference index requirement, details the ambiguous-name resolution limitation, notes deduplication by shortest distance, explains the warning dict for multiple matches, and describes the non-empty return behavior (error/info dicts). It also clarifies why no line is returned. These are rich behavioral disclosures beyond any structured fields.

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 long but well-structured: purpose first, then usage, edge types, limitation, alternatives, args, returns. It is front-loaded and each section adds necessary detail for a complex tool. However, the Args section largely duplicates the input schema descriptions, adding redundancy that could be trimmed without losing information. Still, the organization earns a high score.

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

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

For a tool with 7 parameters, an output schema, and complex edge cases, the description is complete. It covers return value structure, error/info cases, multi-match warnings, depth semantics, and prerequisites. The output schema exists, but the description still explains anticipated edge cases and usage contexts, leaving no important gap for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the Args section repeats the schema descriptions almost verbatim (e.g., project_root, project, max_depth). The description does not add significant semantic value beyond the schema; it clarifies the alternative relationship between project and project_root, but that is already in the schema. Baseline 3 is appropriate because the schema already documents all parameters well.

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

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

The description states a specific verb and resource: 'Find all transitive C/C++ callees — what *name* calls, directly or indirectly'. It specifies the call graph engine (libclang) and edge types, distinguishing it clearly from siblings like find_callers (direct only), get_symbol_context (faster flat list for direct callees), and find_all_callers_recursive (reverse direction).

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

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

The description gives explicit usage guidance: 'Use for dependency analysis: "what does this function depend on to do its job?"' It names alternatives and when to use them: 'For direct callees only, get_symbol_context gives a faster flat list... For the reverse direction use find_all_callers_recursive.' It also advises fallback verification via search_bodies when a missing callee is suspected. This fully covers when-to-use and when-not-to-use.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: read-only/no side effects, index requirement, macro fallback behavior, pagination format, ambiguity warnings, virtual-method override behavior, and the never-empty error/info contract are all disclosed. This goes far beyond the structured fields and gives the agent a reliable model of what happens.

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 long but well-structured with clear sections and bullet-like formatting. Nearly every sentence earns its place given the complexity of the tool, though some repetition of schema parameter details could be trimmed. Front-loading the core purpose and usage guidance is effective.

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 an output schema being present, the description adds a detailed Returns section covering pagination, macro results, ambiguity warnings, and virtual-method callers. It also documents the never-empty error/info contract. For a tool with this behavioral complexity and seven parameters, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra context beyond the schema: the three-tier name resolution, the pagination notice naming the offset, the project vs project_root relationship, and the multi-build variant/image distinctions. It does not merely repeat 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 specific verb and resource ('Find who calls a C/C++ function') and immediately distinguishes direct vs. indirect calls, explicitly naming sibling tools for other needs. This lets an agent separate find_callers from find_references, find_call_path, and find_all_callers_recursive without opening schemas.

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 explicit when-to-use guidance ('Use when you need a quick, flat list of immediate callers') and names the alternatives for transitive calls, all references, and path finding. It also states requirements such as the reference index and the one-hop limitation, leaving no ambiguity about when this tool is the right choice.

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

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

With no annotations provided, the description carries the full burden. It discloses read-only status, no side effects, and prerequisites (symbols in index, refs enabled). It details limitations (dispatch bridge skipping, ambiguous fallback name conservatism, global constructor synthetic node) and explains the node-budget behavior of max_depth. This is far beyond typical descriptions and leaves no critical behavioral ambiguity.

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

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

The description is lengthy but logically structured with headers (Edge types, Limitations, empty-result guidance, alternatives, args). Every section adds necessary detail for a complex tool. It is front-loaded with the core purpose and returns structure, and while a bit long, it is not bloated; each sentence earns its place. Slightly trimmed could earn a 5, but this is still strong.

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 fully covers the return format (at most 5 paths, each with depth, chain, target_usr; warning and info dicts; never empty) and edge cases (overloaded symbols, ambiguous names). It also includes troubleshooting guidance, prerequisites, and limitations. For a tool with 7 parameters and no annotations, this is remarkably 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?

Even though schema coverage is 100%, the description adds substantial meaning: max_depth's lack of clamping and its interaction with the 5000-expansion node budget, project vs. project_root as mutual alternatives, image required when variant holds multiple images, and the note that one query answers for one build. These nuances are not in the schema and materially improve invocation correctness.

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 precise verb+resource statement: 'Find call paths between two C/C++ functions via BFS in the libclang call graph.' It names the specific edge types (function pointers, ISRs, implicit constructors, dispatch) and contrasts with siblings like find_all_callers_recursive and find_callees_recursive, making the tool's unique scope unmistakable.

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 the intended use case ('how does A reach B?') and gives a concrete example. It also names alternatives for one-sided exploration (find_all_callers_recursive, find_callees_recursive) and exact verification (find_callers, find_references), and includes troubleshooting steps for empty results. This is exemplary when-to-use vs. when-not-to guidance.

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

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

With no annotations, the description carries the full behavioral burden and succeeds: it states 'Read-only. No side effects', requires the reference index, defines the two statuses, and discloses known false positives and the single-layer non-reachability limitation. This is far beyond what structured annotations would 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-organized with bold headings, clear bullets, and front-loaded purpose. It is somewhat long and the Args section largely duplicates the input schema, but the tool is complex enough that the extra caveats and status semantics earn most of their place.

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

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

For a complex tool with no annotations, the description is remarkably complete: it covers output shape, the never-empty info replacement, prerequisites, read-only behavior, filtering semantics, pagination, and false positives. Nothing needed for safe invocation is materially 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some genuinely useful clarifications beyond the schema: project_root and project are mutually exclusive, offset pagination references a page notice, and exclude_paths is a user-supplied parameter rather than config. These additions justify a small bump above baseline.

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

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

The description opens with a specific verb and resource: 'Find C/C++ functions that are defined but never called', and frames the tool as global, index-based dead code detection. It also distinguishes itself from text-based search and names related siblings like find_callees_recursive and find_indirect_targets, so an agent can select it correctly.

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

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

The description explicitly tells the agent when to use this tool versus alternatives: for transitive reachability it should use find_callees_recursive, and for possibly_dead hits it should verify with find_indirect_targets. It also explains that text-based search cannot determine actual reachability, which is a strong when/why signal.

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

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

With no annotations, the description carries the full disclosure burden. It explicitly says 'Read-only. No side effects.', declares the reference index requirement, reveals the never-empty 'info' sentinel, and warns that one query answers for one build. These are substantive behavioral disclosures beyond the schema.

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

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

The description is long but logically structured: purpose, usage, parameters, return format. It front-loads the main purpose and keeps related caveats in the parameter/return sections. Some repetition exists ('architectural weight' twice), but every block earns its place for a complex tool.

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

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

For an 8-parameter tool with no annotations, this description is unusually complete: it covers prerequisites, defaults, output shape, the empty-result sentinel, build/variant specifics, and follow-up paths. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly repeats schema text, adding minor context like the page-notice offset hint and the project/project_root mutual exclusivity. It confirms the schema but does not meaningfully extend 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 opens with a specific verb and resource: 'Find the most-called C/C++ functions ranked by caller count' and names the mechanism (libclang call-graph hotspot detection). It clearly distinguishes this from Text-based search and from sibling tools like find_callers, making selection unambiguous.

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

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

It explicitly states the intended use ('high-level impact assessment'), notes that text search cannot aggregate caller stats, and gives concrete follow-up alternatives (find_callers, find_all_callers_recursive). It does not enumerate all negative cases for every sibling, but the usage context is clear and actionable.

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

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

No annotations are present, so the description carries the full burden. It discloses that the tool is read-only with no side effects, explains the libclang-backed mechanism and its limitation versus text search, and reveals the non-obvious return contract: results are never empty and may contain an `error` or `info` key that must be checked.

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 long but every sentence earns its place: purpose, examples, sibling differentiation, prerequisites, parameter semantics, and return format are each addressed without fluff or repetition. The most critical scoping information is front-loaded before the parameter 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?

Given the tool's complexity (6 parameters, output schema, cross-tool distinctions), the description is remarkably complete. It covers prerequisites, parameter alternatives, error behavior, return dict fields, and expected usage, leaving no obvious gap an agent would need to guess about.

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?

Although the schema already documents all parameters (100% coverage), the description adds substantial meaning: the three-tier resolution strategy for `name`, the mutual-exclusivity rule for `project` vs `project_root`, the note that one query answers for ONE build for `variant`, the per-image program semantics for `image`, and the maximum limit of 200. These details go well beyond the schema text.

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 precise verb+resource: 'Find indirect call sites where a C/C++ function pointer field or variable is invoked.' It further clarifies with concrete examples like `driver.onData(buf, len)` and explicitly differentiates this tool from `find_callers` and `find_references`, so an agent can immediately tell them apart.

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 states exactly when to use the tool ('where is this function pointer invoked?') and when not to, naming the alternatives: `find_callers` for 'who calls this function?' and `find_references` for 'where is this symbol read or assigned?'. It also directs the reverse query to `find_indirect_targets` and notes the prerequisite of the reference index.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses read-only/no side effects, the reference-index requirement, null call_file/call_line for assignments without call sites, fallback notes via _note for template-obscured callees, and the never-empty error/info result convention. This is unusually transparent.

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

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

The description is long but well structured: a front-loaded purpose, followed by usage/parameter notes, then return semantics. Almost every sentence earns its place, though some redundancy exists (e.g. 'no side effects' vs 'read-only') and the return-list detail is extensive given an output schema exists.

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 complex tool with no annotations, six parameters, and rich output semantics, the description is complete. It covers purpose, prerequisites, parameter relationships, output shape, special cases, error handling, and the reverse sibling tool. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter well. The description adds extra meaning beyond the schema: 'Uses three-tier resolution' for name, 'One query answers for ONE build' for variant, and the exclusive-alternative rule for project vs project_root. That pushes it above the baseline 3.

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

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

The description states a specific verb and resource ('Find functions assigned to a C/C++ function pointer field or variable'), explains the libclang/USR mechanism, and explicitly distinguishes itself from the sibling find_indirect_call_sites by naming the reverse query. An agent can tell exactly what this tool does compared to nearby tools.

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

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

The description gives clear conditions: it uses the reference index, handles the reverse case by pointing to find_indirect_call_sites, and explains why text-based search cannot resolve these relations. Parameter guidance such as 'Give one of the two, not both' for project and project_root further clarifies when to use which alternative.

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

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

No annotations are provided, so the description carries the full burden — and it does so thoroughly. It states 'Read-only. No side effects,' discloses the macro fallback, multi-symbol warnings, virtual-method peer behavior, paging semantics, and the always-nonempty error/info response. These are exactly the behavioral traits an agent needs to invoke and interpret the tool safely.

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 long but well-structured with clear sections for purpose, args, returns, and warnings. Some redundancy exists between the opening list of reference kinds and the later 'including call sites, variable reads...' sentence, so it is not maximally tight. Still, nearly every sentence carries operational value for a complex tool.

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

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

For a tool with 7 parametersaint, no annotations, and an output schema, the description is remarkably complete. It covers required inputs, optional project selection, paging, all return shapes, ref_kind enumerations, macro fallback, ambiguity handling, virtual-method behavior, and error/info cases. An agent has enough context to call this correctly in almost any scenario.

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

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

Schema description coverage is 100%, so the baseline is 3 even with no additional parameter info. The description does add a few useful details beyond the schema: limit has a documented max of 200, offset's page-notice mechanism is explained, and the project/project_root exclusivity is reinforced. Much of the Args section repeats schema text, which prevents a 5, but the added mechanics elevate it.

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

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

The description names a specific verb and resource: 'Find ALL references to a C/C++ symbol.' It enumerates covered reference kinds (calls, reads, member accesses, function-pointer registrations, template references, macro usages), which distinguishes it from sibling tools like find_callers or find_variables. The libclang-powered distinction also clarifies why it goes beyond text 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 explicitly routes usage: 'For direct callers only use find_callers. For transitive callers use find_all_callers_recursive. For call paths between two symbols use find_call_path.' It also explains when fallback macro lookup occurs, when to pass project vs project_root, and when image is required. This leaves little to inference.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses that the tool is 'Read-only. No side effects,' explains legacy index handling, the global/local split, error and warning keys, and the reference list format. This is unusually complete behavioral 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 long, but the tool is complex with 7 parameters and non-obvious return semantics. It is well organized with distinct sections for intro, usage, args, and returns. Some repetition exists between the Args section and the input schema, but the additional context earns its place.

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

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

The description covers all essential calling context: matching behavior, kind filtering, project selection, build variant/image constraints, error/empty-result handling, and return shape. Even with no annotations and a large sibling list, an agent has enough information to decide when and how 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 100%, so the baseline is 3, but the description adds useful meaning beyond the schema: it documents that the legacy kind 'variable' is also accepted, emphasizes the project/project_root exclusivity, and explains the one-query-per-build behavior for variant/image. These extras justify a small uplift.

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: 'Find C/C++ variables by name or prefix and trace who reads or writes them through the call graph.' It clearly distinguishes itself from siblings like find_references, search_code, and lookup_symbol by stating its variable-tracing scope and its global/local split.

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 it ('Use when you need to understand shared state, find who modifies a global variable...') and names alternatives with conditions ('For general symbol search use search_code or lookup_symbol', 'For all references... use find_references'). It also explains the local-variable niche versus search_code in detail.

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

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

No annotations are provided, so the description carries the full burden. It discloses read-only behavior ('Read-only. No side effects.'), the requirement for the reference index, the non-empty result contract (error/info dicts replace results), and the rationale for path placement on methods rather than classes. It doesn't mention rate limits or failure modes beyond the error key, but the disclosed behaviors are substantial and useful.

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

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

The description is well-structured with clear sections: purpose, example, return format, and usage notes. It is longer than minimal but every section earns its place — the return format detail is essential for a tool with a complex nested output. The front-loading of purpose and the sibling routing early in the text is effective. Slight redundancy exists ('adapter pattern detection' and 'adapter/wrapper architecture' are repeated), but it's not wasteful.

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 6 parameters, a complex nested output schema, and no annotations. The description covers the tool's purpose, prerequisites, parameter selection guidance, return structure, and edge-case behavior (error/info dicts). The output schema exists, so the description doesn't need to explain every field, but it adds the critical 'path sits on the method, not on the class' insight and the 'never empty' contract. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between project and project_root ('alternative to project_root... Give one of the two, not both'), clarifying that variant answers for ONE build, and giving concrete examples for class_name. The limit's max is already in the schema, but the description reinforces it. This exceeds 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 states a specific verb and resource: 'Find C/C++ wrapper classes that call methods of a driver class' and immediately distinguishes it from text-based search and sibling tools. It names the exact pattern (adapter detection) and gives a concrete example (UART wraps UART_DRIVER), making the tool's purpose unmistakable.

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 vs alternatives: 'For the reverse perspective — finding who calls a specific driver method — use find_callers. For class member listing use get_class_members.' It also states the prerequisite (requires the reference index) and explains why text-based search is insufficient. This is exemplary routing 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 exist, so the description carries the full burden — and it discloses far beyond a typical definition: read-only and spawns no subprocess, the failure case sets NO status and returns error alone (explicitly warning a reader not to wait for status == 'error'), UTC-vs-local-time comparison traps, the row_format_mismatch semantics, and the meaning of empty memory lists ('not recorded, never no memory'). Nothing about behavior is hidden.

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?

Excellent front-loading — the purpose, role, and read-only/spawns-no-subprocess facts come first, and the status decision tree is the second block. The Returns section is clearly labeled and organized. However, the description is extremely long (several thousand words) with some redundancy, such as the 'Four conditions set reindex_needed' paragraph restating the status section, and the verbose defines/assembly-file measurement aside. Almost everything is substantive, but it is heavier 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?

With no output schema and a very rich return value, the description carries the full burden of documenting results, and it does so exhaustively: every status value, the error-only dict, the memory region origin/length semantics, the defines scope caveat, and the reduced result shape for uninitialized projects. Nothing an agent needs to interpret a response is left unexplained.

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

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

Schema coverage is 100% and the schema descriptions are already detailed, so baseline is 3. The description adds genuine value beyond the schema: the mutual-exclusivity rule ('Give one of the two, not both' for project vs project_root) and the correctness guarantee that modified_files_count is accurate in both fast modes. That interaction-level semantics pushes it above baseline, though not dramatically.

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?

Opens with a specific verb-resource pair ('Return metadata about the most recently indexed build configuration') and adds an explicit role marker ('MANDATORY FIRST CALL... check index health before using any other fw-context tools'). This immediately distinguishes it from every sibling search/query tool and states what it is not (a search or mutation tool).

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

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

Provides exhaustive when-to-use guidance: it is the mandatory first call, and it gives a full decision tree on the status field — what command to run for 'no_index', 'not_initialized', and each 'reindex_needed' reason, plus explicit do-NOT guidance ('Do NOT run a reindex' for client_restart_required). It names sibling alternatives (list_projects, list_variants) for adjacent needs and tells when to pass fast=False.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read-only. No side effects.' and describes the return dict structure including an error field on failure. It also mentions that members are grouped by kind, which is a behavioral trait. However, it doesn't explicitly state what happens for a class that doesn't exist beyond the generic error, nor does it address potential size or performance considerations, so it's not fully exhaustive but quite transparent.

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

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

The description is longer than a simple one-liner but is well-structured with clear sections: purpose, grouping behavior, alternatives, arguments, and return format. It front-loads the core purpose and then provides necessary detail without redundancy. Each sentence earns its place, making it appropriately sized for a tool with 5 parameters and a nested return 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?

The description covers the return schema explicitly, including the error case, and explains the grouping logic. It also provides routing to sibling tools for different needs. Given that there is no output schema, the description fully compensates by detailing the dict structure. For a C/C++ codebase tool with this complexity, nothing essential is missing 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?

The schema already provides descriptions for all parameters (100% coverage), so the baseline is 3. The description goes beyond by giving concrete examples for class_name, explaining the project vs project_root relationship with 'Give one of the two, not both,' and clarifying that variant and image are for multi-build projects. This adds meaningful usage semantics that the schema alone doesn't convey.

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: 'Return all methods, fields, and nested types of a C/C++ class/struct'. It clearly distinguishes itself from siblings by naming alternatives like get_inheritance_chain and get_symbol_context, and clarifies it works for C structs too. This leaves no ambiguity about what the tool does.

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

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

The description explicitly states when to use alternative tools: 'For inheritance hierarchy use get_inheritance_chain. For individual method details use get_symbol_context.' It also notes the tool works for C structs, implying when it is appropriate. It gives clear context and exclusions, so an agent knows when to pick this tool over others.

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 present, the description carries the full burden, and it does this well: it labels the tool 'Read-only', explains skipped-status semantics, documents the truncated dependency check when uninitialized, and discloses the before-init compile_db behavior. This goes far beyond a generic 'get status' phrasing.

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 long but necessarily so, given the complex aggregate output and absent output schema. It is well structured with a front-loaded summary, bullets for the five domains, and dedicated Args/Returns sections. Every sentence contributes useful information.

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

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

For a tool with no output schema and a multi-domain return value, the description is remarkably complete: it documents every returned field, the uninitialized-project behavior, and optional action fields. An agent has enough to call it correctly and interpret its result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful conflict guidance: 'Give one of the two, not both,' and clarifies when to use project vs project_root. This is useful semantic information not fully enforced by 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 starts with a concrete verb and resource: 'Return the complete project environment status in one call.' It further defines the aggregation of five named domains, which clearly distinguishes it from narrower sibling tools like check_dependencies or check_ollama.

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

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

It explicitly frames the tool as the session-start aggregate call: 'so the LLM can see everything at session start without extra round-trips.' It also clarifies the project vs project_root alternatives. However, it never explicitly says to use individual sibling tools when only a specific domain is needed.

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

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

No annotations are provided, so the description carries full behavioral disclosure. It explicitly states 'Read-only. No side effects.', explains the index's path-resolution and refusal behavior, describes the error dict on failure, and clarifies enum subgroup count semantics. This is well beyond what structured fields 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 long but well-structured with clear sections (overview, index behavior, usage, args, returns). The purpose is front-loaded, and every sentence carries information—the metaphor is brief and the parameter discussion is tersely formatted. Nothing 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?

Despite having no output schema and no annotations, the description fully defines the return structure, failure mode, path semantics, parameter constraints, and side-effect profile. For a 7-parameter tool with complex multi-build concepts, an agent has everything it needs to call this correctly.

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

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

Schema coverage is 100% and schema descriptions are already rich, so baseline is 3. The description's Args section mostly repeats schema text, but adds non-obvious parameter behavior: the subgroup count 'reflects the real total even when max_per_kind limits the constants list,' which is not in the schema. It also reinforces the project/project_root exclusivity constraint, adding meaningful nuance.

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: 'Fast structural map of all C/C++ symbols in a file grouped by kind.' The table-of-contents metaphor concretely conveys the output natureencing. It also explicitly distinguishes from siblings by naming get_symbol_context and lookup_symbol as detailed alternatives, so the agent can tell the difference without opening their schemas.

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 usage context: 'Use before reading a large file to orient yourself.' It also gives an explicit alternative route: 'For detailed symbol information use get_symbol_context or lookup_symbol.' The path-resolution caveat tells the agent when a query may fail, so usage boundaries are unambiguous.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: read-only/no side effects, cross-TU resolution, BFS with cycle detection for diamond inheritance, and refusal of out-of-range max_depth values. It also documents failure returns. This far exceeds minimal 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?

Despite being long, it is organized with an opener, Args, and Returns sections, and every sentence conveys either behavior, routing, or parameter/return semantics. The return-shape block is justified because no output schema exists. It is front-loaded with purpose and alternatives.

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

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

Complexity is high (7 params, no annotations, no output schema), but the description covers purpose, scope, parameter semantics, return format, and error behavior. No critical information appears missing 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?

The schema already covers all 7 parameters, so the baseline is 3. The description adds one meaningful caveat not in the schema—max_depth outside 1–50 is refused, not clamped—and restates the project alternatives. Overall it is helpful but mostly mirrors 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?

States a specific verb ('Return') and a specific resource ('the C++ inheritance chain for a class or struct'), and explains the libclang-aware cross-translation-unit resolution. It also distinguishes itself from sibling tools by deferring to get_class_members and get_method_overrides for related queries.

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 routes class-member queries to get_class_members and virtual-method override-chain queries to get_method_overrides. The transitive/max_depth guidance clarifies when to request the full hierarchy versus direct relations. The contrast with single-file reading and the read-only statement provide additional context for appropriate use.

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

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

No annotations are provided, so the description carries the full burden. It explicitly declares 'Read-only. No side effects', and discloses the underlying data source (the overrides table populated during indexing) and failure behavior (dict holds only error). It could go further by stating prerequisites like index freshness, but the provided behavioral disclosures are strong.

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, but it contains a near-verbatim redundancy: 'Shows what base-class method this method overrides...' appears in both the first and second paragraphs. This repetition wastes space. Other sentences earn their place, but the duplication prevents a higher score.

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

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

Given there is no output schema, the description compensates by detailing the return dict structure and failure mode. It covers all 5 parameters, names alternatives, and explains the index-derived nature of the data. Minor gaps like performance or index prerequisites exist, but for a tool of this complexity it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description's Args section largely duplicates the schema descriptions (e.g., qualified name example, project vs project_root guidance), adding little beyond what the input schema already states. No additional parameter clarification is provided, so a 3 is appropriate.

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

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

The description states a specific verb ('Return'), a specific resource ('C++ virtual method override information'), and explains the core mechanics (libclang-powered vtable analysis, resolving virtual dispatch across class hierarchies). It clearly differentiates itself from textual search and names sibling tools for alternative purposes, making it 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?

Explicit guidance is provided: 'For class-level inheritance, use get_inheritance_chain. For symbol details, use get_symbol_context.' It also explains why this tool is needed ('Text-based search cannot resolve virtual dispatch across translation units') and covers project selection constraints, enabling an agent to decide when to use this tool versus alternatives.

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

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

With no annotations provided, the description carries the full transparency burden. It explicitly discloses the underlying data source ('~/.fw-context/projects.db'), states 'Read-only. No side effects.' and defines the failure contract ('On failure the dict holds only error with the reason'). This is excellent behavioral disclosure beyond the bare 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?

The description is well organized with a front-loaded summary, usage context, Args, and Returns sections. It is slightly redundant around failure behavior — the error dict is described both in Returns and again in the final sentence — but overall it is compact and scannable.

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

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

For a simple one-parameter tool with no output schema and no annotations, the description covers the purpose, data source, side-effect profile, return fields, and error shape. The only notable gap is that it does not state what happens if project_id is empty or omitted, given the parameter has a default and is not marked required.

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

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

The schema already provides 100% coverage by describing project_id as 'Project ID (UUID4 hex) to look up.' The description's Args section largely repeats this. It adds context that the ID must be registered, but does not explain behavior for an omitted or invalid project_id, so it provides only marginal additional semantic value.

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

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

The description opens with a specific verb and resource: 'Return project metadata (name, type, root_path) for a project ID.' It clearly identifies this as a single-project lookup against a global registry, distinguishing it from sibling tools like list_projects and get_active_build by focusing on UUID4-based identification and build-system metadata.

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

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

The description gives clear usage context: 'Use this to identify a project from its UUID4 — find out what build system it uses, its name, and where it was last indexed.' This tells the agent when the tool is appropriate, though it does not explicitly 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?

No annotations are provided, so the description carries the full burden. It discloses read-only/no side effects, ifdef-filtering behavior, stale_warning and source_origin semantics, truncation caps, line-number prefixes, ambiguous_warning, and failure modes with candidates/hints. This is exceptionally transparent.

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

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

The description is long but well-organized into purpose, filtering behavior, alternatives, args, and returns. Every section adds operational detail, though some redundancy with the schema's parameter descriptions keeps it from being maximally lean.

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

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

With no output schema and no annotations, the description fully explains return fields, special keys, truncation, line-number citation, stale data, ambiguity, and error handling. An agent has enough information to invoke the tool correctly and interpret its result without external documentation.

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

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

Schema description coverage is 100%, and the description's Args section mostly restates the parameter semantics already present in the schema (auto-detection, mutual exclusivity, list_projects). It adds little new meaning beyond the structured data, so the baseline of 3 is appropriate.

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

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

The opening sentence states a specific verb and resource: 'Read a C/C++ function/method/enum/macro body using libclang exact extents.' It also distinguishes this from generic file readers and explicitly names siblings ('get_symbol_context', 'normal file read'), so an agent can tell what this tool uniquely does.

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

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

Usage guidance is explicit and actionable: 'For rich context ... use get_symbol_context instead' and 'For the full file, use a normal file read.' It also gives parameter-selection rules such as 'Give one of the two, not both' for project vs project_root, leaving little to inference.

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

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

With no annotations provided, the description carries the full burden and does so admirably. It discloses read-only behavior, no side effects, ifdef-filtered body behavior, source_origin semantics, stale-result handling, ambiguous matches, and failure candidates. It even explains that callers/callees come from the index and may be incomplete when stale.

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 long but densely informative and well-structured with clear sections (usage guidance, returns, failure modes, edge cases). Every sentence earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with the core purpose and usage guidance before diving into return 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?

This is a complex 5-parameter tool with no annotations and no output schema, yet the description covers purpose, alternatives, all edge cases (stale, ambiguous, failure, macro fallback), return variants by symbol kind, and even hints for handling candidate matches. Nothing an agent needs to correctly select and invoke the tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The Args section essentially repeats the schema descriptions word-for-word (e.g., project, variant, image) without adding new parameter semantics. The broader description adds context, but not beyond what the schema already provides for 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 states a specific verb and resource: 'Rich one-shot context for a C/C++ symbol: body, signature, all direct callers and callees.' It clearly answers the core question 'what does this do and how does it fit in the system?' and distinguishes itself from siblings like get_source and the recursive call-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 explicitly says 'Prefer this over get_source when you also need callers, callees, indirect call sites, or LLM analysis' and 'If you only need the raw function body... get_source is slightly faster.' It also names the transitive alternatives (find_all_callers_recursive, find_callees_recursive), giving 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?

With no annotations, the description fully carries the burden. It declares read-only behavior, no side effects, explains the internal mechanism (template_usr column, cursor.specialized_template), discloses reliability limitations for implicit instantiations, and specifies return behavior for no-match and error cases. No contradictions with annotations since none exist.

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

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

Well-structured and front-loaded: the purpose is stated first, then returns, limitations, and parameters. Despite length, every sentence adds essential information—no fluff. Sections are clearly separated, 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?

Given the tool's complexity (6 params, 1 required, no annotations), the description is exceptionally complete. It covers parameter semantics, return format (with example signature), failure modes, limitations, and alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for template_name, clarifying the project_root vs. project relationship ('Give one of the two, not both'), explaining limit defaults and max, variant's single-build behavior, and image's requirement. This exceeds the schema by providing usage context.

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

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

States a specific verb and resource ('Find all template instantiations for a C/C++ class or function template') and distinguishes itself from text-based search and from lookup_symbol for finding the declaration. The purpose is unambiguous and clearly differentiates from sibling tools.

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

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

Explicitly provides when to use (template-aware lookup for cross-TU specialization resolution) and when not to (for the declaration itself, use lookup_symbol). It also states the limitation that header-only templates may yield zero results, giving the agent a clear decision framework.

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

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

No annotations are provided, so the description carries the full burden—and it delivers extensively. It declares 'Read-only. No side effects. Requires an index of the assembly', explains the meaning of every status value, describes the two sources and their implications, warns that slot numbers are not joined across tables, and details edge cases like coverage rows and runtime-installed handlers. No contradiction with annotations exists because none were provided.

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 long, but the tool is genuinely complex and the length is organized with bold headers, bullet-like status explanations, and a front-loaded purpose statement. Some measured examples are verbose and could be trimmed, but the structure makes the detail navigable and each major section addresses a distinct decision an agent must make.

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 exceptionally complete for a complex tool: it covers all statuses, both sources, the unspecified-source 'build' rows, table boundaries, coverage holes, interrupts rows, limit/truncation behavior, and the non-empty error/info response contract. It even documents failure modes ('Never empty: one dict with error... or info...'). An agent has enough context to select and invoke the tool correctly in nearly any scenario.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some meaning beyond the schema: it states the limit max is 1000 (schema only gives default 400), clarifies that 'One query answers for ONE build' for variant, and reinforces the project_root/project exclusivity. Most parameter text repeats the schema, but the extra constraints justify a 4.

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

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

The description opens with a specific verb and resource: 'Read the interrupt vector table, and say what services each interrupt.' It explains the conceptual role of the vector table and gives concrete use cases ('which interrupts does this firmware service', 'find the handler for one interrupt'), clearly distinguishing this tool from the sibling lookup tools.

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

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

Explicit use cases are listed ('Use it to answer...'), and the description names fallback alternatives: 'get_symbol_context on the name, then find_references on the table it uses' for dispatcher rows, and 'find_references on the handler name' for interrupts this tool cannot show. It also states what is not covered (branch-instruction architectures, link-time-resolved addresses), giving 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?

No annotations are provided, so the description carries the full burden and meets it: it declares 'Read-only. No side effects.' It also discloses return behavior, UTC timestamp formats, and edge cases such as no indexed project or a database that cannot be read. This goes well beyond what structured fields would convey.

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 and front-loaded: purpose, read-only note, usage guidance, then params and returns. It is long, but most content is useful; the main inefficiency is that the Args section partly duplicates the input-schema descriptions.

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

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

With no annotations and no required parameters, this description is fully self-contained: it covers when to use the tool, how to choose between parameters, return shape, timestamp semantics, and unusual result cases. There is no critical gap an agent would need to guess at.

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 100% description coverage and already explains both project and project_root, including the distinction between them. The description's Args section mostly mirrors the schema, adding no meaningful new parameter semantics beyond what is already available.

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 all indexed firmware projects with their statistics.' It also distinguishes itself from get_active_build by noting that the latter provides details on the currently active project, so an agent can tell the tools apart.

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

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

It explicitly says to use this tool at session start to discover available projects and directs the agent to get_active_build for active-project details. It also explains when to pass project_root versus project and warns not to give both, which is clear routing guidance.

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

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

With no annotations, the description carries the full burden, and it does so thoroughly. It discloses that this is a read-only diagnostic, that it reflects the actual index rather than config, that single-project indexes return empty variant/image, that memory maps live here rather than in get_active_build, and that uninitialized projects return the {builds: [], multi: False, error: ...} shape.

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?

Long but dense and well-organized: purpose, read-only caveat, sibling differentiation, parameter docs, return shape, and cross-tool warning each earn their place. The opening line front-loads the core purpose, and the rest is structured under clear Args/Returns headings.

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?

Since there is no output schema, the description exhaustively documents the return dict, each field, the memory sub-structure, and the error case. It also covers the single-project behavior and the distinction from get_active_build's images list, leaving no obvious gap 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 description coverage is 100%, so the schema already documents both parameters well. The Args section essentially repeats the schema text without adding new meaning, so the description does not raise the value beyond the schema 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?

Opens with a precise verb-object statement ('List every indexed build') and immediately scopes it to the (variant, image, board) identity. It further distinguishes itself from configuration-declared state and from get_active_build, so an agent can tell exactly what this tool returns.

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 contrasts this tool with get_active_build: use get_active_build for the mandatory first-call health check and human-readable variants/images discovery, and use this tool for per-build config_hash and symbol counts. It also explains how both relate to index state and resolve_build, giving clear selection criteria.

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

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

No annotations are provided, so the description carries the full burden — and it does so comprehensively. It discloses the read-only nature ('Read-only: yes'), side effects ('May auto-reindex stale files (non-blocking)'), the error-key edge case, the empty-list case with no page notice, the _fallback flag, the C++ constructor name-collision quirk, and even flags that llm_analysis text was model-written ('A model wrote the text... the code did not').

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 structure is sound and front-loaded — purpose, then usage, then params, then returns — but the Returns section is verbose, repeating details an output schema would already carry (the full field list). Much of the length is justified by behavioral context (page-notice reading instruction, error key, llm_analysis caveat), but a trim of redundant field enumeration would tighten it without loss.

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 complex tool — 8 parameters, 1 required, multi-case return format, error handling, pagination — the description is remarkably complete. It covers the page-notice semantics, empty-result behavior, error-key case, did_you_mean suggestions, fallback flag, and the C++ constructor quirk. With an output schema present, the return-format detail exceeds necessity but adds behavioral value an output schema cannot capture.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the offset parameter's pagination rationale with stable ordering guarantee ('two pages never overlap and never skip a symbol'), the image parameter's requirement rationale ('each image is a separate program'), and the project vs project_root mutual-exclusion guidance. These exceed what the schema documents.

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

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

States a specific verb, resource, and mechanism: 'Look up a C/C++ symbol by name via libclang index — exact or prefix matching.' It clearly differentiates from search_code by naming what makes it unique ('Finds symbols text-based search can miss: build-conditional code, template instantiations, macro-expanded names') and explicitly names the sibling it should be preferred over.

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

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

Explicit when-to-use guidance: 'Prefer this over search_code when you know the exact symbol name or a prefix... Use search_code for keyword/concept search.' Also gives concrete routing examples (uart_ finds all UART symbols) and instructs calling list_projects for the project parameter. Nothing is left to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers: read-only/no side effects, inactive branches replaced with blank lines preserving line numbers, fallback to raw disk with warning, all_lines_inactive semantics, inclusion of comments/preprocessor directives, range clamping, and failure conditions. Nothing important is hidden.

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 front-loaded, but it is quite long and has some redundancy — the meaning of blank lines and all_lines_inactive is explained multiple times. Every sentence is useful in context, but tighter editing would make it cleaner without losing 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?

This is a complex tool with 8 parameters, no output schema, and no annotations, yet the description covers the return dict fields, warning/all_lines_inactive flags, range clamping behavior, raw-disk fallback, legacy index caveat, and all error cases. An agent has everything needed to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema: file_path relative-or-filename, project vs project_root exclusivity, one query per build, image requirement for multi-image variants, detailed start/end_line semantics (1-based inclusive, 0 = unbounded), and the line_numbers output format. It also warns not to count lines and tells where to get line numbers.

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 precise action — reading a C/C++ source file with ifdef-filtered, build-accurate content — and distinguishes itself from siblings by name (get_source, get_file_map, get_symbol_context, search_content). An agent can immediately tell what this tool does and how it differs from a generic file reader.

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 use case ('read a file without leaving the fw-context ecosystem'), explains what makes it unique (build-accurate ifdef filtering), and explicitly lists alternatives for other needs: get_source for function bodies, get_symbol_context for body+callers+callees, get_file_map for structure, search_content for patterns. This is model guidance.

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

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

With no annotations provided, the description carries the full burden. It explicitly warns 'Not read-only', explains the warning for headers, and discloses that LLM analysis and method override relationships are regenerated when enabled, while unchanged symbols keep stored analysis. It does not detail failure modes or side effects on the broader index, but it covers the most important behavioral traits.

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

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

The description is well-structured with a clear opening, a 'Not read-only' warning, usage context, and an Args section. It is somewhat long but every sentence earns its place, and the most important behavioral warning is front-loaded. Minor redundancy with the schema's parameter descriptions prevents a 5.

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, constraints, side effects, and return value shape. It lacks an output schema, but the Returns section lists the dict keys. It doesn't explain error cases or what happens if the file is not in compile_commands.json, but for a tool with this complexity, the description is nearly complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the header-vs-source distinction and the project/project_root mutual exclusivity, which goes beyond the schema. It doesn't add much beyond that, but the schema is already rich, so a 4 is appropriate.

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

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

The description states a specific verb ('re-parse'), a specific resource ('a single source file with libclang'), and the outcome ('update its symbols in the index'). It also distinguishes itself from a full rebuild and from sibling tools like reindex_file_impl by clarifying it operates on a single file. The scope is unambiguous.

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

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

The description explicitly says when to use it ('after editing a file to keep the index current without a full rebuild'), and it explains the constraint that source files must be in compile_commands.json while headers are handled through an including unit. It also gives clear guidance on project vs project_root alternatives, including 'Give one of the two, not both.' This is strong usage guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'Not read-only' and explains the use of compiler flags from compile_commands.json. It discloses the header re-parsing limitation and the resulting warning, the cost decision (up to 266 units), and the content-addressed analysis regeneration. It also describes the return dict and error handling, leaving no ambiguity about side effects or outcomes.

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 long but every sentence earns its place. It is front-loaded with the core purpose, then systematically covers limitations, cost, parameter details, and return format. The structure is logical and the language is dense without being verbose, making it easy for an agent to extract the key facts quickly.

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 complexity (4 parameters, no output schema), the description is exceptionally complete. It explains the header edge case, the performance tradeoff, the meaning of each parameter, the return value format, and error behavior. Nothing an agent needs to decide whether to call this tool and how to use it correctly is missing.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It clarifies the difference between source files and headers for file_path, explains the relationship between project and project_root (alternatives, not both), and details the performance tradeoff of with_analysis. These enrichments go well beyond the schema descriptions, helping the agent select the correct parameter values.

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: 'Re-parse a single source file with libclang and update its symbols in the index.' It distinguishes itself from a full rebuild and provides specific details about file types. However, it does not explicitly differentiate from the sibling 'reindex_file' tool, leaving the agent to infer the difference from the name.

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 guidance: 'Use after editing a file to keep the index current without a full rebuild.' It also explains when not to use it ('Only a full fw-context index covers every context') and notes the cost tradeoff of using a single translation unit. It further mentions the with_analysis=False fast path used by background auto-reindex, providing clear context for when to choose this tool over alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden. It explicitly warns that the operation is not read-only, permanently deletes the SQLite database and WAL files, supports dry-run, handles corrupt databases gracefully, and documents the warning key and failure result shape.

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 appropriately sized for a destructive tool. It front-loads the purpose and danger, then provides structured Args and Returns sections. Every sentence adds useful information, including the corrupt-database behavior and re-indexing follow-up.

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

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

Given no output schema, the Returns section fully documents the response dict, dry-run vs deleted action, warning semantics, and error-only failure case. All parameters are covered by the schema, and the destructive side effects are clearly disclosed. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates the schema: project_root auto-detection, project as an alternative to project_root, and confirm default false. It adds no material 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 states a specific action and resource: "Delete the entire symbol index for a project." This clearly distinguishes reset_index from sibling tools like reindex_file, which rebuild rather than delete the index.

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

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

The description gives clear usage guidance: call with confirm=False first as a dry-run, pass confirm=True to execute, and re-index with fw-context index afterward. It does not explicitly contrast against sibling tools like reindex_file, so it falls short of full alternative-selection 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 exist, so the full burden falls on the description — and it delivers richly: explicit read-only declaration, ifdef-filtering semantics, FTS5 tokenizer behavior (AND not OR, no implied prefix, punctuation dropping), fallback sanitization with _query_used, source truncation limits, stale-index warnings, and the line-vs-match_lines citation distinction. Warning/error/empty-list conventions are also spelled out so an agent knows what each response shape means.

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

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

The description is very long (1000+ words) but clearly sectioned with headers and bullets, with the core purpose front-loaded. Most sentences earn their place given the tool's subtle FTS5 semantics and conditional return fields; the measured-project anecdotes and some repeated wildcard reminders are illustrative but could be trimmed.

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 zero annotations and 9 parameters, the description covers everything needed to invoke correctly: query formation semantics, scope boundaries, return-field meanings (match_lines vs line for citation), truncation, pagination, error vs warning vs empty-list conventions, and sibling routing. The output schema exists, and the description still adds value by explaining the conditional fields' semantics rather than just their shape.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds non-inferable meaning: FTS5 query rules for the query param (add * for prefix, double quotes for phrases, single word is broadest), the mutual exclusivity of project and project_root, a use-case for project_only, and offset's page-navigation behavior. The value-add is real but concentrated on query plus cross-parameter relationships, so a 4 not a 5.

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 opening sentence names a specific verb and resource — 'Find patterns in the TEXT OF A DEFINITION — the code inside its extent' — and the coverage enumeration (callables, types, data definitions) makes the scope concrete. The 'Only the text matches' paragraph explicitly negates what this tool is not (name/signature/docstring search), distinguishing it from search_code and search_content without needing their schemas.

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?

An explicit 'When to use search_bodies and when search_code' section gives contrasting example queries ('self test' vs 'modem init'), names search_content for what falls outside definition extents, and advises project_only=True for questions about the team's own code. This exceeds the calibration example: it gives positive conditions, exclusions, and named alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read-only: yes,' explains auto-reindexing and the non-blocking watcher daemon, details the progressive relaxation fallback steps with '_fallback' keys, excludes local variables, and cautions that llm_analysis is model-generated and not factual. It also describes the page notice and error/warning dicts. This is thorough and transparent beyond basic read-only 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 long but well-structured with clear headings (FTS5 syntax, Progressive relaxation, Kind filter, Returns). Core purpose and contrasts are front-loaded. While there is some redundancy between the Args section and the schema (repeating descriptions), most sentences add value given the tool's complexity. The length is justified, but it could be tightened slightly.

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

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

For a tool with 9 parameters, many siblings, and an output schema, the description covers all critical aspects: usage context, query syntax pitfalls, fallback behavior, output format (including page notice and error cases), and safety (read-only). The output schema exists, so the description need not detail every return field, but it explains the page notice and fallback keys. Nothing an agent needs to call it correctly is missing.

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

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

Although schema coverage is 100% (baseline 3), the description adds critical semantics: it explains the FTS5 underscore pitfall with concrete examples, clarifies pagination and offset behavior, distinguishes project vs project_root, and notes varlocal exclusion. These insights are essential for correct invocation and go well beyond the 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 verb and resource: 'Find C/C++ symbols by name' and clarifies scope ('searches function/class/enum NAMES'). It differentiates from siblings by explicitly noting what it does NOT search ('Does NOT search function bodies') and pointing to alternatives (search_bodies, lookup_symbol). This makes the purpose unambiguous and distinguishable.

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

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

The description provides explicit usage guidance: 'Use when you know the concept but not the exact name' and 'Prefer lookup_symbol when you already know the exact or prefix name.' It also contrasts with search_bodies for patterns in code. Additionally, it warns against underscores and explains the relaxation steps, giving clear when-to-use and when-not-to-use context.

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

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

With no annotations, the description carries the full burden and excels. It discloses ifdef-filtering behavior, line-number preservation via blank lines, file-level results, LIKE-fallback with '_fallback: like', stale-index auto-reindex, read-only nature, and the subtle case where match_lines are absent because FTS matched a token variant. This is far beyond what structured data could convey.

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 long but structured with distinct sections (purpose, sibling contrast, Args, Returns) and front-loaded with the core scoping statement. Some redundancy exists—'Covers the text that belongs to no definition' is repeated in the contrast paragraph—but given the 8-parameter complexity and zero annotation coverage, the length is mostly earned.

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 a complex search tool with 8 parameters and no annotations. It covers error shapes (dict with 'error'), warnings/hints for stale or unparseable queries, page-notice fields (total, offset, shown, more), match_lines semantics, and the no-match case ([]). Nothing an agent needs to call this correctly is missing.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains the OR-joining and prefix-wildcarding of bare multi-word queries ('every term gets a trailing *'), the project vs project_root mutual exclusion, pagination semantics with offset/page-notice, and variant/image build scoping. These details materially change how an agent should construct calls.

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

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

The description states a specific verb, resource, and scope: 'Find patterns in FULL file content — the whole file, not only the text that belongs to a definition.' It explicitly differentiates from siblings by contrasting with search_code (finds by NAME) and search_bodies (definitions only), so an agent can pick the right tool immediately.

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

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

Provides explicit when-to-use guidance and names alternatives with clear conditions: 'To find a symbol by NAME... use search_code' and 'search_bodies answers WHICH DEFINITION... search_content answers WHICH FILES.' It even advises running both for a feature footprint and explains the fallback path when files_fts is missing.

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

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

With no annotations provided, the description must carry the full behavioral burden, and it does: it discloses read-only semantics, LLM dependency, the silent fallback to search_code with a warning, non-blocking auto-reindex of stale files, that _similarity holds the multiplied score and not raw cosine distance, and the 1.2/0.85 source-aware ranking tiers. Nothing behavioral is left to inference.

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?

Long but well-organized with clear section headers, front-loaded purpose, and worked examples. Nearly every section earns its place. Minor redundancy exists — the fallback behavior is described both in the 'Requires an LLM' section and again in the Returns section — which is the only structural blemish in an otherwise disciplined layout.

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 complex 5-parameter tool, the description is exhaustive: it covers the normal return shape, the warning-dict path when similarity is below the relevance floor, the LLM-unavailable fallback variant, empty results, and the error dict, instructing to check the error key first. Even with an output schema present, the description's coverage of edge cases and failure modes leaves nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema: per-threshold outcome guidance (0.50 exploratory vs 0.65 strict), query length recommendation (5-15 words), and clarification that project vs project_root are alternatives ('Give one of the two, not both'). This materially improves parameter understanding over 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 names a specific verb+resource ('semantic search using pre-computed libclang symbol embeddings') and explicitly distinguishes itself from siblings by meaning ('Finds symbols by meaning, not by text'). Concrete worked examples ('parcel locker state', 'cell modem') make the intent unmistakable, and the contrast with search_code is drawn directly. An agent can tell exactly what this tool does without opening any schema.

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 when-to-prefer sections ('When to prefer over search_code') with concept-vs-keyword criteria and named alternatives (search_code, search_bodies) with reasons ('FTS5 is faster and more precise'). It even covers the multi-build case, steering to search_code/search_bodies when a specific build is targeted. 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly: it states read-only, the slow 10-30s runtime, the full pipeline it delegates to, the fallback when the LLM is unavailable, partial results on LLM stall, stale-index warnings, and error handling. This is exemplary 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 long but well-structured with headers and a clear flow. It front-loads purpose and usage, then pipeline, parameters, and returns. There is some redundancy (the 'prefer this' guidance appears twice), and the multi-phase enumeration is detailed but arguably necessary for such a complex tool. It earns a high score, though not a perfect one due to the repetition.

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

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

For a tool this complex, the description covers every aspect an agent needs: purpose, when to use it, how it works, parameter semantics, return format, edge cases (LLM stall, stale index, no match, error), and even the absence of a build parameter. It is fully self-sufficient even without the output schema, and it goes beyond what the schema provides.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema: it advises query specificity ('5–15 words works best'), explains that limit is clamped to the 5–100 range with the reason (re-rank needs a set), and clarifies the mutual exclusivity of project vs project_root. This is far beyond 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 opens with a precise statement of what the tool does: an LLM generates FTS5 keywords and searches the libclang index to find concepts by meaning. It also names the key sibling (search_code) and explains the distinction: use this when you don't know exact keywords. That is a specific verb+resource with clear sibling differentiation.

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

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

Explicit guidance is given on when to prefer this tool ('when you don't know the exact keywords') and when not to use it ('on a project that holds several builds, use search_code or search_bodies'). It names alternatives directly and states the condition that selects them, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full burden. It states 'Read-only. No side effects. Requires the reference index', discloses timeout behavior ('timed_out: True means ... not proved reachable'), and warns about the never-empty result with an info dict. This is substantial behavioral disclosure beyond the schema.

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

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

The description is long but well organized: purpose, limitations, prerequisites, arguments, return semantics. It is front-loaded with the core purpose. Some redundancy exists because the Args section largely echoes the input schema, but the added examples and clarifications justify most of the length.

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 9-parameter tool with no annotations, the description is highly complete. It covers prerequisites, limitations, parameter disambiguation, timeout semantics, empty-result behavior, and return structure. An agent has enough context to call it correctly without external knowledge.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value with concrete examples for type_name and to_symbol, the 'Give one of the two, not both' guidance for project/project_root, and the timeout clamp 'Clamped to 1000–300000' which is not present 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 specific verb and resource: 'Trace how C/C++ data of a given type flows to a target function via libclang call paths.' It distinguishes the tool from text-based search ('which text-based search cannot trace across translation units') and from sibling tools by naming the find_* family and find_call_path.

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

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

The description gives explicit usage context: 'Works best for synchronous driver stacks' and 'Cannot follow async flows (message queues, interrupts, RS485 callbacks).' It also routes users to alternatives: 'For exact call-graph queries use the find_* family; verify specific paths with find_call_path.'

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