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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world scope, so the safety profile is fully covered structurally. The description adds the useful framing that artifacts are reusable outputs of prior tools, but says nothing about behavior such as an unknown/expired artifact ID or whether reads are cached.

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?

A single well-formed sentence with the load action front-loaded and the motivation trailing. No filler, no redundancy with structured fields.

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 two-parameter read tool with full schema coverage, complete annotations, and no output schema requirement, this description covers what the tool is and why an agent would call it. Only edge-case behavior (missing artifact) is unaddressed, which 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 both parameters are already documented, including which tools return valid artifact IDs and the root scoping rule for subagents. The description's 'by ID' adds nothing beyond the schema, so the baseline 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?

States a specific verb ('Load') and resource ('previously generated context artifact by ID') and enumerates what an artifact can be (task packets, repo maps, decisions). It's clearly a retrieval tool, though it never names or distinguishes itself from siblings like memory_record_task or task_pack.

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 clause 'so agents can reuse earlier task packets... without regenerating them' implies the when-to-use case (reuse vs. regenerate), but there is no explicit when-not, no prerequisite call ordering, and no named alternative. Usage is inferable rather than specified.

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

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

Beyond the read-only and non-destructive annotations, it discloses the important behavioral limitation that results are textual candidates and can include unrelated same-name symbols. It also explains the count-by-kind behavior, though it does not mention possible result limits, truncation, or search-scope exclusions.

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

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

Three compact sentences front-load the purpose, then provide a practical filtering tip and an important limitation with an alternative. Every sentence contributes actionable information without repetition or unnecessary background.

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?

Together with the fully documented schema and safety annotations, the description supplies what an agent needs to select and invoke this read-only search correctly. It covers the matching model, aggregate counts, a key filtering use case, and the appropriate sibling for precision-sensitive rename analysis.

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 already adequate, but the description adds useful semantics for kind:call by specifying call-containing lines. The same-name warning also clarifies that symbol_name is matched textually rather than resolved to a particular binding.

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: it finds textual usage candidates for a symbol and provides counts by usage kind. It also distinguishes the tool from exact_references by identifying its textual, same-name matching rather than binding-resolved 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?

It explicitly directs agents to use kind:call when they need call-containing lines. It also gives a clear alternative and condition: use exact_references for binding-resolved TS/JS rename checks.

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=false and destructiveHint=false, and the description adds a genuinely useful constraint beyond them: the fallback execution path only runs read/index tools and excludes source edits, which explains why the tool is non-read-only yet non-destructive. It does not state that enabling mutates the session catalog or whether that change persists, leaving the main mutation under-explained.

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 purpose is front-loaded in the first sentence, but the second sentence is telegraphic and awkwardly compressed ('call runs a supported read/index tool; never source edits'), which forces the reader to reparse it. No sentence is purely filler, but the phrasing costs clarity.

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 five parameters including a nested free-form `call` object and no output schema, the description covers the discovery contract but not the interaction between query, limit, and enable, nor what the returned schemas look like or how they should be applied. Annotations exist, so the safety gap is partially covered, but the execution fallback deserves more explanation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the read/index-only restriction on `call` and the schema-return notion; it contributes nothing on `query`, `limit`, or `enable` beyond what the schema already says.

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

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

The description names a specific verb set and resource — 'Discover or enable experts and return their schemas' — so an agent knows this tool both lists and activates tools and returns schema payloads. It does not, however, differentiate itself from siblings like status, search, skeleton, or explain, and the term 'experts' is never grounded in the sibling catalog.

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?

One conditional is spelled out: if the client cannot refresh its catalog, use the `call` parameter to invoke a supported read/index tool. That is real when-to-use guidance for one path, but there is no guidance on when to discover versus enable, how to choose `query` values, or when to prefer a sibling tool over this one.

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 a read-only, idempotent, closed-world, non-destructive operation, so the safety bar is met. The description still adds real value beyond them: it discloses what the history does and does not retain (numeric metrics only, never prompts, code, response bodies, or file paths) and warns that savings are estimates rather than billing data — a caveat that directly affects how results should be reported.

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 short sentences, front-loaded with purpose and followed by the two caveats that matter most. Slightly dense phrasing ('persistent, auditable context-compression estimates') but nothing is 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 six optional parameters and no output schema, the definition needs to describe what the report actually contains, but it never says what fields or sections a caller will get back (totals, per-tool events, cost figures). Privacy and estimate caveats are well covered, yet an agent still can't predict the response shape before calling.

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% across all six optional parameters, so the schema already carries per-parameter meaning, including the cost and hypothetical-pricing inputs. The description adds no parameter-level detail (nothing on root, scope windows, format, or history_limit), so the baseline 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 states a specific verb and resource: report context-compression / token-savings estimates, broken down by tool, from a persistent history. That is clear enough to act on, but it never distinguishes this from look-alike siblings such as status, explain, or task_pack, which also surface session/project information.

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 when-to-use or when-not-to-use guidance appears in the description, and no alternative is named. The only timing instruction ('call at task completion and quote finalSummary') lives inside the scope parameter schema, so the description itself leaves invocation context to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: language-dependent precision (compiler bindings for TS/JS, heuristic for Python), staleness of imported SCIP data, that results label calls vs imports, and that truncation happens after per-file totals. It does not discuss permissions, project-size limits, or failure modes when no definition is found.

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 in the first sentence, followed by precision and caveat notes in a compact, dense style. Sentences are telegraphic ('Check scope, ambiguity and warnings') but every one carries information; nothing is redundant.

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

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

For a six-parameter, read-only analysis tool with no output schema, the description covers precision characteristics, result labelling, truncation behavior, and a data-freshness caveat, which is what an agent needs to trust and interpret the output. It lacks explicit routing guidance against the sibling reference/blast-radius tools, which is the main remaining gap.

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?

With 83% schema coverage the baseline is 3, and the description adds meaning on top: 'per-file call totals before limits' clarifies how the limit parameter is applied to results, and 'warnings' on ambiguity links to the line-inference behavior documented in the schema. It does not explain the root-requirement or format trade-offs, which remain schema-only.

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

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

States a specific verb and resource: 'Find who calls or references a symbol.' That is unambiguous and an agent can distinguish it from grep/search-style siblings by the call-reference framing. It stops short of naming a contrasting sibling (e.g. blast_radius or grep), so it does not earn a 5.

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

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

'Check scope, ambiguity and warnings' plus the note that TS/JS bindings exclude same-named unrelated symbols tells the agent when this tool is the right, precise choice over text search. There are no explicit exclusions ('do not use for X, use Y instead'), so it lands at 4 rather than 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavioral context. It does so by framing the tool as a token-efficient partial read ('without reading the entire file') and by describing what the result contains (body plus called functions, or a structural overview), which goes beyond the annotations.

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

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

Three short sentences, front-loaded with the core capability and the efficiency rationale, with no filler. The parallel 'Provide X to get Y' phrasing is easy to scan, though the repeated structure costs a few words.

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 seven parameters and no output schema, the description should carry more weight. It explains the two primary modes and roughly what comes back, but omits the batch symbols path (explicitly encouraged by the schema to avoid repeated reads) and the root requirement, leaving meaningful gaps for a multi-parameter 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 description coverage is 100%, so every parameter is already documented, and the description mostly restates the schema's symbol/file mode split. It adds a little meaning by clarifying that the symbol mode returns 'code + called functions', but says nothing about depth, format, max_tokens, or the batch symbols parameter.

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: 'Extract a specific function/class body with its dependencies.' The phrase 'without reading the entire file' implicitly distinguishes it from a full file read (artifact_read) and hints at a structural alternative (skeleton), but no sibling is named explicitly.

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

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

Gives clear mode-selection guidance for two parameters: symbol for code plus called functions, file for a structural overview. It never says when to prefer this over siblings like skeleton, exact_references, or search, and it omits the batch (symbols) path entirely, leaving the agent to infer it from the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavior beyond that: binary files are skipped and .gitignore is respected via the indexed walker, which tells the agent what results it will not see. It stops short of describing result ordering, truncation behavior, or output shape, which keeps it below 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?

Three sentences, front-loaded with the core capability and closed with the key behavioral caveats (binary skip, gitignore). The middle sentence's list of example use cases is slightly padded but still earns its place as routing guidance.

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

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

For an 11-parameter read tool with full schema coverage and no output schema, the description covers purpose, routing, and search-scope caveats adequately. The only gap is return-format expectations, but the context_lines parameter description already explains the L<line> marker convention, so the burden is largely met elsewhere.

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 all 11 parameters are individually documented in the schema, so the baseline is 3. The description only echoes the pattern/regex duality and adds no syntax, format, or default guidance beyond what the schema already states.

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

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

The description opens with a specific verb and resource ("Fast literal or regex string search across the project's indexed file set") and immediately scopes it to indexed files, which distinguishes it from a filesystem-wide grep. It also names the sibling tool it is not ("Use 'search' instead for semantic intent queries"), so an agent can route between them without opening either schema.

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

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

It gives concrete when-to-use cases (log-message lookups, config-key searches, error-message tracing, known exact characters) and an explicit when-not-to-use with the named alternative, 'search', for semantic intent queries. That is the full routing rule, not an implication.

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 write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description only adds the cross-session persistence intent. It does not disclose that repeated calls are non-idempotent and can create duplicate memories, nor does it explain the effect of supersedes on history, which is a meaningful behavioral gap for a write tool.

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

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

A single well-formed sentence with the verb and core payload front-loaded and zero filler. The enumeration of field names mildly duplicates what the schema already lists, which keeps it just short of ideal.

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

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

For an 11-parameter mutation tool, the description is thin: it omits duplicate-creation behavior, the meaning of supersedes for history, and any notion of the returned result (no output schema exists). The fully documented schema and safety annotations compensate for much of this, but an agent still learns little about consequences from the description alone.

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 every parameter individually described including root's subagent requirement and source_evidence's hash rechecking, so the schema carries the semantic load. The description's field enumeration maps onto schema property names without adding syntax, format, or prioritization guidance, making the baseline 3 correct.

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 ("persist") and resource ("task outcomes") and enumerates the payload categories it stores (files, assumptions, evidence, open risks). It is clearly distinguishable from read-oriented siblings like artifact_read, search, or grep, though it never explicitly names an alternative to contrast against.

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?

"For future sessions" implies the trigger point — recording outcomes so later sessions can recall them — but there is no explicit when-to-use/when-not or any routing to siblings such as task_pack (which likely produces the task context this tool records). Usage is inferable rather than stated.

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 the safety profile (non-read-only, non-destructive, non-open-world), so the description's job is to add behavior, and it does: content-hash change detection means partial work, embeddings are populated eagerly by default, and the import graph is rebuilt as a side effect other tools depend on. It does not estimate cost/duration or say whether concurrent edits during a run are safe.

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 front-loaded sentences with the core action first, then caching behavior, then embedding side effects, then the downstream artifact. Every sentence carries information, though the embedding sentence is dense enough to require a second read.

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 five-parameter mutation tool with no required inputs and no output schema, the description covers trigger conditions, incremental semantics, expensive side effects, and downstream consumers. A reader still lacks a sense of runtime cost or what the tool returns, but the essentials for correct invocation are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the field docs by framing no_embed as a default-on embedding pass and by tying the env var override to that default. It says nothing extra about root, force, auto_hubs, or target_path, which is acceptable given full 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?

"Re-walk, re-parse, and re-index project files into the database" gives a specific verb triad plus the resource and destination. It also names distinct sub-behaviors (import graph build, embedding population) so an agent can tell this apart from read-only siblings like search, grep, or skeleton.

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 after git pull, branch switch, or external edits" states concrete triggering conditions rather than leaving timing to inference. There is no explicit when-not or named alternative, but no sibling tool overlaps enough to need one.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds real behavioral context by disclosing the underlying mechanism (embeddings plus keyword overlap scoring) and the default mode's combine-both behavior. It stops short of discussing cost, latency, or result size limits for a 19-parameter search, which keeps it off 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?

Four sentences, front-loaded with purpose and modes, followed by mechanism and the alternative-tool caveat — every sentence adds something. There is minor redundancy in re-explaining the mode enum that the schema already enumerates, but 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?

For a 19-parameter tool with no output schema, the description covers the conceptual model (modes, scoring, defaults) that an agent needs to pick sensible arguments, and the schema handles the rest. The one gap is that with no output schema, the description never indicates what a result record contains or how mode affects the returned shape beyond 'call chains'.

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

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

Schema description coverage is 100%, so the schema already documents all 19 parameters including mode, format, fusion, preset and the weight knobs. The description adds only marginal semantic meaning beyond that, mainly restating mode behavior and clarifying that identifier mode carries call chains; it does not explain how the score filters or weight parameters interact in practice.

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

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

The description opens with a specific verb and resource ('Search the codebase by MEANING') and immediately qualifies it with the three modes and their distinct targets (file headers/symbols vs. function/class definitions with call chains). It also draws an explicit boundary against LSP-based go-to-definition, so an agent can separate this tool from exact_references or grep without opening the schema.

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

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

It states both when to use this tool ('meaning-based / fuzzy discovery across the whole repo') and when not to ('for an exact known symbol name ... prefer that for go-to-definition'), naming the alternative class of tool and the condition that selects it. The guidance is conditional and actionable rather than a generic 'use this to search'.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context by warning that signatures are normalized summaries and not exact edit anchors, and that line ranges are returned. It does not state language coverage beyond the schema's TS/JS hint on exported_only, or how unparseable files are handled.

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

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

Three tight sentences, front-loaded with the capability and capped by the editing caveat. Every sentence carries information the agent needs; there is 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 does the work of describing the return shape (signatures, methods, type definitions, API surface, line ranges) and flags the key caveat about edit anchors. Minor gaps remain around supported languages and behavior on non-code or partially parseable files.

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 root, file_path, and exported_only are already fully documented in structured data. The description reinforces 'of a specific file' but adds no filtering or path-resolution semantics beyond the schema, so the baseline 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?

States a specific verb (Get) and a specific resource (function signatures, class methods, type definitions of a file), and explicitly contrasts the scope with reading the full body. An agent can immediately tell this is an API-surface/outline tool rather than a content reader like search or grep.

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 a positive use case (inspect API surface without reading the body) and an explicit exclusion plus the alternative: use context(targets:[{file,start,end}]) for source text before editing. The alternative is named with concrete call syntax, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing the aggregate read-only payload it assembles across several subsystems, which explains the cost profile of a single call. It says nothing about error handling or behavior on a bad root, which keeps it at 4.

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 short sentences, front-loaded with the identity of the tool and followed by the payload contents and then the usage cue. Every sentence earns its place and nothing is repeated from annotations or schema.

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

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

With no output schema, the description carries the burden of explaining return values and does so by enumerating the six data groups. Combined with fully-described parameters and annotations covering side effects, an agent has enough to call it correctly; only error/edge-case behavior is 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 description coverage is 100% and the two parameters (root, format) are fully documented in the schema, including the important caveat about omitting root only at session start. The description adds no parameter-level meaning, 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 names a specific resource (project overview dashboard) and enumerates exactly what it returns: file counts, index state, memory graph stats, git branch, uncommitted changes, recent commits. That content list makes it clearly distinguishable from siblings like efficiency_report, reindex, or search 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?

"One call for complete situational awareness at the start of a session" gives a concrete usage context and implies it is a cheap first step rather than a targeted query. It does not name an alternative tool or state when not to use it, so it falls short of a full routing instruction.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered structurally. The description adds value by disclosing the packet composition (files, tests, diffs, memory, risks), which stands in for the absent output schema. It says nothing about cost, provider dependency, or delta semantics from previous_context_id.

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?

A single front-loaded sentence with no filler; the resource and its contents come first and every clause adds information. Nothing is redundant with the schema or the 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?

For a 13-parameter aggregator with no output schema, the description names the return contents, which is the most important missing piece. Remaining gaps are usage routing (this vs. search/grep) and the root/delta calling conventions, both of which the schema documents on its own.

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

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

Schema coverage is 100%, and every parameter carries a substantive inline description including defaults, ranges, and the token-estimation caveat, so the schema does the heavy lifting. The description contributes no additional parameter meaning, which is the expected baseline here.

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?

Uses a specific verb ("assemble") plus a defined artifact ("minimum useful working set for a task") and enumerates its contents: ranked files, nearby tests, recent diffs, memory, risks. An agent can picture the output. It stops short of naming sibling tools it supersedes (search, grep, exact_references, skeleton), so differentiation relies on inference.

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 "for a task" implies context-gathering at task start, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many retrieval siblings. An agent must guess whether to call task_pack or fall back to search/grep.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description usefully adds that the tool recommends rather than executes checks, and that explicit files override inference, but says nothing about scope of inspection, cost, or how many checks are returned.

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, zero filler, with the sequencing trigger front-loaded ahead of the parameter hint. Nothing could be removed without losing information.

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

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

Covers what the tool returns (validation checks and commands) and the one non-obvious calling rule, and the remaining parameters are fully documented in schema. With no output schema, a brief return-value statement would help, but this is a minor gap rather than a missing one.

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 every parameter including root, format and max_files is already documented, establishing a baseline of 3. The description's files-precedence note merely restates the schema text for that property and adds no syntax or format detail beyond it.

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

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

States a specific verb and output ("recommend the most relevant validation checks and commands") plus a sequencing cue ("After edit_scope"). The agent knows this produces validation guidance rather than performing edits, but no sibling in the provided list is named as an alternative, so differentiation relies on inference.

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 a clear invocation point ("After edit_scope") and a decision rule for the optional files parameter ("Pass files when you already know what changed; they take precedence over task inference"). No when-not-to-use guidance or explicit alternative tool is offered.

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