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

The annotations already declare a safe read-only, closed-world operation. The description adds substantial behavior beyond annotations: hidden superseded/deprecated cards, `⚠ stale` prefixes for cards older than 90 days, an init hint on empty architecture memory, independent per-kind budgets, and project-based rank boosting.

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

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

The description is front-loaded with the core purpose and return shape, then uses compact bullets and short paragraphs for behavior, staleness, limits, project ranking, and the sibling alternative. Despite its length, each sentence conveys operative guidance for invoking or interpreting the tool.

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

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

For a complex retrieval tool with five parameters, nested `limits`, no output schema, and read-only annotations, the description covers return kinds, staleness handling, empty-layer behavior, per-kind limits, project ranking, and when to prefer `arch_list`. Nothing essential for correct invocation appears 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 already documents all parameters thoroughly. The description still adds meaning beyond the schema for `limits` and `project`, including the default/max behavior, the ability to suppress a kind with 0, and the project-scoped rank boost; it does not add much for `group` or `min_score`, but those are fully covered in 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 states a specific verb and resource: retrieve architectural memory relevant to a question or touched files. It enumerates the three returned card kinds and explicitly distinguishes this tool from `arch_list` when ground-truth enumeration is needed, so an agent can identify its role without opening the schema.

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

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

It gives an explicit trigger - call this BEFORE any non-trivial change - and names `arch_list` as the alternative when ranking issues are suspected. It also explains when stale cards require verification, which is actionable usage guidance rather than merely 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 declare destructive and idempotent behavior, but the description adds critical context beyond them: no undo, no audit trail, cards are removed from Qdrant, stale ids can silently miss or wipe now-current cards after re-upserts, and missing ids are reported in `notFound` without failing. This is exactly the kind of behavioral detail an agent needs for a destructive operation.

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

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

The description is front-loaded with the core action and the most important warning (no undo, no audit trail). The remaining sentences each add distinct operational value: use cases, idempotency behavior, stale-id risk, and the preferred alternative.

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 destructive tool with no output schema, the description covers safety profile, return behavior via `notFound`, id lifecycle risks, required pre-call workflow, and the alternative tool. Nothing material is missing for an agent 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 coverage is 100%, so the baseline is 3. The description still adds meaningful id semantics beyond the schema: stale ids may point to re-upserted cards with fresh UUIDs and should be refreshed via `arch_context`, and deletion by a reassigned id could wipe a current card. The `group` parameter is left to the schema, which fully documents 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?

The description opens with a precise verb and resource: hard-delete one or more arch cards by id. It clearly distinguishes the operation from related sibling tools by naming `arch_context` for re-fetching ids and `arch_record_decision` for replacement-based workflows.

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 explicit use cases (obsolete cards, removed features, payload migrations) and an explicit when-not/alternative: prefer `supersedes` on `arch_record_decision` when a replacement exists. It also mandates re-fetching ids via `arch_context` immediately before calling, which is a concrete operational guideline.

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 a read-only, closed-world operation, but the description adds important behavioral context: there is no vector search or ranking, `project` filtering is hard for components and soft for decisions/lessons, and history is excluded by default. It also describes pagination and returned fields. Minor gaps like error behavior are not material for this list operation.

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

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

The description is front-loaded with the core distinction and use cases, then lists optional filters and return/id usage compactly. Every sentence contributes actionable information without redundant restatement.

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

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

There is no output schema, and the description compensates by explaining the returned card fields and how to use returned ids with `arch_delete` or `arch_record_*` calls. Combined with usage guidance, filter semantics, pagination, and annotation-covered safety profile, it provides enough context to invoke the tool correctly.

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

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

With 100% schema description coverage, the schema already explains each parameter, so the baseline is 3. The description reinforces the hard/soft `project` filter semantics and the pagination resume pattern, but it largely repeats structured parameter documentation rather than adding substantial new 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 states a specific verb and resource: enumerate arch cards in a group. It explicitly distinguishes this from vector search, ranking, similarity thresholds, and the sibling `arch_context`, so an agent can identify the tool's role without opening schemas.

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

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

It gives explicit when-to-use guidance: audit, dedupe, migration, or any need for every card rather than top-N similarity results. It names the alternative `arch_context` and explains that it is for relevance-ranked retrieval while `arch_list` is for ground truth.

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 idempotentHint=true, destructiveHint=false, openWorldHint=false, and the description is consistent with them. It adds value by disclosing the return statuses (created | updated) and the fact that identity is the component name. It omits a key behavioral detail for an upsert: whether omitted fields on update merge or are replaced.

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 compact sentences in a logical order: action, when to use, field semantics, return value. The most decision-relevant information is front-loaded and nothing is padded.

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

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

A seven-parameter, four-required mutation tool with no output schema is well served by a description that names the return statuses and explains the two least obvious fields. The remaining gap is the update/merge behavior, which matters for an idempotent upsert but is not addressed.

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 seven parameters are already documented, including the summary four-section structure and anchors stability. The description largely restates schema content (summary sections, anchors surviving refactors) rather than adding format or constraint details, so baseline 3 applies.

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

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

States a specific verb+resource (record an architectural component), adds the upsert-by-name idempotent behavior, and names the exact prerequisite store (arch_context). It is clearly distinguishable from siblings like arch_record_decision and arch_record_lesson.

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 triggers: a logical unit not already in arch_context, or an existing component whose boundary changed. It does not state when NOT to use it (e.g., versus arch_suggest_components or arch_record_decision), so it falls short of the full when/when-not/alternatives bar.

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 identify this as a non-read-only, non-open-world, non-destructive write. The description adds important behavior beyond that: a similarity gate is run, `duplicate` and `similar` outcomes write nothing, and `supersedes` bypasses the gate and marks the prior decision as superseded.

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

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

Front-loads the core purpose, then cleanly lists the three gate outcomes. The `supersedes` escape hatch is clearly separated, and every section adds actionable 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?

Given a 9-parameter mutation tool with no output schema, the description supplies the missing outcome semantics and replacement workflow. It is complete enough for an agent to invoke the tool correctly and interpret the gate outcomes.

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 89%, so most parameters are already well documented. The description still adds meaningful semantics for `supersedes`, explaining that it bypasses the duplicate gate and marks a prior decision as superseded, which is not fully captured by the schema alone.

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: "Record an architectural decision." It also frames the intended trigger condition—non-obvious choices about libraries, patterns, or boundaries—and distinguishes the resulting behavior from simply reading context via `arch_context`.

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

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

Gives explicit when-to-use guidance: "Use when you pick a library, pattern, or boundary that wasn't obvious." It also explains what to do when a duplicate or similar decision is found, including the `supersedes` alternative for deliberate replacement.

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 (readOnlyHint=false, idempotentHint=true), it discloses the server-side similarity gate and its three outcomes (created/updated/similar), which is precisely the behavior an agent needs to interpret the result — and it is consistent with idempotentHint=true. It also implicitly sets expectations about what gets written and what the agent should do on a `similar` result.

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

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

Front-loaded with the purpose, then cleanly structured with headings and a bulleted routing rule; almost every line carries decision-relevant content. The three field definitions partially duplicate the input schema's own parameter descriptions, which is the only wasted 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?

With 8 params, 4 required, and no output schema, the description compensates well by documenting the three possible outcomes in place of a return schema. The remaining gap is operational: `group`, `scope`, and `severity` semantics are never explained, which matters for a tool whose scoping determines where the lesson lands.

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%, so the baseline is 3, and the description largely restates the schema for rule/why/when (adding only "each markdown"). It adds nothing about the undocumented parameters — `group` ("Target group" in the schema too), `scope`, and `severity` — so an agent must guess what a group is and what scope/severity change.

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

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

The first sentence gives a concrete verb and resource ("Record a lesson — a rule the agent should follow next time") and even defines what a lesson is. It sharply distinguishes arch from external agent-side memory files, but never distinguishes itself from the sibling record tools arch_record_component and arch_record_decision, leaving that routing to the agent's 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?

It gives explicit triggers ("user corrects a non-obvious mistake", "you accept an unusual approach that would surprise a future reader") and explicit exclusions ("Skip typos, parser errors, and facts trivially visible in code"). The arch-vs-agent-memory section with a "new engineer joining the codebase" heuristic routes borderline cases decisively.

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 openWorldHint=false; the description reinforces this ('The tool only reads — it does not write component cards') and adds real context beyond annotations: the ranking signal is in-degree, already-covered files are excluded, and results are candidates requiring human/agent judgment rather than authoritative boundaries.

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 what the tool computes and how it ranks, then use-cases, then a caution, then parameters — a logical order with no filler sentences. Slightly longer than strictly necessary (the read-only point is stated twice across description and annotations), keeping it off a 5.

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?

No output schema exists, and the description implies the return shape (ranked list of uncovered high-in-degree files, capped by limit) and the decision workflow. That is sufficient for correct invocation, though the exact fields of a suggestion entry are left implicit.

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 group, project, and limit are already documented with types, bounds, and defaults. The description restates the limit default and max and clarifies that project scopes to 'one project in the group', but adds no new syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('suggest candidate components to record') and precisely describes the mechanism: symbol-graph in-degree over indexed code, restricted to files not already covered by a component card. This is clearly distinguishable from siblings like arch_record_component and arch_list.

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

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

Gives explicit when-to-use triggers (initialising the arch layer for a group, after a large refactor) and contrasts with the alternative behaviour it replaces ('instead of guessing where the boundaries are'). It also spells out the follow-up action ('call arch_record_component for the ones you do') and warns that high-degree files may be utilities rather than components.

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 (readOnlyHint=false, idempotentHint=true, openWorldHint=false), the description adds valuable behavioral context: exactly what data is destroyed across three stores, and that the project will be re-indexed on the next cycle if configured, which clarifies reversibility. It does not discuss permissions or confirmation requirements, but it adds substantial concrete detail for a mutation operation.

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 tightly packed sentences with zero waste: scope first, recovery behavior second, usage guidance last. Every sentence earns its place and the most important destructive detail is front-loaded.

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

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

For a two-parameter mutation tool with no output schema and annotations that already cover safety characteristics, the description provides everything an agent needs: precise destruction scope, recovery behavior, and a usage trigger. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, and the two parameters (group and project) are already fully documented in the schema. The description only refers generally to a 'specific project' and adds no syntax or format details beyond what the schema provides, 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 states a specific verb ('Delete'), a precisely scoped resource ('all indexed data for a specific project'), and enumerates the underlying stores affected: Qdrant chunks, SQLite metadata, and query cache. This clearly distinguishes it from sibling delete tools such as term_delete and arch_delete, which target different resources.

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 says to use this tool when a project's index is corrupted or stale, giving a clear triggering condition. It does not name alternative tools or state when not to use it, so it falls short of the explicit alternatives expected for a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds directional semantics and the notion that links can be 'noisy', but it never describes the shape of the response or how results are presented, which matters since there is no output schema. Some value added, but not rich 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?

Four tight sentences, front-loaded with the core capability, then invocation guidance. No filler or repetition of title/name.

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 full schema coverage and no output schema, the description covers purpose, directions, and workflow sufficiently to call it correctly. The main residual gap is what a returned usage record looks like, which the description leaves to inference.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by explaining what the directions mean in prose and telling the agent to pass chunk_id from prior search results. It maps call semantics onto parameters rather than restating them.

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 symbol relationships: what calls this code, and what this code calls') and immediately distinguishes the two directions. An agent can tell this apart from search_code/get_chunk 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?

Explicitly says when to use it ('Use after search_code or get_chunk') and quotes the user utterances that should trigger it ('where is this used?', 'what calls this?'). It also names the prerequisite source for the required parameter, 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 and openWorldHint=false, so the safety profile is covered. The description adds useful value by saying what comes back (code with symbol definitions and usage info), but says nothing about truncation, size limits, or behavior at large radius_lines 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?

Three short sentences, front-loaded with the core action, followed by the return shape and usage hint. Nothing is wasted.

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

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

No output schema exists, and the description compensates by summarizing the return content. For a two-parameter read tool with full schema coverage and annotations, this is nearly complete; only edge-case behavior for large radii is absent.

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 both parameters are already documented including the 0-200 range and the search_code provenance of chunk_id. The description only restates the existence of optional surrounding context, adding no syntax or tradeoff detail 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?

States a specific verb and resource ('Get a code chunk by ID') plus the optional surrounding-context capability and what the response contains. It is clearly distinct from siblings like search_code and find_usages, though the differentiation is implied through the description rather than an explicit naming.

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 to expand on search results' gives clear context for when to reach for this tool, reinforced by the schema note that chunk_id comes from search_code results. No explicit when-not guidance or naming of an alternative, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing what the tool actually returns (per-group indexed chunk counts) and framing it as a pre-search verification step, though it doesn't explain what a 'group' is or how failures/zero counts present.

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 lines, zero waste: the purpose and output content come first, the usage condition second. Every sentence earns its place.

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

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

For a zero-parameter, read-only, no-output-schema tool, the description covers purpose, return content, and invocation timing. It is slightly thin on return shape and the 'group' vs 'projects' terminology is used interchangeably, which could confuse an agent interpreting results, but the essentials are present.

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

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

The tool takes zero parameters, which is the baseline-4 case. Nothing about the schema needs compensating for in the description.

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 — 'Check indexing status' — and specifies the payload ('number of indexed chunks per group'), so the agent knows exactly what diagnostic data comes back. It does not name a sibling or explicitly contrast itself with search_code/list_projects, leaving differentiation to 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 concrete triggering conditions: verify indexing before searching, or debug empty results. It offers clear context but no explicit exclusions or named alternatives, so there is room left for an agent to guess at edge cases.

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 openWorldHint=false, so safety is covered. The description adds useful context about result shape (grouped by collection, per-project metadata) but says nothing about pagination, ordering, or handling of empty results.

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 action and return content, followed by concrete usage triggers and the optional filter. No wasted sentences.

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 returned metadata and grouping structure. For a zero-required-param read-only list tool, 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 single `group` param is already documented as 'omit to list all groups'. The description restates the optional filtering behavior without adding syntax or edge-case semantics, so the baseline 3 applies.

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

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

States a specific verb+resource (list indexed projects) and specifies what metadata is returned (chunk count, languages, grouped by collection). This clearly distinguishes it from siblings like delete_project, search_code, or arch_list.

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 trigger phrases ('what projects are indexed?', 'which repos are available?') and the optional group filter. It doesn't name an alternative sibling for cases where the user wants search rather than enumeration, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real behavioral context beyond that: results are meaning-ranked chunks with confidence scores, coverage spans all indexed projects, and cost is claimed 50-90% lower than reading full files. The one blemish is the coercive 'REQUIRED — call this FIRST for ANY code question' framing, which risks over-invocation and adds no descriptive information.

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

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

Well front-loaded: the imperative, then scope, then triggers, then rationale, then workflow, then the naming caveat — an agent reading only the first line still routes correctly. Slightly verbose: the trigger list is long and its final clause ('or ANY reference to project code') subsumes everything enumerated before it, and the WHY/token-savings section reads as advocacy rather than specification.

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 four-parameter read-only search with no output schema, the description covers return format, ranking semantics, scope, and the downstream chain, so an agent can call it correctly. Remaining gaps are minor: no guidance on what a confidence score threshold looks like in practice or how 'group' interacts with 'project' filtering.

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 earns an upgrade by clarifying project naming: directory basenames, not org/repo form, with a concrete example ('billing' not 'org/billing') — a convention the schema's 'Project name or "all"' does not convey. The group parameter and limit bounds are left entirely to 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?

States a specific verb and resource — semantic code search across all indexed projects — and immediately defines the return shape (ranked code chunks with symbol definitions and usages). The workflow sentence positions it as the entry point ahead of get_chunk and find_usages, so an agent can tell where it sits relative to siblings 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?

Explicitly says when to call it ('call this FIRST for ANY code question') and enumerates trigger intents: location, implementation, how-X-works, counts, versions, patterns, flows, error handling, auth, API usage. It also hands off explicitly: search → evaluate scores → get_chunk for details → find_usages for dependencies, which names the alternatives and the condition selecting each.

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 readOnlyHint and openWorldHint annotations, the description explains that results are excerpts rather than whole documents, how excerpt boundaries work, that scoring is a fusion rank not a similarity, and that semantic floors can produce empty results. It also discloses audience-ceiling behavior, stale-document indicators, and when to verify against code.

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

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

The description is front-loaded with the key purpose, return shape, and sibling alternative, and nearly every sentence carries useful caveats. It is dense and long for a single paragraph, but the length is largely justified by the complexity of the search behavior.

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

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

For a complex search tool with no output schema, the description covers return format, excerpt limitations, audience filtering, relevance floors, score interpretation, stale-document handling, and empty-result meaning. An agent has enough information to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already defines all seven parameters. The description still adds useful operational context for audience restrictions and the two relevance floors, especially why markdown in code repositories uses a stricter threshold, though much of this overlaps the schema text.

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: hybrid dense semantic plus BM25 keyword search over indexed markdown documentation. It explicitly distinguishes the tool from search_code, making sibling selection clear without needing to inspect schemas.

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

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

It says exactly when to use this tool for prose documentation and when to use search_code for code. It also gives operational guidance: scan alternatives before concluding, treat empty results as undocumented, and read the named file when an excerpt is partial.

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 idempotentHint=true, and the description adds the key trait not covered there: 'No undo' — irreversibility. It does not say what happens to references or usages of the term (find_usages exists as a sibling), which is the one behavioral gap for a destructive operation.

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 very short sentences, zero filler, with the destructive nature and irreversibility front-loaded before the usage hint. Nothing 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?

For a two-parameter, non-open-world mutation with full annotation coverage and no output schema, the definition covers what is needed to call it safely. The only missing piece is the downstream effect on anything referencing the deleted term.

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?

Both parameters are already fully documented in the schema (100% coverage) with per-field descriptions for id and group. The description adds only 'by id', not clarifying the group scoping or whether group/id must match an existing pair. Baseline 3 is appropriate when the schema does the work.

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 ('Hard-delete a glossary term by id') with an explicit qualifier ('Hard') that separates it from soft-removal or edit operations. An agent can distinguish it from siblings like term_record, term_list and term_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?

'Use to remove obsolete or wrong terms' gives a clear condition for selecting this tool. It stops short of naming alternatives (e.g. term_record for renaming or deprecating instead of deleting) or stating prerequisites, so it 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 readOnlyHint=true and openWorldHint=false, so safety is settled. The description adds nothing beyond that: no ordering, no pagination/truncation behavior beyond the schema's limit cap, no indication of what a term record contains, and no statement that empty groups return an empty list.

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 compact sentences with the operation stated first and the purpose second; nothing is redundant. It could be tightened slightly by merging the scope and use-case into one clause, but there is no 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?

For a simple read-only listing tool with full schema coverage and annotations, the essentials are present. However, with no output schema, the description should have said what a listed term looks like (name, definition, project) so the agent knows what it gets back.

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 each of the three parameters is documented in the schema, including defaults and max limits. The description corroborates group and project scoping but adds no format hints or guidance 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?

States a specific verb and resource ("List recorded glossary terms") plus scoping by group and optional project, which is enough to distinguish it from a search or write tool. It does not explicitly contrast with the sibling term_search, so it falls short of a 5.

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

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

"Use to audit coverage or review what terminology has been captured" gives an intended scenario but no exclusions or alternatives. An agent facing both term_list and term_search is left to infer that list is for enumeration and search is for lookup.

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

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

Adds meaningful behavior beyond the annotations: a duplicate/similar gate returns the existing near-identical term instead of writing, and advises reconciliation via update. This complements idempotentHint=true with concrete mechanism, though it doesn't state what a successful write returns.

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

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

Front-loads the core action and field list, then explains the duplicate gate and provenance in a compact follow-up. Dense but each clause carries information; no 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?

For a write tool with full annotation and schema coverage, the description covers the duplicate-gate behavior and authoring workflow, which are the non-obvious aspects. Only the success return value is unaddressed, which is minor given no output schema exists.

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 five parameters are documented in the schema. The description only restates field purposes (canonical name, definition, aliases, project scope) without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (record) and resource (glossary term) and enumerates the content fields, so it is clearly distinguishable from term_search, term_list, and term_delete among the siblings.

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

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

Gives clear usage context: authored by the agent as it learns domain vocabulary, or in bulk via the extract-terminology skill. It also explains what to do when a near-identical term exists (reconcile by updating that term), though it does not explicitly name the sibling update/search tool to use.

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 openWorldHint=false, so the safety profile is covered. The description adds that results include aliases and definitions (useful since there is no output schema), but says nothing about empty results, matching behavior, or how group/project scoping interacts with results. Solid 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?

Three sentences, front-loaded with the purpose, then the usage rule, then the return shape. Every sentence carries information the agent needs and there is no 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 compensates by naming what is returned (term, definition, known aliases), and the lookup/usage guidance covers the required query parameter. For a 4-param, fully-described schema this is complete enough to invoke 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%, with group, limit, project, and query all documented, so the baseline is 3. The description mentions the lookup input type but adds no meaning about scoping or the default limit 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?

States a specific verb (look up) and resource (company glossary) and scopes it to terms, abbreviations, and domain concepts with concrete examples. It is clearly distinguishable from siblings like search_code, search_docs, and term_list/term_record.

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 ordering rule — 'Use this FIRST when a query contains an unfamiliar acronym or product name' — and names the follow-up tools (search_code / search_docs), so the agent knows both the trigger and the workflow. No alternative tool competes for this exact trigger.

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