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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows this is a safe, non-mutating operation. The description adds behavioral context by enumerating the specific risk heuristics (typosquatting, unpinned versions, abandoned packages), which clarifies the tool's analytical scope beyond a simple dependency listing.

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

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

The description is a single, compact sentence that is front-loaded with the core purpose and immediately enumerates the heuristics, providing maximum information per word.

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, zero-parameter tool with annotations covering safety, the description covers the essential purpose and risk categories. It lacks an explicit output format, but no output schema exists, and the description is sufficient for an AI to understand when to invoke 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?

The tool takes zero parameters, so the baseline is 4; the description correctly does not attempt to document parameter details. Schema coverage is trivially 100%, and no parameter semantics are needed.

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

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

The description clearly identifies the tool as a dependency inventory with risk heuristics, distinguishing it from the sibling nexus_dependency_graph by focusing on typosquatting, unpinned versions, and abandoned packages. While it lacks an explicit verb, the intent is unambiguous.

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

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

The description implies use cases (auditing dependencies for supply-chain risks) but does not explicitly state when to choose this over alternatives like nexus_dependency_graph or nexus_impact_analysis. No exclusions or alternative tool guidance is provided.

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

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

Annotations already declare the tool as read-only and idempotent, so the safety profile is clear. The description adds no behavioral details beyond the purpose, such as return format, pagination, or any side effects. With annotations covering the safety aspect, a score of 3 is appropriate.

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

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

The description is extremely concise and front-loaded, using only essential words to convey the tool's function. Every word is meaningful, and there is no redundant information. It is appropriately sized for a tool with a simple purpose.

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

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

Given the tool's simplicity and the presence of read-only annotations, the description provides a minimal viable explanation. However, it does not describe the output format, nor does it clarify how this differs from closely related sibling tools like nexus_references or nexus_dependency_graph. Additional context would help an agent select the correct tool, but the description is not wholly inadequate.

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

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

The schema only provides a description for 'symbol' (33% coverage), so the description must clarify 'depth' and 'direction'. The phrase 'depth-N' and 'callers or callees' partially compensates by explaining the role of depth and direction, but it does not mention default values or range constraints, which are only available in the schema. This adds some value but not full compensation.

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 'Callers or callees of a function, depth-N' precisely states the tool's purpose: it returns the callers or callees of a given function up to a specified depth. This distinguishes it from sibling tools like nexus_references or nexus_dependency_graph by focusing specifically on function call relationships with a depth parameter.

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 does not explicitly say when to use this tool versus alternatives such as nexus_references or nexus_dependency_graph. However, the name and phrase 'callers or callees' imply when it is appropriate, and the absence of exclusions or alternative recommendations leaves usage guidance implied 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 and idempotentHint=true, so the safety profile is covered. The description adds value by listing the bundle's composition (repo map slice, symbol outlines, related files), but it does not disclose any limitations, defaults, or how 'related files' are determined. No contradictions with annotations.

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

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

The description is a single, front-loaded phrase with a colon-separated list. Every word contributes to the meaning, with no filler or redundancy. It is concise and well-structured for quick scanning.

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 should explain return value structure and usage context more thoroughly. It lists bundle components but lacks details on how related files are selected, what format the output takes, and any prerequisites. The brevity leaves significant gaps for an agent deciding whether and how to invoke 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 50% (only focusFiles has a description). The description does not mention the parameters at all, so it adds no meaning beyond the schema. maxTokens lacks any description and the relationship between focusFiles and the generated bundle is unclear, requiring the agent to infer usage.

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 a task-focused context bundle composed of repo map slice, symbol outlines, and related files. This is a specific noun phrase that distinguishes it from sibling tools like nexus_repo_map or nexus_file_symbols, though it lacks a verb to indicate the action.

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

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

The description offers minimal guidance on when to use this tool. The phrase 'task-focused' implies it is for task context gathering, but there is no explicit comparison to alternatives or mention of when not to use it. This leaves the agent without clear decision criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint as true, so the safety profile is covered. The description adds semantic clarity for dependencies vs dependents but does not disclose behavioral details such as output format, traversal depth, cycle handling, or potential large-result considerations.

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

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

The description is a single sentence that is front-loaded with the verb and resource, contains no filler, and remains entirely focused. Every word contributes to understanding the tool's purpose.

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

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

For a read-only query with clear parameters and annotations, the description covers the core use case. However, since there is no output schema, the description does not mention what the returned dependency information looks like (e.g., list, graph, nesting), leaving agents to infer the return format from the tool name.

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 50%: the 'file' parameter is already documented as a workspace-relative path, while 'direction' has no textual description beyond its enum. The tool description compensates by explaining the direction values ('what it depends on' vs 'what depends on it'), adding real meaning beyond the schema.

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

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

The description uses a specific verb ('Import') and identifies the resource ('dependencies of a file' or 'dependents'), with parentheticals defining both directions. It is clear and unambiguous, but it does not explicitly distinguish the tool from sibling tools like nexus_references or nexus_impact_analysis.

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

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

The description implies when to use the tool: when you need a file's dependencies or dependents. However, it provides no explicit guidance on alternatives, exclusions, or when not to use this tool, and it does not reference any sibling tools.

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 outputs from tsc/eslint are parsed into structured diagnostics, which is extra behavioral detail beyond the sparse openWorldHint annotation. It does not mention potential side effects or error handling, but for a read-only analysis tool this is acceptable.

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 front-load the primary action and then summarize the output format. No redundant or vague words; every phrase earns its place.

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

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

The description provides the essential purpose and the structured output format. It does not mention defaults or failure behavior, but the schema clarifies defaults (both booleans true, files all). For a relatively simple tool, it is sufficiently complete.

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

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

The description names tsc and eslint, giving meaning to the boolean parameters, but does not explain the files parameter. Schema coverage is only 33%, yet the files parameter is described in the schema. The description partially compensates for low coverage but not fully.

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 runs typecheck (tsc) and linter (eslint) and parses output into structured diagnostics. This is a specific verb+resource with a defined output, distinguishing it from siblings like nexus_test_run or nexus_exec.

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

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

The description implies usage for static analysis/typechecking/linting, which is clear from naming tsc and eslint. It does not explicitly state alternatives or exclusions, but no sibling tool directly competes with this functionality, so the context is clear.

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

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

Annotations are minimal (only openWorldHint), so the description carries the transparency burden. It does disclose notable behaviors: ring-buffer output, secret redaction, and process-group kill on timeout. However, it omits important safety semantics such as the requirement to set allowDangerous for dangerous commands, and it doesn't describe background execution behavior.

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

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

The description is compact and efficient—just two sentences that front-load the primary action and then list key features. No redundant or filler content. Every word contributes to understanding.

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 its apparent simplicity, the tool has complex behaviors (timeout, ring-buffer, secret redaction, background jobs, allowDangerous) and no output schema. The description does not clarify return values, output format, polling implications (especially with nexus_exec_poll as a sibling), or failure modes. This makes the description under-specified for reliable use.

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

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

The schema already describes 4 of 5 parameters with meaningful text. The description adds 'timeout' which aligns with timeoutMs, but this is a generic mention. It does not enrich understanding of args, background, or allowDangerous beyond their existing schema descriptions. Overall, the description adds modest value for parameters.

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

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

The description clearly states 'Run a command' and lists specific behaviors: timeout, ring-buffer output, secret redaction, and process-group kill. This makes the tool's purpose unambiguous, but it does not explicitly contrast with sibling tools like nexus_test_run or nexus_exec_poll, so it lacks direct sibling differentiation.

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

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

The description offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, likely use cases, or exclusions. The only contextual signal is the openWorldHint annotation, which is not elaborated. Users are left to infer when nexus_exec 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?

There is a direct annotation contradiction: readOnlyHint=true while the description includes 'kill' which is a destructive action. This is a serious inconsistency that misleads the agent about behavioral safety. No additional behavioral context is provided.

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

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

The description is a single sentence of eight words, front-loaded with the actions. Every word is necessary, and it is immediately 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 no output schema, the description offers no information about return values, side effects of 'kill', or the necessity of jobId per action. The annotation contradiction also undermines completeness, and the missing guidance on parameter usage leaves the agent under-informed.

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

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

The schema coverage is only 50% (jobId has no description), and the tool description adds no parameter-specific meaning. It does not clarify that jobId is likely required for 'poll' and 'kill' but not for 'list', nor does it explain the meaning of jobId. The enums are simply restated from the schema.

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

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

The description uses clear verbs ('Poll, list, or kill') against a defined resource ('background exec jobs'), making the tool's scope unambiguous. It distinguishes from sibling tools like nexus_exec by focusing on managing existing background jobs rather than starting them.

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

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

The description implies usage context (managing background exec jobs), but does not explicitly state when to use this tool versus alternatives such as nexus_exec. No exclusions or alternative tools are mentioned, leaving the agent to infer the differentiation from the tool name and sibling list.

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

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

The description mentions a key behavioral trait: concurrency limit. It also implies that the command is executed per item. With only openWorldHint as an annotation, the description adds some useful context beyond annotations. However, it does not disclose other important behaviors such as whether the tool blocks until completion, returns output, or has side effects. The transparency is adequate but not rich.

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

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

The description is a single concise sentence, front-loaded with 'Parallel map' to immediately convey the core concept. There is no redundant or extraneous text. Every word 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 tool with moderate complexity (command template, items, concurrency, timeout) and no output schema, the description gives a good high-level overview but omits critical details like return values, error handling, and whether execution is synchronous or asynchronous. These gaps are significant for an agent deciding how to use the tool correctly. The description is adequate for basic understanding but incomplete for full guidance.

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 only 50%, so the description needs to compensate. 'concurrency limit' adds meaning to the concurrency parameter beyond its schema (which only has min/max/default). The phrase 'run a command over multiple items' helps clarify the items and command parameters. However, timeoutMs is not mentioned, and the description does not fully compensate for the missing schema descriptions. It provides some additional semantics but not a complete picture.

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

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

The description clearly states what the tool does: 'Parallel map: run a command over multiple items with concurrency limit.' It uses a specific verb ('run'), identifies the resource ('command over multiple items'), and distinguishes it from likely siblings like nexus_exec (which probably runs a single command) by emphasizing parallel fan-out. This is a specific and differentiating purpose statement.

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

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

The description gives clear context for when to use the tool: when you need to run a command over multiple items in parallel. The label 'Parallel map' implies a batch-processing scenario. However, it does not explicitly mention when not to use it or name alternatives (e.g., nexus_exec for single commands), so it falls short of a 5. Still, the context is clear and implied.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds useful context about the scope of symbols (functions, classes, types) but discloses no further behavioral traits such as output format or limitations.

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

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

The description is a single, concise sentence that front-loads the verb and resource. Every word adds value, and it is appropriately sized for the tool's simplicity.

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 tool with one parameter and strong annotations, the description is complete enough. It clearly states what the tool does and what input is required. The lack of an output schema is offset by the explicit enumeration of symbol types, making the expected result reasonably clear.

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

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

The input schema covers 100% of the single parameter with a clear description ('Workspace-relative path'). The tool description reinforces the meaning of 'file' by mentioning it in the main sentence. No additional parameter semantics are needed.

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

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

The description states a specific action ('Get the symbol outline of a file') and clarifies what kind of outline (functions, classes, types). It is clear and actionable, but it doesn't explicitly differentiate from sibling tools like nexus_find_symbols, which might also deal with 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?

No guidance is provided about when to use this tool versus alternatives. The description simply explains what it does without mentioning scenarios, prerequisites, or exclusions.

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

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

Annotations already declare read-only and idempotent behavior. The description adds context that the search is 'fuzzy' (tolerant of partial names) and spans the 'entire workspace.' However, it doesn't disclose additional traits like case sensitivity, ordering of results, or potential dependence on a prebuilt index (given the sibling nexus_index_build). So it adds some value but not deep 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 a single, front-loaded sentence with no fluff. Every word serves a purpose: 'fuzzy,' 'symbols,' 'across the entire workspace.' It is efficient and easy to parse.

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

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

The tool is simple with schema covering most params and annotations covering safety, but there is no output schema and no mention of return format or indexing requirements. For a search tool, a complete description might note what to expect in results or whether an index is needed; these gaps keep it from being fully complete, yet the core purpose is captured adequately.

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

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

The schema already describes 'name' and 'kind' with descriptive text, covering 67% of parameters. The description does not add details beyond that; 'fuzzy' implicitly reinforces partial matching for name, but limit and kind are not elaborated in the prose. Schema's built-in descriptions and constraints handle the heavy lifting, 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?

The description uses a specific verb 'search' and a clear resource 'symbols' with scope 'across the entire workspace.' It effectively differentiates from sibling tools like nexus_file_symbols (symbols in a file) and nexus_references (references to a symbol), and 'fuzzy' signals partial matching. No ambiguity.

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

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

There is no explicit guidance on when to prefer this tool over alternatives. It doesn't mention when not to use it or name any sibling tool for other scenarios. The implied use is finding any symbol by name workspace-wide, but no exclusions or comparisons are provided, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds valuable behavioral details not in the annotations: pagination behavior and binary file flagging. These traits help the agent understand what to expect from the output without overexplaining.

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

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

The description is concise, consisting of two short, front-loaded sentences. It communicates the core functionality and key features without any wasteful words 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?

The tool has only one parameter and no output schema, so the description must convey return behavior. It mentions stat summary, paginated hunks, and binary file flagging, giving a basic but adequate sense of the output. However, it does not explain how pagination is handled (e.g., page tokens), which is a notable gap for a tool without an 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?

The input schema fully describes the single 'staged' parameter with a default value and description (100% coverage). The description does not add any extra meaning about the parameter, so it adds no value beyond the schema. 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 clearly identifies the tool as a git diff viewer, specifying that it provides a stat summary, paginated hunks, and flags binary files. This goes beyond a simple restatement and distinguishes it from sibling tools, none of which are git diff-related.

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 its usage (for viewing git diffs) but does not explicitly state when to use it versus alternatives or provide any exclusions. There are no sibling diff tools to differentiate from, so the lack of explicit alternatives is acceptable, but the guidance is only implied.

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 declare readOnlyHint=true and idempotentHint=true, and the description does not contradict these. It adds useful behavioral context by describing the content (workflows, recipes, gotchas), which goes beyond the 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 a single, front-loaded sentence with no redundant information. Every word contributes to conveying the tool's purpose.

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

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

For a simple tool with one optional parameter and no output schema, the description provides sufficient context about its purpose. It does not describe the return format, but the input schema covers the only input, making this adequate.

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

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

The schema fully describes the single optional 'topic' parameter with an example, achieving 100% coverage. The description does not add additional parameter-level meaning, but none is necessary given the schema's clarity.

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

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

The description clearly identifies the tool as an on-demand playbook providing workflows, recipes, and gotchas for using NEXUS. It distinguishes itself from sibling tools by its guidance-centric focus, though it lacks an explicit action verb like 'provides' or '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 usage is implied by the phrase 'on-demand playbook'—users should query it for guidance on specific topics. However, there is no explicit guidance on when to use this tool over alternatives, nor any exclusions or alternative tool mentions.

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. The description adds the method (reverse reachability) and scope (dependency/call graph), giving more insight into tool behavior without contradicting annotations.

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

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

Two crisp sentences, front-loaded with purpose, no filler. 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?

Description covers both purpose and method. With annotations and schema, it's sufficiently complete for an agent to select and invoke the tool, though output format is not 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 documents target and mode with 50% coverage. Description connects 'symbol or file' to the mode parameter, adding meaning to the enum values. It also clarifies that target can be either a symbol name or file path.

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

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

The description clearly states the tool's function: identify the blast radius of editing a symbol or file. It uses specific terms like 'reverse reachability' and 'dependency/call graph' that distinguish it from sibling tools such as references or call graph.

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

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

Provides clear context: use when evaluating the impact of an edit. It doesn't explicitly name alternatives or exclusions, but the context is sufficient for an agent to know when to employ the tool.

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

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

The description says 'Build or refresh', which implies a state-changing/write operation. Yet the annotations declare readOnlyHint=true, which is a direct contradiction. This is a serious safety signal mismatch and fails to disclose the index mutation behavior.

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

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

The description is two short sentences, immediately stating the action and its prerequisite. Every word earns its place; there is no fluff 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?

For a simple one-parameter tool, the description covers the key context: what it does, what it contains, and the required usage context. However, it does not mention return values or side effects, and the contradiction with readOnlyHint leaves a gap in safety context.

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

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

The schema covers 100% of parameters, including a clear description for 'force' ('Force full rebuild (ignore incremental cache)'). The description adds no extra meaning beyond the schema, 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?

The description uses a specific verb phrase ('Build or refresh') and identifies the resource ('the code index') with contents ('symbols, imports, calls'). This clearly distinguishes it from sibling code-intel tools like nexus_file_symbols or nexus_references that consume the index.

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

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

It explicitly states it is 'Required before code-intel tools,' giving clear when-to-use guidance. However, it does not mention when it might be unnecessary (e.g., if the index is already fresh) or provide alternative tools, so it's not a perfect 5.

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

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

Annotations already indicate destructiveHint and idempotentHint, and the description repeats 'DESTRUCTIVE' but adds new context 'Audit-logged', which is a behavioral trait not present in annotations. The matching method is also revealed, though partly covered by schema.

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

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

Two concise sentences: the first states the core action, the second adds audit and destructive warnings. Every word earns its place, and critical 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?

Given the tool's simplicity (one parameter, high schema coverage, annotations for destructive/idempotent), the description is mostly complete. It covers purpose, input method, and audit logging. The main gap is the lack of clarification on how text matching behaves (exact vs partial), but this is not critical for basic usage.

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

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

The schema already provides 100% coverage of the single parameter with 'Memory ID or text to match and remove'. The description merely restates this without adding examples, constraints, or details on matching semantics (e.g., exact vs substring), so it adds no additional parameter meaning.

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

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

The description clearly states the verb 'Delete' against the resource 'memories' and specifies the method 'by ID or text match'. This unambiguously differentiates it from sibling tools like nexus_memory_search or nexus_memory_write.

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

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

The description implies usage (when you want to delete memories) but provides no explicit guidance on alternatives or when not to use it. It does not mention using nexus_memory_search to find IDs first, leaving alternatives to be inferred.

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 declare readOnlyHint and idempotentHint, so safety is already established. The description adds no further behavioral context beyond the search dimensions, such as return format or pagination behavior, and does not 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 a single, front-loaded sentence with no filler or repetition. Every word contributes to understanding the tool's purpose and key parameters.

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 simple tool, strong annotations, and schema covering most parameters, the description is adequate. It lacks explicit guidance on when to use this tool versus sibling nexus_search, and does not describe return values, but these are non-critical for a straightforward read-only search.

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 75%, with descriptions for tags, text, and namespace, but not for limit. The description repeats the three filter modes but adds no extra semantics beyond the schema, and does not mention limit. It provides some value but relies largely on 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 uses a specific verb 'Recall' and a clear resource 'memories', and specifies the search dimensions (text query, tags, or namespace). This distinguishes it from sibling tools like nexus_search (generic search) and nexus_memory_write (write operation).

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 use for recalling memories via text, tags, or namespace, providing clear context. However, it does not explicitly name alternatives or exclusions, such as when to use nexus_search instead.

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

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

The annotation idempotentHint=true already signals safety for retries. The description adds the behavioral trait 'Survives across sessions,' which provides durability context. However, it does not disclose whether writing to an existing key overwrites, appends, or errors, nor does it describe the return value. Given the annotations, this is acceptable but not rich.

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

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

The description is two sentences with no redundant wording. It front-loads the core action ('Store a persistent memory') and follows with a clarifying list of content types and a durability statement. 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 simple memory-write tool, the description is nearly complete: it states the purpose, content scope, and durability. The schema fully documents parameters, and the annotation covers idempotency. It does not mention overwrite/update behavior or return value, but these are minor gaps for a write operation with 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?

The input schema provides 100% coverage with descriptions for all four parameters (key, value, tags, namespace), so the baseline is 3. The description adds minimal parameter-relevant guidance by listing content types (knowledge, decision, gotcha, preference) that could inform the 'value' parameter, but it does not go beyond the schema's own semantics.

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

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

The description clearly states the tool's purpose with a specific verb ('Store') and resource ('a persistent memory'), and it enumerates the types of content ('knowledge, decision, gotcha, or preference'). This differentiates it from sibling tools like nexus_memory_search and nexus_memory_forget by emphasizing persistent storage across sessions.

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 ('Store a persistent memory') but does not explicitly contrast it with alternatives. It lacks exclusions or direction such as 'for retrieval, use nexus_memory_search' or 'for deletion, use nexus_memory_forget'. The use case is understandable but not fully contextualized among siblings.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe read operation. The description adds valuable behavioral context beyond annotations by mentioning 'Encoding-safe, binary-aware, injection-scanned,' which alerts the agent to how the tool handles file contents and security checks. No contradictions exist.

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

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

The description is exceptionally concise, using two short sentences. It front-loads the primary purpose and then adds three key behavioral traits in a compact tagline. Every word earns its place with zero 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 simple read tool with annotations covering safety, the description covers the core purpose and some behavioral traits. However, with four parameters, no output schema, and minimal schema coverage, it leaves important gaps: the semantics of start, end, and allowSensitive are not explained, nor is the return format. It is adequate but not fully complete.

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

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

Input schema description coverage is only 25% (only 'file' is described). The phrase 'line range' loosely implies start and end are line numbers, but the description does not explicitly explain the parameters or their defaults, and 'allowSensitive' is entirely unexplained. The description fails to compensate for the low 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 clearly states a specific operation: 'Read a line range of a file.' This distinctly identifies the tool's purpose and differentiates it from sibling tools like nexus_search or nexus_file_symbols, which focus on other actions.

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

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

The description provides no guidance on when to use this tool compared to alternatives. It does not mention any exclusions, prerequisites, or scenarios where other tools would be more appropriate. The sibling list is extensive, but the description offers no decision support.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful context about the scope (reference sites and their types) but does not disclose output format, performance characteristics, or any limits. This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that tells the agent exactly what the tool does without any filler. Every word contributes to understanding the tool's function.

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

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

For a simple read-only tool with one well-documented parameter and no output schema, the description is mostly complete. It clearly defines the inputs and the conceptual output (reference sites), though it could optionally clarify the return format (e.g., file paths and line numbers). Overall, it is sufficient for the tool's complexity.

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

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

The schema fully describes the single parameter 'symbol' with type string and explanation 'Symbol name or qualname', giving 100% coverage. The description does not add additional parameter semantics beyond that, so the baseline score of 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?

The description starts with the specific verb 'Find' and clearly identifies the resource: 'all reference sites of a symbol.' It also enumerates the kinds of references (calls, imports, type annotations), which distinguishes it from sibling tools like nexus_search or nexus_find_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 phrase 'all reference sites of a symbol' provides clear context for when to use this tool, and the explicit mention of calls, imports, and type annotations helps the agent decide it is the right tool for reference discovery. However, there are no explicit exclusions or alternative tools mentioned.

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 state readOnlyHint=true and the description says 'Preview,' but the schema includes an `apply` boolean (defaulting to false) that likely allows mutation. The description does not disclose that setting `apply=true` would execute the rename, nor does it clarify that the default is read-only. This is a significant gap because an agent could believe the tool is strictly read-only when it is not.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It delivers the core action, scope, and a key differentiator ('graph-scoped, not blind sed') efficiently. This is ideal conciseness.

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 4 parameters, no output schema, and only a read-only annotation, the description needs to provide more context. It gives a vague 'Returns the changes to make' without describing the output structure, omits the `apply` behavior, and does not mention potential prerequisites like requiring an index (given sibling tools like nexus_index_build). The tool is not fully specified for an agent to use safely.

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

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

Schema description coverage is 0%, so the description must compensate for parameter clarity. It only mentions 'symbol' and 'workspace-wide,' leaving `file`, `apply`, `oldName`, and `newName` unexplained. While `oldName` and `newName` are fairly obvious, the critical `apply` parameter is not described at all, and `file`'s role is ambiguous.

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

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

The description clearly states the verb 'Preview' and the resource 'workspace-wide rename of a symbol,' immediately conveying the tool's purpose. The phrase 'graph-scoped, not blind sed' further distinguishes it from naive text replacement and clarifies the method. This is a specific and unambiguous purpose statement.

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 using this tool for a safe, graph-aware rename preview and contrasts it with 'blind sed,' but it does not explicitly state when to use it versus alternatives or when to avoid it. It also fails to mention the `apply` flag, which could be used to actually perform the rename, leaving a key usage scenario undisclosed.

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 and idempotentHint, covering safety. The description adds the token budget constraint and the PageRank ordering behavior, which is useful. However, it does not disclose what happens when focusFiles is used, nor any prerequisites (e.g., whether an index must be built) that might affect invocation.

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 crisp sentences: a noun-phrase summary, a detail on what's shown, and a positioning statement. Every sentence earns its place, and key information is front-loaded. No redundancy or wordiness.

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 small parameter set, good annotations, and the absence of an output schema, the description covers the essential purpose and content. It explains the ranking and token budget, but omits potential prerequisite constraints and the precise effect of focusFiles. Still, it's nearly complete for the tool's complexity.

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

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

Schema coverage is 100% with clear parameter descriptions for maxTokens and focusFiles. The description reinforces the 'token budget' concept but does not add new meaning beyond the schema, such as how focusFiles affects prioritization or the exact format of the map.

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

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

The description clearly states that the tool produces a 'ranked repo map within a token budget' and shows 'top symbols per file, PageRank-ordered.' This is specific and conveys the resource and output nature. It doesn't explicitly contrast with sibling tools like nexus_workspace_overview or nexus_context_pack, so it misses full differentiation, but the distinctive ranking and per-file symbol emphasis set it apart.

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

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

The phrase 'Most important context feature' implies this should be the first tool used for repo context, but there is no explicit 'when to use vs. not use' guidance or mention of alternatives. Usage is implied rather than explicitly stated, so it's adequate but not 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?

Beyond the annotations (destructiveHint, idempotentHint), the description adds specific behavioral context by stating 'Overwrites current content', which explains what gets destroyed. It does not contradict annotations and provides useful operational detail.

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

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

The description is three short sentences, front-loaded with the core purpose, and includes a clear warning. Every word earns its place with no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential behavior and danger adequately. It could mention prerequisites like needing a valid snapshot ID, but the schema and warning suffice for basic use.

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

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

The input schema already describes the only parameter 'id' as 'Snapshot ID to restore', which aligns with the description. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate given 100% 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 ('Restore files from a snapshot') and clearly distinguishes it from sibling tools like nexus_snapshot, which creates snapshots. The added detail 'Overwrites current content' clarifies the action's scope.

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

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

The description provides clear context for when to use the tool (restoring from a snapshot) and warns about destructive behavior, but it does not explicitly mention alternatives or when not to use it. This is clear context without exclusions.

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

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

Annotations already declare this as read-only and idempotent, so the description adds the behavioral trait of being 'gitignore-aware' and the ability to search via literal, regex, or glob. However, it does not disclose output format, default limit behavior, or potential errors, making it minimally sufficient beyond the annotations.

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

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

The description is extremely concise: two short sentences that pack the key information—search modes and gitignore-aware behavior—with no filler or redundancy. Every word contributes meaning.

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?

While the description provides the essential purpose and search modes, it omits details about the return value (e.g., file paths, snippets, match counts) and how the limit parameter behaves. Given the simple nature of the tool and the existence of annotations, this is adequate but has clear gaps in expected output.

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

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

The schema already documents 'pattern' and 'glob', but the description introduces the concept of 'literal' search, which is not present in the schema, thereby enriching parameter understanding. The 'limit' parameter remains undocumented both in schema and description, slightly reducing the score.

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

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

The description opens with a specific verb ('Search') and resource ('files'), and clearly distinguishes the two search modes: content (regex/literal) and glob patterns. It also sets it apart from sibling tools like nexus_find_symbols or nexus_references by focusing on file content rather than code symbols or references.

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 explains what the tool does but provides no explicit guidance on when to use it versus alternatives. Sibling tools like nexus_find_symbols or nexus_memory_search exist for other search types, but the description does not mention them or provide exclusion criteria, leaving the agent without clear usage context.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety traits. The description adds a key behavioral detail: 'Findings are redacted', which is not evident from annotations or schema. No contradiction exists, and the extra information is valuable for setting expectations.

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

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

The description is a single, front-loaded sentence that immediately conveys purpose. It includes concrete examples and a critical behavior (redaction) without unnecessary verbosity. Every phrase 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 simple scanning tool, the description covers the core action and redaction behavior, and the schema documents paths. However, it omits output format or return value details, and lacks usage guidance. Given the absence of an output schema, some indication of what the tool returns would have improved completeness.

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

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

Schema coverage is only 50% (paths has a description, limit does not). The description does not mention parameters at all, leaving limit's semantics ambiguous. This does not compensate for the partial schema coverage, and the description adds no parameter-related value.

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

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

The description clearly states the tool's function with a specific verb ('Scan') and resource ('files'), and specifies the target ('secrets') with concrete examples (AWS, GitHub, OpenAI, JWT, private keys). This distinguishes it from sibling tools like nexus_search and nexus_read_span, which serve different purposes.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios where a different tool would be more appropriate. The description is purely functional without usage context.

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

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

Annotations already declare the tool as read-only and idempotent, so the safety profile is covered. The description adds behavioral context by listing the diagnostics returned (index age, backend, caps, state dirs, version), which helps set expectations. However, it does not describe the output format, potential errors, or any required permissions, so it is adequate but not rich.

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

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

The description is a single, concise sentence that front-loads the purpose ('Server self-diagnostics') and then lists the key elements. Every word earns its place; there is no repetition or filler.

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

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

Given the tool's simplicity (no parameters, no output schema, minimal annotation needs), the description is largely complete. It states what the tool reports. However, because there is no output schema, it does not specify the exact return structure (e.g., JSON key names), but the listed fields provide a reasonable expectation.

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 has zero parameters and the schema has 100% coverage (empty object). With no parameters to describe, the baseline is 4. The description does not need to add parameter semantics, and it does not contradict the schema.

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

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

The description clearly identifies the tool as 'Server self-diagnostics' and enumerates the specific data it provides: 'index age, backend, caps, state dirs, version.' This is specific enough to distinguish it from many sibling tools, though it lacks an explicit verb like 'get' or 'report.' It could be confused with nexus_diagnose, but the focus on server state versus general diagnostic makes it reasonably clear.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that it should be used for checking server health or that nexus_diagnose might be more appropriate for troubleshooting. There is no explicit when-to-use or what-not-to-use context.

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

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

The description states that the tool 'creates a restore point with full file contents', which implies a persistent side effect (writing snapshot data). However, the annotations declare readOnlyHint=true, indicating no state mutation, creating a direct contradiction between the description and the safety profile. This is a serious inconsistency that could lead an agent to wrongly assume the operation is side-effect-free.

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

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

The description is very concise: two sentences, no filler, with the main verb and purpose stated first. It front-loads the key action and provides a brief elaboration on what the snapshot contains, earning full marks.

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

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

The description is adequate for a simple checkpoint tool but fails to resolve the contradiction with annotations, and it omits details about idempotency behavior or how the restore point is stored. Since the readOnlyHint misleadingly suggests no side effects while the description creates one, the contextual picture is inconsistent and incomplete.

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 provides descriptions for both parameters (id and files), giving 100% coverage. The description does not add additional semantics beyond saying 'full file contents', which aligns with the schema's 'files' description. Thus the description adds minimal value beyond the schema, meriting the baseline 3.

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

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

The description uses specific verbs ('Checkpoint', 'Creates a restore point') and a clear resource ('files'), and it distinguishes the tool from siblings like nexus_restore by explicitly stating it snapshots file contents. The phrase 'before editing' clarifies its role as a pre-edit safety measure, making the purpose unambiguous.

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

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

The description provides an explicit usage context ('before editing') that tells the agent when to invoke this tool, differentiating it from restoration workflows. It does not enumerate exclusions or alternative tools, but the timing guidance is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint and idempotentHint, establishing the safety profile. The description adds the set of statuses included in the DAG, but does not disclose return format, pagination, or other behavioral details, so the added value is moderate.

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?

Single compact sentence with no wasted words. Clearly states the action and scope, making every word earn 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?

Given the tool's simplicity (no params, read-only, no output schema), the description covers the core purpose and status categories. However, it omits details about the response structure (e.g., whether it's a nested graph or flat list), which would help an agent parse the 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?

Tool has zero parameters, so schema coverage is complete and parameter semantics are not needed. Baseline 4 applies because the description offers no parameter information but none is necessary.

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

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

Description uses specific verb 'View' and names resource 'task DAG', enumerating statuses (ready, blocked, in_progress, completed, failed). This clearly distinguishes it from sibling tools like nexus_task_submit or nexus_task_update.

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

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

No explicit when-to-use or alternatives are provided. The description only states what it does; usage context is implied by the read-only task DAG focus but does not mention exclusions or 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 provide idempotentHint=true, and the description adds behavioral details about cycle validation and persistence across restarts, which go beyond the structured metadata. However, it does not disclose failure behavior or return values.

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

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

The description is two concise sentences, front-loaded with the core action, and contains no redundant wording.

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 one-parameter tool with no output schema, the description covers key behaviors but omits response/return value details and parameter structure semantics, making it adequate but incomplete.

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

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

Schema description coverage is 0%; the description does not explain the structure of the 'nodes' array or how fields like dependsOn define the DAG. The term 'task DAG' minimally implies nodes are graph nodes, but explicit semantics are absent.

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

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

The description explicitly states 'Submit a task DAG', using a specific verb and resource, and adds validation and persistence details that distinguish it from sibling task tools like nexus_task_update and nexus_task_status.

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

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

The description implies usage for submitting task DAGs but offers no explicit guidance on when to use it versus alternatives like nexus_task_update or nexus_task_status. No exclusions or alternate tool references are provided.

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

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

With no annotations, the description carries the full burden. It discloses the key side effect of unblocking dependents, but does not mention permissions, reversibility, or what happens to the task itself beyond status change. It adds some behavioral context beyond 'update' but lacks depth.

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

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

The description is two short sentences that are front-loaded with the action and key information. Every word earns its place, and there is no repetition of schema information.

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

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

Despite being a simple mutation, the tool has side effects (unblocking dependents) and optional parameters (error/result) that are not explained. With no annotations or output schema, the agent cannot fully predict the tool's behavior or know when to include error/result, leaving significant gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains the status parameter values (completed/failed/in_progress), leaving id, error, and result unexplained. This is insufficient for an agent to correctly use optional 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 the tool's action: updating task status with explicit allowed values (completed/failed/in_progress). It also mentions the side effect of unblocking dependents, which distinguishes it from siblings like nexus_task_submit and nexus_task_status.

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

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

The description implies when to use this tool (when a task's status changes and dependents need unblocking), but it does not explicitly exclude alternatives or name sibling tools. There's no 'use this instead of X' guidance, so usage context is implied rather than clearly defined.

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 only include openWorldHint, which is generic. The description adds framework detection and structured return values, but does not disclose potential side effects of running tests or prerequisites. 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?

One sentence efficiently states purpose and return value. No unnecessary words 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?

The description explains the main purpose and return structure, but since there is no output schema, the structured format remains vague. It also does not elaborate on scope or timeout semantics, making it adequate but not comprehensive.

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 50%, with timeoutMs lacking a description. The tool description does not mention parameters or how to use them, failing to compensate for the low coverage.

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

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

The description clearly states the tool's function: detect test framework and run tests. It lists specific frameworks and mentions the structured return type, making it distinct from sibling tools like nexus_exec.

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

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

The description implies the tool is for running tests but does not explicitly contrast it with alternatives like nexus_exec. There's no clear when-to-use or when-not-to-use guidance, though the purpose is evident.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a useful list of content areas (languages, LOC, git state, index health, entry points), but does not disclose any limitations, return format details, or performance characteristics beyond what the annotations imply.

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

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

The description is a single, front-loaded sentence with a colon followed by a concise list of content items. Every word earns its place, with no redundancy or filler.

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

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

For a simple, parameterless, read-only overview tool, the description provides sufficient context by enumerating the included information categories. There is no output schema, but the list of attributes serves as a reasonable substitute. It lacks explicit notes about return format or potential edge cases, but these are not critical for an overview tool.

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

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

The tool has no parameters (empty properties in schema, 0% required). The baseline for zero-parameter tools is 4, and the description does not need to explain parameter semantics. The 'at a glance' phrasing suggests no inputs are required, which is consistent.

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 'Project at a glance: languages, LOC, git state, index health, entry points' clearly states a specific purpose: providing an overview of key project metrics. It identifies the resource (project) and the types of information included, but does not explicitly differentiate from sibling tools like nexus_repo_map or nexus_git_diff.

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 offers no guidance on when to use this tool versus alternatives. It does not mention scenarios, exclusions, or alternative tools. Users are left to infer when a high-level overview is needed.

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