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

Annotations already declare readOnly/idempotent/non-destructive, and the description earns credit for adding caveats the annotations cannot: complexity is cyclomatic and therefore approximate, and dead-code entries merely lack a static caller, so they must be verified before deletion. 'Read-only' restates the annotation but the accuracy and deletion-safety warnings are real added value.

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?

Front-loaded with the purpose, then use cases, then the parameter, then the caveats; each sentence carries a distinct payload. The only slack is the redundant 'Read-only' clause already covered by annotations.

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

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

An output schema exists, so return values need not be described, and the description covers scope, filtering, what analyses are produced and their accuracy limits. For a zero-required-parameter, read-only analysis tool this is everything an agent needs before calling it.

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

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

Schema coverage is 100% and the single `path` parameter is already documented as an optional relative path filtering a subdirectory or file. The description's 'Pass `path` (relative) to limit it to a directory or file' largely restates that, so the baseline 3 applies.

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

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

States a specific verb and resource ('review the quality of the indexed project, or of one path') and enumerates the concrete outputs: complex/long functions, large classes, dead code, module dependencies, overall score. It does not name any sibling tool, so the agent has to infer the boundary with `graph` or `map` on its own, which keeps it just short of a 5.

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 concrete trigger phrases ('what is the most complex code', 'review this directory', 'is there dead code') and tells the caller to pass `path` to narrow to a directory or file. No exclusion or 'use X instead' guidance is given, so nothing prevents overlap confusion with `graph` or `search`, but the positive usage context is strong.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description instead discloses non-obvious behaviors: classes over 2,000 chars return an outline, other code over 6,000 chars is cut and marked `(truncated)`, and several names can be batched in one call. It doesn't mention ordering or how missing symbols are reported, which is a minor gap given an output schema exists.

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?

Front-loaded with the verb and the returned artifact, then usage examples, then caveats. Dense but nearly every clause carries information; the truncation thresholds are the only slightly over-specified part, though they change how the agent interprets output.

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 two-parameter read tool with a full output schema, the description covers purpose, alternatives, batching, naming patterns and output truncation. Nothing an agent needs in order 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% (both parameters documented), so the baseline is 3. The description adds real meaning on top: comma-separated multi-name batching, the "Class.method" addressing form for method bodies, and the intent behind exact=false (match part of a name when unsure of spelling).

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 (look up functions, classes, methods or constants by name) plus what comes back (code, file, line range, callers and callees). It explicitly separates itself from file reads/greps and points to `graph` for a different question, so an agent can distinguish it from siblings 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?

Gives concrete when-to-use triggers ("show me create_order", "where is TokenBudget defined") and a when-not-to-use rule: use `graph` for every use of a name, and don't use a file read or grep for a definition. Alternatives are named explicitly.

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, and the description goes further with the key limitation: edges are static, so callbacks, reflection and dynamic dispatch are absent from caller lists, while `references` still surfaces those lines. It also pre-announces the shape of a callers result (whole-word source lines, test files as counts), which is exactly the context an agent needs before trusting the output.

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

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

Front-loaded with the core verb and both directions, then the risk-analysis use case, then the caveat — a sensible ordering. The parentheticals ('what breaks if I change X', the grep aside) are dense but each carries information, so no sentence is wasted.

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

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

For a 3-param read-only analysis tool with an output schema, this covers everything: what it returns for each direction, the extra `references` channel, and the static-analysis blind spot. Nothing an agent needs to call it correctly or interpret results 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, but the description adds real meaning: it spells out the consequence of transitive=true ('everything that depends on the symbol, directly or indirectly') and the purpose of the references payload. It stops short of adding anything the schema lacks for direction/symbol_name.

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

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

Opens with a specific verb and resource ('Trace the call graph') and immediately disambiguates the two modes via direction='callers'/'callees'. An agent can tell this apart from search/find_symbol without consulting 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?

Gives an explicit use case with a condition: use transitive before changing a signature or renaming/moving/deleting a shared function ('what breaks if I change X'). It also names grep as the alternative it replaces, but never mentions sibling tools like find_symbol or search, so routing between MCP tools 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?

Adds behavior beyond annotations: indexing is incremental when an index exists, a file watcher maintains freshness afterward, large repositories take time, and progress is reported. Annotations already cover the mutation/idempotency profile, but the description usefully clarifies runtime 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?

Front-loads the core action, then immediately explains when to call it and what depends on it. Every sentence adds operational value, including the monorepo path note and watcher behavior, 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 annotations, full schema coverage, and an output schema, the description provides everything needed to decide when to call it and how to pass paths. It also covers incremental behavior, watcher freshness, runtime expectations, and progress reporting.

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 already documents both path parameters as absolute and comma-separated. The description repeats the monorepo comma-separated usage but adds no parameter detail beyond the schema, so 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?

States a specific verb and resource: build or refresh the code index for a project. It clearly distinguishes this from siblings such as status, search, find_symbol, graph, map, and analyze by naming them as dependent tools rather than equivalents.

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 invocation guidance: call once per project when status says indexed is false, and explains that search, find_symbol, graph, map, and analyze all need the index. It also says the file watcher keeps it fresh, so repeat calls are rarely 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds what each mode surfaces (files/languages/quality vs layers/dependencies/entry points), but says nothing about output size, cost, or whether 'full' is expensive on large repositories — the main behavioral risk for an overview tool.

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

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

Front-loaded with the core purpose, then intent examples, then mode semantics, then usage timing — a sensible order with little waste. There is mild redundancy between the description's mode list and the enum's own descriptions, but nothing is padded.

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

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

With an output schema present, the description need not explain return values, and the single optional parameter is fully covered; annotations cover safety. The only meaningful gap is guidance on when the richer 'architecture'/'full' modes are worth the extra output versus defaulting to 'summary'.

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 single enum is already documented in the schema; the description's mode explanations largely restate that text ('full' gives both appears in both places). Baseline 3 applies since the schema does the work and the description adds only minor rephrasing.

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 ('Get an overview of the project') and reinforces it with real user phrasings ('how is this structured', 'where do I start') plus a breakdown of the three detail modes. It does not explicitly name or contrast the siblings (search, find_symbol, graph, status), so an agent must infer that this is the orientation tool rather than a lookup 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?

Gives clear timing guidance: 'Use it at the start of work in an unfamiliar repository, before you list directories or open files one by one.' That establishes when to use it and steers away from manual exploration, but it names no alternative sibling (e.g. status or index) and gives no when-not condition, such as skipping it in a repo you already know.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: notes are persisted to the project's .nexus index and retrieval is semantic rather than keyword-based. It stops short of stating whether deletes are recoverable, so it is not a 5.

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 core purpose is front-loaded and each sentence carries actionable content (purpose, per-action triggers, storage/semantics). It runs slightly long across multiple lines, but no sentence 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?

With an output schema present and 100% schema description coverage, the description needn't explain return values and correctly focuses on usage. What remains unstated is deletion recovery behavior, a minor gap given the destructive annotation.

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 goes beyond it by tying parameters to actions in prose, notably that delete can target by ID or tags and that search matches by meaning — clarifications that help disambiguate the tags parameter's role across actions.

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 pair ('keep and recall project knowledge') and enumerates the three concrete actions (store/search/delete). It differentiates from the sibling 'search' tool by clarifying notes are 'found by meaning, not by exact words' and scoped to the project's .nexus 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?

It names explicit trigger phrases for each action: 'remember that...' or a decision for store, 'what did we decide about...' for search, and removal of outdated notes by ID or tags for delete. The agent knows exactly when to pick each branch without 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?

Annotations already declare read-only/idempotent, and the description adds genuinely useful beyond-schema behavior: ranked results with file path and line range, the top three containing whole definitions, and source-before-test ranking. It stops short of saying how ranking is scored or when the index may be stale, which would matter for trust.

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?

Front-loaded with purpose then escalating detail (result shape, query syntax, fallbacks), and every sentence carries an actionable rule. Slightly long, and the exact-names-first point is stated twice (prose and again in the schema-echoed phrasing at the end).

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 2-parameter search tool with an output schema, this covers everything an agent needs: how to phrase a query, what a result contains, how many are trustworthy without opening files, and which sibling to reach for otherwise.

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 meaning the schema lacks: multi-name queries ('parse_config RetryPolicy') resolve exact definitions first. The `limit` parameter is left entirely to the schema, which is fine.

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 ('Find code by meaning or by keyword') and immediately grounds it in real query phrasings. It explicitly separates itself from siblings by naming `find_symbol` for truncated results and built-in grep/read for exact strings.

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 concrete when-to-use trigger phrases, states the condition for switching to `find_symbol` (result is cut), and explicitly says when a built-in tool is just as good. Both an alternative tool and an exclusion are named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add real behavioral context: a prior session's index is auto-attached at startup, and a stale index triggers an automatic background reindex. That auto-reindex disclosure is valuable because it explains why an agent should not panic over staleness. Points withheld because the enumerated return fields duplicate the existing output schema rather than adding new behavioral information.

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?

Purpose is front-loaded in the first sentence, followed by the when-to-use guidance and then return contents. Mostly tight, but the middle list of return fields (counts, engines, memory) is a partial restatement of the output schema and could be trimmed 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 zero-parameter, read-only status tool with rich annotations and an output schema, the description supplies everything an agent needs: what it reports, when to call it, that it is not a prerequisite, and what to do on a false result.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly does not waste space inventing inputs.

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: checks whether the project is indexed and whether the index is fresh. It is clearly distinguishable from siblings like `index`, `search`, and `map`, and an agent knows immediately this is a health/state check rather than a query.

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

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

Explicitly says when NOT to call it ('You do not need it before other nexus tools: an index saved in an earlier session is attached when the server starts'), names the triggering condition ('Use it when a tool says "No codebase indexed"'), and routes to the alternative ('If `indexed` is false, call `index`'). This is the strongest form of routing guidance.

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