Symvanta

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

Annotations already provide idempotentHint and readOnlyHint/destructiveHint, but the description adds meaningful behavioral detail: the first attach triggers an indexing job, the response carries indexing_status and indexing_job_id, and data becomes available only after the index is stable. This goes beyond the annotations and helps the agent understand side effects and polling behavior.

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

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

Three compact sentences each carry distinct value: what the tool does, idempotency plus the indexing side effect, and response/availability semantics. The most important information is front-loaded with no filler.

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

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

Given there is no output schema, the description compensates by naming the response fields (indexing_status, indexing_job_id) and explaining how to interpret them. It covers the required inputs, behavior, side effects, and data availability, making the tool self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds mild value by highlighting owner + repo_name as the key pair and noting the clone URL is derived, but it does not meaningfully explain projectId, default_branch, or feedback beyond what the schema already states.

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 ('Attach') plus a concrete resource ('public GitHub repository to the active project') and names the core inputs ('owner + repo_name; clone URL derived'). This clearly distinguishes it from sibling tools like list_repositories or reindex_repository, which serve different operations.

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

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

The description gives clear context: it applies to attaching a public repo to the active project, and 'first attach dispatches an indexing job' signals the initial-onboarding use case. Idempotency also implies it is safe to call again. It does not explicitly name alternatives like reindex_repository for already-attached repos, so it falls short of a 5.

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

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

The description discloses the write-oriented behavior of record and update, including the special constraint that superseding requires supersededById. It adds meaningful context beyond annotations by explaining that ADRs survive reindexes and are anchored to symbols/files/projects. It does not describe return formats or complete side effects, but the annotations offer no contradictory signals and the description is honest about mutating operations.

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

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

The description is compact, front-loaded with the core concept, and organized into clear operation bullets. Every sentence carries information: persistence behavior, anchoring, and per-op requirements. There is no filler or redundant repetition of the schema.

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

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

Given 14 parameters, multiple operations, and no output schema, the description covers the essential patterns an agent needs to call the tool correctly. It defines anchors, required fields per operation, and filtering options. Minor gaps remain, such as not mentioning the feedback piggyback field or the projectId default, but the schema fully documents those and the description handles the highest-risk decisions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable op-conditional semantics, such as record needing title+decision, anchor alternatives (repository+symbolPath vs filePath vs project-wide), and update requiring id with specific status handling. This goes beyond the flat schema descriptions and clarifies parameter relationships.

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

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

The description clearly identifies the tool as managing architecture decision records, explains the core concept (WHY behind code), and enumerates the three operations record/list/update. It also differentiates from the sibling find_node by noting that find_node attaches a node's decisions, so the agent knows which tool handles retrieval vs. management.

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 per-operation usage rules: record requires title+decision and anchor selection, list filters by specific fields, and update requires id plus status transitions. It also points to find_node as the place where a node's decisions are attached, implying when the agent should look elsewhere. It does not explicitly state when not to use adr, but the op-specific guidance is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavior beyond them: cost/latency (~2-4s, ~3-5k tokens), the single-call answer+citations behavior, the scope:all restriction that rejects repository, and the early-stop sufficient_to_answer signal. There is no contradiction with the annotations.

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

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

The description is compact and front-loaded: purpose and cost warning come first, followed by scoping rules and the stopping condition. It avoids fluff and every sentence conveys decision-relevant 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 9-parameter tool with no output schema, the description provides enough to select and invoke it correctly: what it returns, when to use it, when to avoid it, how scoping works, and when to stop. The remaining parameter details are fully documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic value beyond the schema by explaining that scope:all rejects repository, that omitting repositoryIds spans all repos, and that commitSha pins reads to a revision. Some parameter details are left to the schema, but that is appropriate given its full coverage.

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

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

The description states a specific purpose: 'Synthesis Q&A for behavior/architecture questions' with 'answer + citations in one call'. It also differentiates itself from lighter siblings by flagging itself as HEAVY and explicitly naming context, find_node, and locate as alternatives an agent should prefer when they suffice.

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

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

The description gives an explicit routing rule: prefer cheaper tools when adequate and stop making further tool calls once sufficient_to_answer=true. It also clarifies when to use scope 'repo' versus 'all', how repositoryIds narrows cross-repo scope, and that 'all' rejects repository.

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

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

Beyond the readOnly and idempotent annotations, the description discloses parallel execution, shared bundle-level scope with per-call repository overrides, input-order result ordering, and error objects for unsupported tool names. It also constrains valid modes and kinds, giving the agent a clear behavioral model. There is no contradiction with annotations.

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

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

The description is dense but well-structured: the core capability is front-loaded, and each subsequent clause adds a necessary constraint or behavioral fact. No sentence is wasted, and all key operational details are packed into a compact form.

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 nested batching tool with no output schema, the description covers the essential context: call limit, supported tools, scoping rules, result ordering, and error behavior. It leaves some details to the schema, such as feedback and commitSha semantics, and does not describe per-tool result shapes, but those are reasonable omissions for a wrapper tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-level semantics by explaining how repository scope applies at the bundle level versus per-call args.repository, and by enumerating valid combinations of args.mode and args.kind for supported tools. This goes beyond the bare schema definitions.

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: running up to 10 independent tool calls in parallel in one round-trip, and it enumerates the specific supported tools and their constraints. This clearly distinguishes the bundle tool from sibling individual tools like locate or relate, making its role as a batching wrapper obvious.

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 conditions for use: calls must be independent, at most 10, and only listed tools are supported. It also provides exclusions such as locate mode 'not codebase' and relate kind 'callers only'. However, it does not explicitly instruct the agent to fall back to individual sibling tools when a call is dependent or unsupported.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond annotations: it returns top 5 files with symbols and matching snippets, makes one call, costs ~1-1.5k tokens, takes ~500 ms, and performs no LLM inference. No contradiction exists between the description and annotations.

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

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

The description is compact and front-loaded, leading with the tool's core purpose and then giving output shape, cost, latency, and sibling alternatives. Every sentence contributes useful information; there is no filler or redundancy.

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

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

For a read-only, schema-rich tool with 100% parameter coverage and no output schema, the description is complete enough: it explains what the call returns, how much it costs, what it replaces, and how it relates to sibling tools. The absence of an output schema is mitigated by the explicit description of the return content.

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 task, feedback, commitSha, projectId, and repository. The description adds context about the task parameter's role ('natural-language task' and its result shape), but it does not deepen meaning for the remaining parameters beyond what the schema already provides.

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

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

The description states a specific verb and resource: pass a natural-language task and get the top 5 relevant files with symbols and snippets. It clearly differentiates itself from siblings by explicitly naming the chain it replaces (locate text + locate semantic + list_file_symbols) and contrasting with find_node/locate and ask_codebase.

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

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

The description says 'First-touch task orientation,' which establishes the intended use case, and explicitly names the alternatives: locate, list_file_symbols, find_node/locate, and ask_codebase. It lacks an explicit 'when not to use' statement, but the sibling routing and first-touch framing give strong practical guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful behavioral context beyond those flags: default revision resolution (head = session effective revision, base = previous indexed), the union blast radius across layers and cross-repo, and the prerequisite indexing step for uncommitted edits. It doesn't contradict annotations.

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

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

The description is dense but efficient: three sentences cover purpose, output categories, sibling replacement, defaults, and the uncommitted workflow. The first sentence is a little long and packed with clauses, but every piece of information earns its place and the most important guidance appears early.

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

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

For a read-only analytical tool with no output schema, the description provides the needed purpose, defaults, alternative routing, and a special-case workflow. It doesn't spell out the response structure, but the listed output categories (changed files, blast radius, endpoints, test suites, co-change reminders) give a reasonable expectation. Minor gap: how the results map to future reference or relate calls.

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 real value by explaining default base/head semantics and the 'call with no shas' pattern following an uncommitted-edit indexing step, which helps the agent decide when to omit parameters despite the schema already describing each parameter individually.

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 computes the impact of a diff between two indexed revisions, listing specific output categories (changed files, symbols, blast radius, endpoints, test suites, co-change reminders). It also names the sibling it replaces (per-symbol relate blast_radius loops), making it distinguishable from related tools.

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

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

Provides explicit usage context: 'before merging' as the trigger, names the alternative it replaces (relate loops), explains default behavior for omitted shas, and gives a concrete workflow for uncommitted edits ('run ref (op:"index_working_tree"), then call with no shas'). This gives an agent clear when-and-how-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?

The description discloses that the estimate is heuristic, approximate, and based on 'symbol-name + text matches' rather than exact analysis. Words like 'coarse' and 'likely touches' warn the agent not to treat the result as ground truth, which is valuable behavioral context beyond the read-only and idempotent annotations.

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

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

Every sentence earns its place: what the tool produces, when it is used, and how it works. The core purpose is front-loaded and there is no filler or repeated schema information.

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

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

For a tool with no output schema, the description conveys the essential return concept (coarse file count and layer/repository span) and the decision it informs. It stays somewhat high-level about the exact response shape, but that is consistent with a heuristic pre-flight tool, and the annotations already cover safety and idempotence.

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 because the schema already describes all three parameters. The description's mention of 'symbol-name + text matches' hints at how the tool processes input but does not add explicit parameter-level guidance such as formatting, required content, or how to use the optional feedback/projectId fields.

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

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

The description opens with 'Pre-flight estimate before graph traversal' and clearly defines the output: a coarse count of touched files plus whether the change spans layers or repositories. It also positions the tool as a decision aid ('Decides single-file edit vs consulting the graph'), which distinguishes it from graph-traversal siblings like ask_codebase and diff_impact.

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

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

It clearly frames when to use the tool: before graph traversal, to decide whether a single-file edit is enough or whether the graph should be consulted. It does not explicitly name sibling tools or list when-not-to-use conditions, but the pre-flight framing and decision role provide sufficient context for an agent to select it appropriately.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: it parses framework router metadata for Express, Fastify, Hono, Laravel, FastAPI, etc., rather than doing text search, and can resolve dynamic segments and mounted routers. It doesn't cover no-match behavior, but this is a minor gap for a read-only resolver.

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

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

Two sentences carry the full definition: the first states what the tool resolves and returns, the second gives direct usage guidance and capability context. Every sentence earns its place and the most important information is front-loaded.

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

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

For a read-only lookup with one required parameter and no output schema, the description explains the input, the output shape (endpoint + handler with filePath and line bounds), and the routing-aware behavior. It doesn't specify return cardinality or no-match behavior, but the combination of description and full schema coverage is sufficient 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%, with the schema already documenting path, method, feedback, commitSha, projectId, and repository. The tool description reinforces the core path+method semantics but adds no significant parameter details beyond what the schema already provides.

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

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

The description opens with a precise verb, 'Resolve', and a clear object: 'HTTP route by path + optional method to endpoint + handler (filePath + line bounds)'. It also explicitly contrasts the tool with grep/locate for URL paths, making it easy to distinguish from sibling search tools like locate.

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 it: 'Use instead of grep/locate for URL paths'. It explains why by saying it follows framework router metadata and resolves dynamic segments, prefix groups, and middleware-mounted routers that text search misses, giving clear 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?

Beyond the readOnly/idempotent annotations, the description discloses the return shape, optional enrichments (source excerpts, summaries, SCIP package metadata, heritage), and the unresolved fallback {resolved:false, candidates}. It also clarifies modifier interactions such as includeCrossRepo being a no-op when includeHeritage is off.

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

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

Four dense sentences with no filler, and the core purpose is front-loaded before selector variants and optional behavior. The long clauses earn their place given the tool's complexity and the absence of an output schema.

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

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

With no output schema, the description thoroughly covers what a resolved and unresolved result looks like, including optional metadata and heritage limits. Remaining parameters such as limit, projectId, repository, and sourceMode are already fully documented in the input schema, so 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 semantics by noting that a flat query/name/single field also works instead of the selectors array, and by explaining what includeSource, includeSummaries, includeHeritage, and includeCrossRepo change in the result.

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 precise operation: resolve 1-10 symbols into filePath, line bounds, and signature. It also differentiates the tool by supporting multiple selector forms (nodeId, symbol, symbolPath, filePath) and a flat query fallback, which distinguishes it from single-lookup siblings like locate or quick_lookup.

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

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

There is no explicit guidance about when to use find_node versus sibling tools such as locate, list_file_symbols, or quick_lookup. The description explains how to invoke the tool and what it returns, but does not state when it should be preferred or excluded.

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

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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral details: it reports Symvanta's indexed state rather than local git, explains that currentRemoteSha can be null without credentials, and discloses that the active ref pin is echoed. These are exactly the kind of non-obvious behaviors an agent needs to interpret results correctly.

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

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

The description is three sentences with no filler. It front-loads the return values and purpose, then adds essential caveats and additional output context. Every sentence earns its place and even the null behavior is covered compactly.

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

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

For a simple read-only freshness check with no output schema, the description covers the returned fields, a key null condition, and the distinction between Symvanta state and local git. It could additionally explain when lastIndexedSha/lastIndexedAt might be null or how the active ref pin is determined, but the essentials for correctly using and interpreting the tool are present.

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

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

The input schema already describes all three parameters thoroughly, including projectId, repository, and the feedback object, with 100% coverage. The description does not need to repeat parameter details. It adds no parameter-level meaning, but the schema carries the full burden, so the baseline score of 3 is appropriate.

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

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

The description opens with the exact resource and fields returned ('lastIndexedSha, lastIndexedAt, and the current remote HEAD sha') and immediately states the purpose: 'detect index drift from remote.' It also differentiates the tool from local-git operations by saying 'Reports what Symvanta knows, not local git,' which clearly separates it from sibling tools focused on git or indexing.

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 a clear use case: detect whether the indexed repository has drifted from the remote. It also provides useful context about the meaning of 'currentRemoteSha' when no GitHub credential is configured. However, it does not explicitly name alternative tools or state when not to use this tool, such as when checking local git state.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety semantics. It adds useful behavioral context beyond annotations: the indexed-window limitation, the <=200/default 50 row cap, and the null result for commits outside the window.

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

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

The description is compact, scannable, and front-loaded with the core resource. The bullet-per-operation structure groups related information cleanly, and every sentence earns its place without filler or repetition.

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

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

Given the tool's multi-op design and lack of an output schema, the description sufficiently summarizes what each operation returns: metadata with file lists, diff summaries, and ranked files. Combined with 100% schema parameter coverage and the annotations, an agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the description is not required to re-explain each parameter. It still adds value by tying each op to its output semantics, noting the default/max limit, and clarifying the null behavior for unknown SHAs. This goes beyond what the raw schema descriptions provide.

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 'Indexed commit history' and then enumerates three concrete operations, making it immediately clear what the tool does and what resource it operates on. It is unambiguous and distinct from raw git log, so an agent can understand the tool's role without opening the 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?

The commits bullet explicitly says 'With a clone prefer git log,' giving an actionable alternative and the condition under which it should be chosen. The commit and recently_changed bullets also clarify result behavior, helping the agent decide when this indexed-history tool is appropriate.

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

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

The annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral detail beyond that: empty results may mean 'not indexed yet', 'skipped' rows will never arrive, 'failed' means no source was found, and specific statuses distinguish network/credential problems from repository problems. This is rich, useful behavioral context.

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

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

The description is dense and long, but almost every clause earns its place by explaining a status code or metric interpretation. It is front-loaded with the core purpose and the key call signal, though the heavy use of nested parentheses and semicolons makes it harder to parse than it could be with structured bullets.

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

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

With no output schema, the description carries the burden of explaining return semantics, and it does so thoroughly, covering each health field, possible status values, and their practical meaning. It also tells the agent what actions to take for degraded or failed indexes, making the tool fully actionable.

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

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

All three parameters already have descriptions in the schema, so the baseline is 3. The description mentions 'per-project' and 'per-repo' concepts that imply the projectId and repository parameters, but it does not add explicit parameter-level guidance beyond what the schema already provides.

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

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

The description states 'Per-project index health' and then enumerates the specific health categories it reports, so an agent knows exactly what this tool produces. It also distinguishes itself from siblings by focusing on index status rather than search, reindexing, or repository management.

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 to call this tool when a query is surprisingly empty, and it explains what different statuses mean and which statuses are worth waiting on. It also references alternatives like 'inspect via map view' and remediation through reindexing, giving clear guidance on 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond those annotations, such as returning a usage field with decision matrix/routing and the explicit stop condition for empty repositories. It does not contradict the annotations.

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

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

Three tight sentences with no filler. The key instruction 'Call first' is front-loaded, followed by the return summary and the conditional routing rule. Every sentence earns its place.

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

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

For a zero-required-parameter initialization tool, the description is complete: it states what is returned, how to interpret the result, what to do in the empty case, and explicitly warns against falling back to Grep. The lack of an output schema is compensated by the clear high-level return contract.

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 sole parameter, feedback, is fully documented in the schema with descriptions for answerId, outcome, and correction, so the schema carries the parameter burden. The description adds no parameter-specific meaning, but it does not need to because coverage is 100% and the parameter is optional.

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 clear purpose: initialize the session by returning active project, repositories, and index health in one call, plus a usage field for routing. This distinguishes it from graph-query siblings by framing it as the mandatory first call and by naming the exact aggregated data it 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?

The description gives explicit usage direction: 'Call first' establishes when to invoke it, and the conditional rule ('Non-empty repositories = proceed with graph queries; empty = tell the user to attach repos... do not fall back to Grep') tells the agent exactly when to continue and when to stop. This is strong routing guidance relative to 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful status behavior for 'version': 'indexing' means a job is in flight and retrying converges, while 'failed' carries a reason and does not change on its own. This is valuable context beyond the annotations, though pagination/auth/rate-limit details are not covered.

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

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

The description is well organized into a short intro plus a bulleted list of ops, with status semantics attached to the relevant op. It is dense but each sentence earns its place, and the structure makes the two invocation modes 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?

With no output schema, the description compensates by enumerating the fields returned by each op and defining the status enum values. It is reasonably complete for a read-only catalog tool, though it could add more detail about overall response shape or error behavior.

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 parameter-relevant meaning: it states that 'packages' takes no projectId, and it frames 'version' as resolving for a project, clarifying the role of projectId and specifier. These details go beyond what the schema states.

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 'Library catalog lookups' and names two concrete operations: listing indexed npm packages and resolving a package version for a project. It is specific about resources and scope, but does not explicitly contrast with sibling tools like quick_lookup or source, so it stops short of full differentiation.

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

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

The op descriptions give useful context: 'packages' is tenant-scoped with no projectId, while 'version' resolves one package for a project. However, there is no explicit guidance about when to prefer this tool over alternatives or when not to use it, so the agent must infer usage from the op descriptions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it reveals that the tool returns line bounds, that it is meant to be paired with source for efficient reads, and that it yields roughly 4-15x fewer tokens. This gives the agent a clear model of how the tool behaves in a workflow.

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

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

Three sentences with no filler: the first gives the core function, the second explains the intended workflow and benefit, and the third names the alternative. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a read-only list tool with one required parameter, the description is complete: it states what is returned, how to use the result, and when to choose a different sibling. The input schema handles parameter details, and annotations handle safety, so nothing critical is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents filePath, commitSha, projectId, repository, and the feedback object in detail. The description adds little parameter-level meaning beyond implying the target is a single file; it does not need to compensate because the schema carries the full burden. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List symbols in one file', and names the exact output fields ('name + kind + line bounds'). It also distinguishes itself from find_node and source by positioning the tool as the first step of a two-step read, so an agent can tell it apart from siblings 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?

The description explicitly explains when to use this tool: as Step 1 of a two-step read, with the follow-up action spelled out ('pass startLine/endLine to source (op:read)'). It also names the alternative for a different need: 'For one symbol + signature, use find_node {symbol, filePath}'. This is clear, actionable 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the tool returns all projects and includes indexing summaries, which goes beyond the annotations.

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

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

Two short sentences deliver the core function and use cases with no filler. The main action is front-loaded, and every word adds value.

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

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

For a simple list-all operation with safety annotations already provided, the description is mostly complete. It could clarify how 'find by name' works given there is no name parameter, but the core behavior is adequately specified.

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 optional feedback parameter is already documented. The description does not add parameter-level meaning, and the phrase 'find a project by name' could misleadingly imply a name parameter exists when the schema contains none. Baseline 3 is appropriate given high schema coverage.

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

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

The description uses a specific verb and resource: 'List all projects with indexing summaries.' It clearly states the tool's core function and gives two concrete use cases, though it does not explicitly distinguish itself from sibling tool list_repositories.

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

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

The description implies when to use the tool ('find a project by name or check which exist'), but it does not explain when to prefer an alternative like list_repositories or how the two tools differ. Usage guidance is present but implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is well covered. The description adds the scoping detail and hints that repository names are returned, but it does not disclose additional behavioral traits such as ordering, pagination, or output 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?

Two short sentences, both earning their place: the first states the action, the second states the practical purpose. No filler or redundant restatement.

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

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

For a simple read-only list tool, the description covers what it does and why an agent would call it. The schema handles the parameter details, and annotations handle the safety profile. A fully explicit mention of the active-project fallback or return fields would make it complete, but nothing critical 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%, with both projectId and the optional feedback object documented in the schema. The description does not provide additional parameter-level meaning beyond saying the goal is to get repository names, 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?

States a specific verb ('List') and resource ('repositories in a project') and immediately clarifies the use case: 'Find repository names to scope a query to one repo.' This differentiates it from sibling tools like list_projects and add_repository.

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

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

The description clearly implies when to use this tool: when you need repository names to scope a query to one repo. It does not explicitly mention alternatives or exclusions, but the intended context is clear and helpful.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructiveness, so the safety profile is covered. The description adds useful behavior like case-insensitive substring matching and that output is intended to be mirrored, but it does not disclose result ordering, pagination, limits, or error cases.

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

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

Two short sentences carry both the core behavior and the primary use case with no filler. The action and object are front-loaded in the first sentence.

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

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

Despite having no output schema, the description tells the agent what entities are returned (test suites and cases) and that they can be mirrored as templates. With 100% schema description coverage for the five parameters plus safety annotations, an agent has enough to select and invoke the tool correctly.

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

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

Schema descriptions cover 100% of parameters, so the baseline is met. The description goes slightly beyond the schema by specifying that matching is a case-insensitive substring and that the selector denotes a symbol name, which clarifies how the required selector will be interpreted.

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: it lists 'Test suites and cases' matching a symbol name, and adds precise matching semantics with 'case-insensitive substring'. This clearly differentiates it from sibling tools like list_file_symbols or find_node, which are not test-focused.

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?

'Call before adding tests to see existing coverage and mirror its shape' gives an explicit when-to-use context tied to a concrete workflow. It does not enumerate alternatives or when-not-to-use, so it stops short of a full 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: AUTO-ROUTE fallback logic, per-mode result caps, pathsOnly token savings, did_you_mean on empty results, tests-last behavior, moreInFileTruncated, and answered_by in responses. This gives an agent a realistic model of side effects and edge cases without contradicting the annotations.

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

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

The description is long but tightly organized by mode, with each line earning its place and critical routing rules front-loaded in the opening sentence. Despite covering six modes and many parameters, it avoids repetition and is 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 tool with 16 parameters, no required fields, no output schema, and six modes, the description covers invocation behavior, defaults, constraints, and important response markers. It still leaves some return-structure details unspecified, but the annotation safety profile and exhaustive parameter guidance make the tool safely callable.

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 every parameter, but the description adds high-value semantics: queries implies text mode, pathsOnly is ~5x cheaper, maxPerFile=0 means uncapped, limit has per-mode caps, and repositoryIds applies only to codebase mode. This meaningfully improves parameter understanding beyond the raw schema.

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

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

The description clearly identifies a multi-mode search/lookup tool and specifies each mode (text, symbol, semantic, file, config, codebase), which is far more specific than the name alone. However, it never explicitly distinguishes locate from sibling tools like quick_lookup or find_node, so an agent must infer overlap from the mode descriptions.

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

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

The description gives strong mode-selection guidance: use semantic when names are unknown, text for literal identifiers, file for fuzzy filenames, and config for env/config keys. It also warns not to retry reworded empty text queries and to switch to semantic instead. It does not explicitly compare locate with sibling tools, so cross-tool routing is left implicit.

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

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

Annotations already declare readOnly and idempotent hints, and the description adds substantial behavioral detail beyond that: output shape, token-efficiency, provisional module names with stable ids, and architecture-mode clustering behavior. This is exactly the kind of context an agent needs beyond structured annotations.

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

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

The description is dense but every sentence contributes. The main purpose is front-loaded, and the parameter guidance is compactly woven in. The architecture-view sentence is long but packs essential caveats without waste.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so for both views: directory skeleton details and architecture module-map details. It also explains the module-name/id stability caveat and key parameter levers, making the tool callable without further inference.

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 real semantic value for path, maxDepth, density, and especially view—explaining what the architecture view returns and why module ids matter. It avoids repeating schema-only details for the remaining parameters.

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

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

The description clearly states what the tool returns: a token-efficient repo/subtree skeleton with classes, methods, functions, and HTTP endpoints. It also distinguishes the two views (tree vs architecture), making it easy for an agent to tell this orientation tool apart from sibling tools like source or list_file_symbols.

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

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

The description provides explicit usage context: 'Orient before drilling in' tells the agent when map is appropriate, and it explains how to scope, cap, and switch views. It doesn't explicitly name sibling alternatives or say when not to use it, but the guidance is clear enough for correct selection.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds behavioral detail beyond that: no ranking, no semantic search, reads the latest indexed revision, and no ref pin. This helps the agent set expectations about result quality and version consistency.

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

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

Three dense sentences with no filler: output format and caveats come first, usage context and alternatives second, revision semantics third. Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

Despite having no output schema, the description enumerates the returned rows and field semantics. The parameter schema is rich and fully documented, so optional parameters like feedback do not need to be re-explained here. The description is complete for correct invocation and expectation-setting.

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 five parameters, including limit, query, feedback, projectId, and repository. The description adds useful context about result shape and matching behavior but does not need to repeat parameter details.

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

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

States a specific verb and resource: 'Fast substring lookup of symbol DEFINITIONS by name' and enumerates the exact output row fields. It also explicitly differentiates itself from locate and find_node, so an agent can distinguish it 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?

Gives explicit when-to-use guidance: a cheaper alternative to locate (mode:symbol) for latency-sensitive pre-fetch in a grep-augment hook. It also states when not to use it: interactive search should prefer locate/find_node, naming the alternatives directly.

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 readOnlyHint=false already signaling mutation, the description adds valuable behavioral context: state is session-scoped, index_working_tree pins a short-lived synthetic revision, clear reverts to the default, and there is a 100-file/256KB cap. The disclosure is strong, but the undocumented 'commitSha overrides' claim and lack of clarity about what happens on success reduce full 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 bulleted operation list is compact, front-loaded with a summary, and contains nearly no filler. The final 'index_working_tree' bullet is dense and slightly run-on, and the unresolved 'commitSha overrides' fragment hurts readability, so it is not quite top-tier.

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 stateful tool with no output schema, the description covers invocation preconditions, side effects, failure modes, caps, and interactions with sibling tools well. It is incomplete only around the success/error response contract and the unexplained commitSha reference, leaving some room for agent confusion.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add meaningful context for branch, baseSha, changedFiles, and deletedPaths (e.g., tracked/indexed requirement, synthetic revision, tool visibility). However, the description explicitly mentions a 'commitSha' override that is absent from the schema, which is a concrete parameter-semantics defect that could mislead an agent.

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 crisp summary ('Session-scoped branch / working-tree overlay') and enumerates three distinct operations with their effects, so an agent can see what the tool does without opening the schema. It loses a point because the phrase 'commitSha overrides' references a parameter that does not exist in the input schema, creating ambiguity about the exact behavior.

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 concrete preconditions ('Branch must be tracked+indexed... else indexing_in_progress') and names which sibling tools reflect the overlay (find_node/locate/relate) versus those that do not (source, locate mode:semantic). It does not explicitly say when to prefer this over alternative tools, but for a state-overlay tool the operation-specific conditions provide adequate 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?

The description discloses meaningful internal behavior: force bypasses per-file hash-skip, re-runs SCIP subprocesses, and avoids serving a same-sha .scip cache. This goes well beyond the annotations, though it does not explain whether the dispatch is asynchronous or what the response/return value looks like.

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

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

The description is front-loaded with the core action and then efficiently expands on the important force flag. Every clause earns its place, and the two-sentence structure makes the key behavior easy to parse without burying it in filler.

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

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

For a dispatch-style tool, the description gives enough context to select and invoke it correctly: target repository, optional commit pin, and force semantics. It lacks only a note about what the call returns or that the job may run asynchronously, which would round out the picture given there is no output schema.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining why force:true is needed for parser fixes, external-moniker re-pins, and toolchain upgrades, and by anchoring repositoryId to the list_repositories/add_repository flow.

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

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

The description uses a specific verb ('Dispatch') and names the resource ('a reindex job') plus the exact scope: an already-attached repository. It also clarifies the source of repositoryId, which distinguishes it from repository management tools like add_repository or list_repositories.

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

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

The description clearly states the prerequisite (repository already attached) and where to get the repositoryId, and it gives concrete scenarios for when to use force:true. It does not explicitly contrast with alternatives like add_repository, but the intended usage path is still 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds substantial behavioral detail beyond those: blastRadiusTotalCount is distinct-symbol count rather than row count, blastRadiusTruncated and blastRadiusTotalAtLeast describe sampling/bounds, and the explicit warning 'Never report the number of listed rows as the impact size' is a critical agent-facing caveat. It also discloses cost behavior for minimal and per-kind parameter effects.

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

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

Although long, the description is information-dense and organized by kind with terse, purposeful clauses. Every sentence adds operational guidance, and the high complexity of a 24-parameter graph traversal tool justifies the length. The front-loaded purpose statement and scannable kind list make the structure 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 having 24 parameters and no output schema, the description covers per-kind behavior, defaults, truncation semantics, cross-repo behavior, confidence/package row details, fallback guidance, and error reasons. It addresses the most dangerous misinterpretation of blast_radius results directly. For this tool's complexity, the description is remarkably complete on its own.

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 real semantic value beyond the schema: it clarifies that blastRadiusTotalCount is not the row count, that expansionLimit caps the array, that includeCrossRepo defaults differ by kind, and that minimal:true is ~50% cheaper. These details are not inferable from the schema alone, so the description earns 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 opening line 'Graph relationship traversal via one kind (real edges, not text)' names a specific verb, resource, and scope, and directly distinguishes graph edges from text search. The per-kind breakdown (callers, dependencies, blast_radius, heritage, chain, path) makes the tool's role concrete. It also names locate as the text-based alternative, which further disambiguates it from siblings.

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

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

The description gives clear usage context for each kind and explicitly says '0 results: call locate (mode:text), not Grep', providing a concrete when-to-use/alternative rule. It also explains edge-case semantics like includeCrossRepo defaults and blast_radius truncation. It does not explicitly contrast the tool with non-text graph siblings such as ref or diff_impact, so it stops short of complete sibling differentiation.

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

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

Beyond the read/idempotent annotations, the description discloses operational details: reads happen at the indexed commit, ifHash suppresses content when unchanged, compact strips blank/comment-only lines, and each op's core behavior is summarized. No annotation contradiction exists; 'diff' and 'blame' are read-style introspection against git objects.

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 definition is densely packed but front-loaded with the reason for existence, then organized as a scannable op list, key examples, and a gating note. Every sentence adds operational value; there is no filler or repetition of 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?

For a 7-op, 19-parameter tool with no output schema, the description covers scope, operation semantics, key parameter roles, representative call shapes, and access requirements. The remaining return-shape details are minor and inferable from the op names and schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable clarifications: the key examples show canonical argument shapes, 'filePath is the file, path the directory' disambiguates two overloaded parameters, and the op list maps operations to required arguments. This goes beyond a bare schema repeat.

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 line names a specific resource ('raw file/git access at the indexed commit'), ties it to a clear audience (cloud agents with no clone), and distinguishes it from local Read/Grep/git. The operation list then makes the tool's 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?

It explicitly states when to use this tool ('for cloud agents with no clone') and when not to ('with a clone prefer your own Read/Grep/git'). It also surfaces the prerequisite gate ('Gated by the Source Access add-on; else source_access_required'), so the agent can predict availability.

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