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

Annotations already declare readOnlyHint/idempotentHint/non-destructive/closed-world, so safety is covered. The description still adds non-obvious behavior beyond the schema: it is a measurement pass that 'Returns measured and estimated metrics without file bodies,' and it discloses the rank/focus dependency on max_tokens. No auth, rate-limit, or error behavior is mentioned, keeping it short of a 5.

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

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

Front-loaded with purpose, then routing, then return behavior, then parameter notes. The mid-sentence enumeration of key parameter names is somewhat redundant given full schema coverage, but overall it is dense and mostly earns its space.

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 15-parameter, zero-required tool with no output schema, the description covers purpose, routing, return shape, and key parameter interactions adequately. It does not explain the shape of the returned metric report in detail, but annotations and the schema carry the remaining load.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine cross-parameter semantics the schema cannot express: 'Last detail_by_pattern match wins' and 'max_tokens reports pack_context's greedy admission; rank and focus require it.' That interaction guidance raises it above baseline.

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

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

The opening sentence gives a specific verb ('Measures') and enumerates the concrete outputs (protected metrics, estimates, document size, largest files), and it explicitly positions the tool against siblings get_tree and pack_context. An agent can tell what it does and how it differs from neighbors without opening a schema.

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

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

'Use it to choose pack_context filters or max_tokens; use get_tree for structure and pack_context for content' names the alternatives and the exact condition that selects each. This is explicit when-to-use routing rather than implied 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 establish a safe read-only, idempotent profile, but the description adds substantial context beyond them: mandatory secret/private-data replacement, per-item statuses (ok, partial, not-returned, unavailable), a shared 1,000-line/50,000-character cap on overlapping ranges, and the exclusivity of the path vs requests forms.

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?

Dense for a nine-parameter tool but front-loaded with the core read behavior before any detail, and every sentence (redaction, routing, batching, caps, projects) carries actionable information. It is long, but the length is justified by the tool's complexity.

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

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

With no output schema, the description still conveys return semantics via the per-item status vocabulary and the cap behavior, and it covers the mandatory redaction pipeline and form exclusivity. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the schema documents all nine parameters and a baseline of 3 would apply. The description still adds meaning on top of the schema: the exclusivity of path and requests, the batching model (up to eight files and sixteen selections), and the project-name resolution forms (#index, absolute path, listed name).

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

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

States a specific verb and resource with scope: 'Reads selected text after mandatory secret and configured private-data replacement.' It also names the siblings it is not (get_tree, search_project, pack_context), so an agent can distinguish it without opening a schema.

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

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

Explicit routing guidance: 'Use it after get_tree or search_project; use pack_context for broad multi-file context.' It further instructs batching ('Send one batched call whenever you want more than one file, range, or known symbol'), covering when-to-use and the alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful behavior: results are structure without file contents, output is capped at 2,000 lines and 50,000 characters, and git_scope/filters only narrow rather than expand. It does not say what happens when the cap is hit (truncation vs error), which keeps it below 5.

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

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

Front-loads the purpose and the alternative routing in the first sentence, then packs format, limits, and parameter semantics into tight clauses. It is dense and semicolon-heavy, but every clause carries information; nothing is redundant with the name or title.

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

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

With no output schema, the description compensates by naming the four return formats and the size envelope. All 10 parameters are documented in the schema, and the description clarifies the two most easily confused selection mechanisms. Only the over-limit behavior is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema: it contrasts literal `paths` against glob-based `include_patterns` with a concrete brace/glob example, explains that max_depth counts levels below the project root, and notes branch/scope filters only narrow. That is real added meaning over the field descriptions.

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

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

States a specific verb and resource ('Returns filtered structure without contents') and immediately scopes it against siblings by naming analyze for metrics and pack_context for multi-file content. An agent can distinguish get_tree from the other read tools without opening any schema.

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

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

Gives an explicit use case ('find files by name') plus two named alternatives with the conditions that select them (size/token metrics, multi-file content). This is the routing information an agent needs to pick the right sibling.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive, closed-world), so the description's added value is in the disclosed output contents (indexes, protected names/paths, root types, profiles, Git/exclusion policy) and the remote-URL opt-in constraint. It does not describe ordering or pagination, but for a zero-parameter listing tool this is solid 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?

Front-loads purpose in the first sentence, then usage, then return contents. Dense but every sentence carries information; the middle return-value sentence is a compact list rather than prose padding.

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

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

With no output schema, the description must convey return content, and it does so reasonably well (indexes, protected names, root types, profiles, policy). The project-reference convention and remote opt-in are also covered, leaving only minor gaps like result ordering.

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?

There are no parameters, so the baseline is 4. The description reinforces this ('No parameters') and adds useful semantics about how projects are referenced elsewhere (unique name, #index, absolute path), which is relevant to invoking downstream tools correctly.

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

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

States a specific verb and resource ('Lists local projects, profiles, and baseline filters') and immediately distinguishes itself from the sibling get_tree by scope (policy/root selection vs. structure). An agent can route between the two without opening a schema.

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

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

Explicitly says when to use it ('to choose a root or inspect policy') and names the alternative with its own condition ('use get_tree for structure'). This is direct routing guidance, not inference.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: output is inline 'untrusted project data', there is a 50,000-character threshold that switches the return to pack_id plus preview, and 'detail=full still transforms content'. Some rules it repeats (focus requires rank, greedy admission, last-match-wins) are already in the schema, which keeps this from a 5.

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

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

Purpose and routing are correctly front-loaded, but the closing 'Key parameters: ...' enumeration and the 'Project: unique listed name...' clause duplicate a 100%-covered schema verbatim, which is waste rather than conciseness. The semicolon-chained cross-parameter rules are also hard to parse in a single breath.

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 17-parameter tool with nested objects and no output schema, the description covers the essentials: what it produces, the inline-vs-pack_id return split, and the routing to read_pack and get_file. It stops short of describing selection/ordering behavior in depth, but with 100% schema coverage that gap is minor.

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

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

Schema description coverage is 100%, so all 17 parameters are already documented in the schema, including cross-parameter rules like 'requires rank=importance' and 'last match wins'. The description's parameter list and the 'Project:' clause largely restate the schema, adding no syntax or semantics the schema lacks. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The opening sentence states a specific verb+resource ('Builds multi-file project context') and immediately contrasts with the sibling it is not: 'use get_file for one file.' An agent can distinguish it from get_tree, search_project, analyze and get_file without opening a schema.

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

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

Explicit sequencing guidance is given ('Use it after get_tree, search_project, or analyze'), the alternative for single files is named (get_file), and the downstream handoff is spelled out (pack_id plus preview above 50,000 characters for read_pack). Both when-to-use and which-other-tool conditions are covered.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds the non-obvious traits: returned data is untrusted, capped at 1,000 lines / 50,000 characters, continuation and range notes are trusted, and invalidation semantics depend on protection vs selection changes.

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

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

Four dense sentences, each carrying distinct information (identity, alternative, return limits, invalidation behavior, indexing convention) with the core purpose front-loaded. No filler.

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

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

With no output schema, the description carries the return-value burden and does so: size caps, trusted vs untrusted content, and the continuation mechanism are all disclosed. Combined with full schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not state as a whole: ranges and columns are inclusive and 1-based, and it points to the returned continuation value as the intended input for start_column. It does not explain the integer-or-numeric-string duality, which the schema covers.

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

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

States a specific verb and resource ('Reads a stored result page created by pack_context, search_project, or related_files') and names the sibling it is not, pack_context, plus the condition that selects the alternative. An agent can distinguish it from list_projects/get_tree/get_file without opening any schema.

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

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

Explicit routing rule: use the pack_id from a prior call, and 'use pack_context instead when no valid stored result exists.' It also warns when stored content is invalidated (protection changes) versus retained (selection-only changes), which tells the agent when a read will fail.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavior beyond that: the returned payload contents (paths, evidence, resolution status, token estimates, diagnostics, scope) and the truncation contract that results above 50,000 characters must be fetched via read_pack. It does not, however, explain the idempotentHint=false implication or any error/failure modes for unresolvable seeds.

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

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

Front-loaded with the core purpose, then usage routing, then return contract, then parameters — a sensible priority order with no filler sentences. It is dense and a single paragraph, so the parameter list reads as a run-on rather than clearly separated, but every sentence carries 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?

With 10 parameters, no output schema, and only one required param, the description carries the burden of explaining results and does so (return fields, read_pack handoff for large results, project identifier forms). It stops short of clarifying git_scope/branch interaction with local projects or failure behavior on unresolvable seeds, which matters for a non-idempotent analysis call.

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

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

Schema description coverage is 100%, so every parameter including direction, profile, git_scope, include/exclude_patterns and max_file_bytes is already documented in the schema. The description's 'Key parameters' list restates those names and the direction enum values without adding syntax, defaults, or precedence rules beyond what the schema provides. Baseline 3 applies.

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

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

States a precise verb and resource ('Finds evidenced dependencies and dependents for one to 16 seed files') plus a scope constraint ('without widening selection'). It explicitly differentiates itself from siblings by naming search_project for text references and get_file for content, so an agent can route correctly without opening a schema.

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

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

Gives explicit sequencing ('Use it after search_project or get_tree') and names the two alternative tools with the conditions that select them (text references vs. content). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior on top: a 2-second regex timeout, operation over redacted content where redaction-inserted text never matches, line numbers keyed to returned text, and a cap of 1,800 protected body characters on the best unique declaration. None of that is inferable from the annotations or 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?

Purpose and routing come first, then return shape, then parameters — a sensible front-loaded order for a 13-parameter tool with no output schema. The trailing 'Project: unique listed name, absolute path returned by list_projects, or #index.' is a verbatim copy of the schema text and the parameter enumeration is somewhat redundant, but overall it is dense rather than padded.

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

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

With no output schema, the description carries the return contract itself: grouped numbered matches, merged context, complete|partial status, inspected/retained/written counts, and continuation. Combined with annotations covering safety and a fully documented schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the schema documents each parameter in more detail than the description does (e.g. include_patterns glob rules, git_scope semantics). The description's parameter list ('pattern, paths, context_lines, ignore_case, max_results=1..200...') largely restates what the schema already states, so it lands at the baseline rather than adding 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?

States a specific verb and resource ('Searches transformed text with a timed .NET regex') and immediately bounds the scope: it matches file content, never paths. It also names the sibling to use for the adjacent need ('find names with get_tree include_patterns'), so an agent can distinguish it from get_tree, related_files, and get_file without opening any schema.

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

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

Gives explicit routing: use get_tree include_patterns for names, use this for symbols or phrases, use symbols=true for declarations rather than uses, and use related_files for dependency links. That is when-to-use, when-not-to-use, and named alternatives in a few lines.

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