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

With no annotations, the description carries the full burden and succeeds: it declares 'Every mode is read-only: no call writes to disk', documents the exact host response shape, enumerates all five status values, and explains that 'draft' never reads content and refuses paths outside the project. These are behaviors the agent could not infer from the schema alone.

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

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

Front-loaded with purpose and usage caveat, then organized by parameter and response shape with bold headers and bullets. It is long and partially restates the schema's enum descriptions, but nearly every sentence carries operational detail (status values, fault vocabulary, remediation branches) rather than 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?

There is no output schema, so the description must define returns — and it does, giving the exact host response shape, found:true/false semantics, the four draft outcomes, and the contract/template payload shapes. Nothing an agent needs to call this correctly or interpret its result is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and their enums; the baseline would be 3. The description goes further by specifying per-source response shapes, the 'source: draft requires path' constraint, and the incompatibility of path with any other source, though it retreads some enum text already present 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?

States a specific verb+resource — an on-demand entry point that reads brain sections — and explicitly separates itself from siblings by contrasting with aide_info.brain.status (boot-time reporting) and naming aide_upgrade for remediation. An agent can identify what this tool does and what it is not without opening the schema.

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

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

Gives an explicit when-not ('do NOT call it on every /aide boot') with the reason, plus a named alternative for boot state. It also routes to /aide:brain config, aide_upgrade, and aide_info for specific failure cases, so the agent has a decision path for almost every scenario.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses exact removal scope, status eligibility rules, refusal behavior with file/line reporting, all-or-nothing refusal semantics, and dryRun behavior, plus a clear statement that it never reads or rewrites specs/code/session state. This is unusually rich behavioral context for a destructive file 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 then expands into the necessary safety conditions. Despite being multi-paragraph, each sentence contributes a concrete rule, refusal case, or invocation constraint, and no part is redundant 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 complex destructive tool with no annotations and no output schema, the description is nearly complete: it covers prerequisites, eligibility, refusal behavior, dryRun, and cross-platform intent. The main remaining gap is that it does not describe the success response or reporting format for a real non-dryRun call.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces that path is the module directory and that dryRun is an optional preview, but it does not add substantial new parameter-level meaning beyond the schema. Baseline 3 is appropriate when the schema handles parameter documentation.

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: remove a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) once its cycle has closed. It clearly delimits what is removed from what remains durable (code, intent specs, research specs, session.aide), so an agent can distinguish this cleanup operation from sibling inspection, validation, or frontmatter tools.

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 timing and prerequisites: call after the module cycle closes and record a closing status with aide_frontmatter first. It also says when the tool refuses (proposed/approved status, open items, orphan brief.aide, empty folder) and notes that dryRun is optional and never required, so the agent knows when and how to invoke it directly.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that only the head of each file is read, that responses open with an ancestor chain with alignment status, and that subtree output includes summaries and anomaly warnings. It does not address permissions, failures on a non-existent path, or depth limits of the scan.

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 behavior, which is good, but the two-mode explanation is duplicated almost verbatim between the description body and the schema description, and the length is heavy for a one-parameter read tool. The file-type glossary earns its place as reference material; the duplication does not.

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, so the description must (and does) describe the return shape for both modes, and the tag taxonomy explains how to interpret [plan: approved]-style tags. Gaps remain on error behavior for invalid paths and on how deep the subtree scan descends.

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

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

Schema coverage is 100% and the single path parameter's schema description already spells out both modes, so the description largely restates it. The file-type taxonomy adds interpretive value for reading results but does not deepen understanding of the parameter itself, so this is the baseline 3.

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

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

A specific verb and resource ('Scan for .aide spec files in this project') plus the return artifact ('tree map of where specs live'). The two modes are clearly scoped (project-wide map vs. subtree drill-down), but no sibling tool (aide_read, aide_inspect, aide_info) is named to contrast with, which is the only thing separating this from 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?

Explicit usage contexts are given: 'Use this once to understand the project's spec architecture' and 'Use this to drill into the area you're working on', plus the workflow rule 'Read .aide files BEFORE reading code.' No when-not-to-use cases or named alternatives, so it stops short of 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?

With no annotations, the description carries the disclosure burden well: it states that only allowed lifecycle moves are accepted, describes refusal conditions (unchecked items, incomplete plan for briefs), says refusals name allowed next values, and clarifies that the tool never chooses a value. It does not cover permissions or return shape, but the mutation safety profile is clear.

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 definition is dense but front-loaded around read-or-change behavior, and every sentence contributes operational detail. It could be structured with clearer separation between lifecycle rules and refusal rules, but there is little waste.

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 three-parameter mutation tool with no annotations and no output schema, the description is quite complete: it covers read versus write usage, which files have governed values, lifecycle transitions, and refusal behavior. Minor gaps remain around exact read return format and error cases for invalid paths.

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 already 100%, so the baseline is 3. The description adds meaning beyond the schema by mapping fields to file types (alignment for intent specs, status for plan/brief/todo) and listing the lifecycle values, which helps the agent select valid field/value combinations.

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 states a specific verb pair ('Read or change') and resource ('one governed frontmatter value of an AIDE file') with clear scope ('leaving every other byte untouched'). It does not name or distinguish itself from sibling tools such as aide_read, but the purpose is unambiguous.

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

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

The description gives explicit usage conditions: pass path alone to read, use alignment on intent specs, use status on plan/brief/todo files, and avoid the tool entirely for session records, research specs and brain.aide. It lacks explicit routing to sibling tools, so it falls short of the top score.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it explains that no path validation or disk stat occurs, that missing `.aide/versions.json` collapses to `[]`, that offline checks fail silently, that upgrades only take effect in a new session, and that soft fields never gate the pipeline. It also documents every `brain.status` value, its shape, and its remediation.

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 purpose and uses bold field headers and status lists to make a complex return contract navigable. It is long, and the sync remediation text is repeated almost verbatim for `no-mcp-entry` and `mcp-drift`, which is a minor conciseness cost for an otherwise structured definition.

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 no annotation coverage, so the description must fully explain the tool's return shape and operational meaning. It does: every top-level field, null condition, status enum, fault shape, hint array, and gating consequence is documented.

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

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

The schema has zero parameters, so baseline is 4; the description adds meaningful context by stating no parameters are needed and that the tool uses the server's working directory. That is the only parameter-like semantic relevant 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?

The description opens with a precise role: a boot-time reporter invoked by the orchestrator at startup. It then enumerates the exact top-level fields returned (`outdated`, `behind`, `brainMigration`, `brain`), making the tool's scope unmistakable and distinct from diagnostic siblings like `aide_inspect` or `aide_validate`.

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

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

It explicitly states when the tool is used (boot-time startup), how the orchestrator must branch on each field, and which conditions are soft notifications versus hard gates. It also tells the agent to halt only when `brain.status` is not `'ok'`, and that the other fields never gate the pipeline.

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?

No annotations exist, so the description carries the full burden and meets it: it discloses that the tool writes files to disk itself, that it never overwrites the brain config or session record, how would-skip/would-overwrite statuses behave, and what happens on failed MCP installs. It even documents the response shape (manifest fields, brainSummary fields) without an output schema.

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

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

The purpose is front-loaded and the structure is legible, but the text is very long and repeats the overwrite logic twice (branch-logic block, then again in the numbered wizard steps), and includes self-referential noise like 'not prose'. Much of the length is load-bearing for a multi-step wizard, but it could be tightened considerably.

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

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

For a 3-parameter orchestration tool with no output schema and no annotations, the description supplies everything an agent needs: return shapes for both call modes, per-category step statuses, exception handling for MCP/brain/session/IDE steps, and the interaction pattern. Nothing material is left 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?

With 100% schema coverage the baseline is 3, and the description goes beyond it by explaining the semantic difference between omitting `category` (metadata-only summary) versus supplying it (writes files and returns a manifest), and by describing when to use `framework` to override detection. It does not add anything about `path` 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?

Opens with a specific verb+resource: 'Bootstrap the AIDE development environment into a project', and immediately distinguishes itself from siblings by naming aide_upgrade, aide_brain, and aide_scaffold in their respective exception clauses. An agent can tell exactly what this tool does and which sibling handles the adjacent work.

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 two-call protocol (call without `category` first, then per-category), a category ordering walk, and per-case rules (pure-create = apply silently, overwrite-bearing = prompt, inherent-decision = always prompt). It also states exclusions and handoffs ('do not use the Write tool for new files', 'never replace an existing aide entry').

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool operates without opening the full file (lightweight), and searches across multiple file extensions (ts, tsx, js, jsx, mjs, cjs). It could mention return format or performance constraints, but overall it is transparent.

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

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

The description is concise (two sentences plus one additional sentence on file types) and front-loaded with the core functionality. Every sentence adds value, no wasted 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?

The description explains the input and what is returned (JSDoc, signature, kind) adequately for a simple lookup tool. No output schema is needed; the description covers the return values. It fits well within the sibling tools context.

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

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

Schema coverage is 100% with both parameters described. The description adds context beyond schema: it explains how to use the optional file parameter to narrow the search when location is known. This provides meaningful guidance beyond the schema's basic descriptions.

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

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

The description clearly states it returns JSDoc, signature, and kind for a named symbol without opening the full file, distinguishing it from siblings like aide_read which opens the full file. The verb 'inspect' and resource 'symbol' are specific.

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

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

The description explicitly advises when to use this tool: when an agent knows a function name from an import list or orchestrator file. It also explains the optional file parameter for narrowing search. However, it does not explicitly state when not to use it or mention alternative tools.

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

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

With no annotations, the description carries full burden. It details the output structure (content, type, related specs, links), which goes beyond a minimal description. However, it does not mention error handling or read-only status, though that is implied.

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

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

The description is two sentences: first defines functionality, second gives usage guidance. No unnecessary words, front-loaded with key details.

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

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

The tool is simple (1 param, no output schema). The description fully explains the return value and usage context, making it complete for the agent.

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 baseline is 3. The description adds no additional meaning for the 'path' parameter beyond the schema 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?

The description clearly states the verb 'read', the resource '.aide spec file', and details the returned information (file content, type, related specs, links). It also explicitly distinguishes from sibling tool aide_discover.

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

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

The description explicitly instructs to use this tool after aide_discover, providing clear context on when to use it versus alternatives.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses no-overwrite behavior, skip-line reporting, initial values, naming rules, auto-renames, root special cases, plan prerequisites, and session file handling. These are meaningful behavioral traits beyond parameter mechanics.

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

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

The core purpose and no-overwrite rule are front-loaded, and most sentences carry necessary edge-case information. It is dense and lengthy for a two-parameter tool, but the complexity of naming, renaming, and prerequisite behavior justifies most of the detail.

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

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

Given the complexity, lack of annotations, and no output schema, the description is complete: it covers creation behavior, prerequisites, side effects, naming rules, edge cases, and failure/no-op outcomes. An agent would have little reason to guess about how to invoke this 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 already 100%, so the baseline would be 3, but the description adds substantial meaning: it explains the semantic effect of each type, including research-triggered renames, the research+intent pair for both, plan refusal, and the always-fixed session path. Directory semantics for '.aide' and '.' are also clarified beyond the schema.

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

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

The first sentence states a specific verb and resource: 'Create a new AIDE working file from its blank template, under its canonical name.' It also distinguishes this creation behavior from deletion/replacement by naming aide_cleanup 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?

The description gives clear usage conditions and exclusions: existing files become no-ops, plans are refused without an intent spec, and replacement requires aide_cleanup first. It does not broadly compare against other creation/setup siblings such as aide_init, but the when/when-not guidance is strong.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the category call writes files directly to disk, that the agent never sees canonicalContent, that brain changes are guarded by beforeHash and refused when bytes drift, and that config edits are byte-preserving (line endings, formatting, 'every other byte unchanged'). Failure modes are also surfaced — failed installs must stop the flow, malformed results must not be overwritten, refused results carry instructions. This is unusually rich behavioral disclosure for a zero-annotation 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?

Structure is genuinely good — purpose first, then the two-call pattern, a numbered agent checklist, then per-category notes — so it is front-loaded. But the 'MCP step' paragraph alone is a multi-hundred-word run-on covering exit code 2, npx timeouts, pinned-vs-global entries, and shim detection, far beyond what is needed to select and invoke the tool. Much of this is error-path guidance that belongs in tool responses, not the selection surface.

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 6-parameter, zero-annotation, no-output-schema tool, the description is complete: it names the manifest fields (filePath, status, name), the brain outcomes (inserted/adapt/change/applied/refused), the mcp result variants (prescription, pinMove, globalSwitch, malformed, instructions), and the ordering constraints among calls. An agent would not need to guess at any return shape before invoking.

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 baseline is 3, and the description earns above it by explaining cross-parameter semantics: which calls are legal together (targetVersion only with no category or category 'mcp'), the brainChange preview-vs-apply pairing with beforeHash, and per-category effects of 'category'. Most of this is restated from the schema fields rather than added, and the added value is buried in dense prose rather than attached to the parameters.

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

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

The opening sentence is a specific verb+resource+output: 'Compare the AIDE methodology artifacts ... against the canonical versions and return structured JSON results grouped by category.' It also draws a hard boundary ('NOT for editing user .aide specs — it inspects methodology infrastructure only'). It does not differentiate against the many adjacent siblings (aide_info, aide_validate, aide_brain, aide_scaffold), and its own dual inspect/write nature is only reconciled deep in the body.

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?

Trigger conditions are explicit and enumerated ('update AIDE, sync AIDE, refresh AIDE, check for AIDE updates'), and the when-not case is stated. The two-call progressive-disclosure protocol and the one-at-a-time AskUserQuestion wizard are spelled out step by step. What is missing is routing to alternatives: no sentence says 'use aide_info to just read the version' or 'use aide_brain for brain edits', so sibling selection is left to inference.

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

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

With no annotations, the description carries the full burden, and it does disclose useful detection semantics (root intent spec never orphaned, plan presence never decides orphaning, valid alignment enums). However, it never states whether validation is purely read-only or can mutate files, nor what the response looks like, leaving the most important behavioral question unanswered.

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 clause, but the remainder is one long run-on sentence with deeply nested parentheticals that are hard to parse. The enumerated checks earn their place, but the structure could be far clearer as a list.

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 no annotations, so the description should cover return shape and mutation behavior; it covers the check catalog but not the result structure or whether findings are returned as codes/severities. Adequate to know what it looks for, incomplete for knowing how to consume the result.

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

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

Schema coverage is 100% and the single optional `path` parameter is fully documented in the schema ("Subdirectory to validate (defaults to entire project)"). The description adds nothing about scoping or path semantics, 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 opens with a specific verb+resource ("Health check for .aide spec files") and enumerates the exact defect classes it detects, so an agent knows precisely what the tool does. It never names a sibling (e.g., aide_inspect, aide_cleanup) to differentiate itself, which is the only thing separating it from 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?

Usage is implied by "health check" and by the remediation aside for plan-without-spec ("write the folder's spec, never delete the plan"), but there is no explicit when-to-use, when-not-to-use, or alternative-tool routing. The agent must infer that this is the pre-flight/diagnostic step before aide_fix-style work.

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