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: it discloses exactly what is destroyed versus protected, the refusal conditions (unchecked items, empty/unchecked todo.aide, brief.aide without plan), the refusal reporting format (each unchecked item with file and line, nothing removed), and the allowEmptyPlan exception. This is unusually rich for a destructive 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?

It is dense but well front-loaded, opening with the core action before enumerating edge cases. Some phrasing about allowEmptyPlan is duplicated between description and schema, but overall every sentence carries decision-relevant 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?

For a destructive cleanup tool with no annotations and no output schema, the description covers all the behavioral ground an agent needs: scope, protected files, refusal conditions, error reporting, and the two optional flags. Nothing critical 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 all three parameters are already documented in the schema with nearly identical wording to the description (allowEmptyPlan's 'overrides nothing else' phrasing appears in both). The description adds little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource — removing a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) after the cycle closes — and explicitly bounds it by naming everything it never touches (intent specs, research specs, code, session.aide). An agent can distinguish this cleanup tool from siblings like aide_validate or aide_inspect 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?

It gives clear use conditions (only once a module's cycle has closed, only when checks are complete) and explicit invocation guidance ('Call it directly... dryRun... is never a required step'). It does not name sibling alternatives for the cleanup decision, but the when-to-use context 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 fully discloses behavior: different responses based on path, ancestor chain with alignment status, summaries and warnings, and explains .aide file types. No contradictions.

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 longer but well-structured with clear sections. Front-loaded main purpose. Could be slightly more concise, but every sentence adds value for this complex 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?

No output schema, but the description thoroughly explains the output structure (ancestor chain, subtree) and file types. Covers both modes comprehensively given the tool's complexity.

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

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

Schema coverage is 100% with a single parameter 'path'. The description adds significant context beyond schema: different outcomes, ancestor chain structure, and usage scenarios, enhancing agent understanding.

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 'Scan' and the resource '.aide spec files', returning a 'tree map'. It distinguishes between two modes (with/without path), which differentiates it from siblings like aide_read and aide_inspect.

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 guidance on when to use without path (project-wide overview) and with path (drill into area). Does not explicitly state when not to use, but the progressive disclosure concept and file type explanations provide clear 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?

With no annotations, the description carries the full burden and does so thoroughly: it discloses that staleness is informational only, that a missing versions.json silently collapses to [], that `behind` is null when offline, that no path validation or directory stat ever occurs, and exactly which statuses require halting. These are genuine behavioral traits beyond anything the schema provides.

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 response is long, but it is front-loaded with the soft-vs-hard-gate distinction and uses bolded field names as scannable anchors, so the structure aids navigation. It is dense rather than wasteful, though the two lengthy remediation paragraphs about `no-mcp-entry`/`mcp-drift` contain duplicated wording that could be tightened.

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 fully describe the return shape — and it does, covering every top-level field, the null conditions, the five `brain.status` values with their faults and remediations, and the always-present `hints` array. An agent has everything needed to interpret and branch on 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds a small amount of useful context by noting that the call relies on the server's working directory, which explains how a zero-arg tool determines its target, but there are no parameter semantics to enrich further.

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 use case — 'Boot-time reporter called by the orchestrator at startup' — and enumerates the exact fields returned (outdated, behind, brainMigration, brain), making the resource and function unambiguous. However, it never differentiates itself from plausible siblings like aide_inspect or aide_validate, which also sound like status/config readers, so it falls short of the rubric's 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?

It clearly states the invocation context (called by the orchestrator at startup) and gives explicit branching guidance: soft notifications that never gate, versus `brain` as a hard gate where the orchestrator 'must halt' when status is not 'ok'. It never names an alternative tool to use instead, 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?

No annotations are provided, so the description carries the full burden — and it delivers. It discloses that the tool writes files directly to disk, that `would-overwrite` steps require approval, that `would-skip` steps are never written, that it never touches MCP config, and that it never overwrites an existing `.aide/config/brain.aide`. That is unusually rich behavioral context for a mutation 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?

Purpose is front-loaded, but the body is extremely long and partly redundant — the branch logic section and the numbered wizard section re-explain the same one-at-a-time rules, and much of the text is agent-turn UI guidance rather than tool semantics. Substantial trimming is possible 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?

There is no output schema, so the description must describe returns — and it does in detail: the metadata summary (statuses, brainHints, framework), the write manifest (created/overwritten/exists), MCP `prescription` data, and the brain `brainSummary` shape. For a tool of this complexity, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the `category` param's role in the two-call pattern, `aideMode` pairing with category=mcp (including the global-vs-local tradeoff and npm install fallback), `brainMode` with category=brain, and `framework` as a forced override on re-call. This goes beyond the schema's field-level 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?

States a specific verb and resource: "Bootstrap the AIDE development environment into a project," and immediately frames it as a two-call progressive-disclosure tool. The role is unambiguous. It never names a sibling (aide_scaffold, aide_upgrade, aide_cleanup), so it does not explicitly differentiate itself from adjacent 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?

Extensive when-to-use guidance: call without `category` first, then per-category, with explicit branch rules for pure-create vs overwrite-bearing vs inherent-decision categories. However, it gives no when-not-to-use and never routes the agent to alternative tools such as aide_upgrade or aide_cleanup.

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, the description fully discloses key behaviors: naming rules, auto-renaming of existing .aide files when creating research.aide, and the specific purpose of each type. It could mention potential side effects like overwriting, but the information is sufficient.

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 and well-structured, with a clear main sentence followed by bullet points for types. Every sentence contributes meaning without being verbose.

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

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

Given the tool's simplicity (2 params, no output schema, no annotations), the description covers all necessary aspects: purpose, naming conventions, type meanings, and usage context. An agent can correctly select and invoke the tool.

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

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

Schema coverage is 100%, baseline 3. The description adds significant value beyond the schema by detailing each type's purpose and naming interactions, which helps the agent decide values for the 'type' 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?

The description clearly states the tool creates .aide spec files and enforces naming conventions. It explains the types and interactions, distinguishing it from sibling tools like aide_read or aide_validate, which are for different purposes.

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

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

The description provides clear context for each type (intent, research, etc.) and when to use them, but does not explicitly state when not to use this tool or suggest alternatives. The sibling tools cover other operations, making usage relatively clear.

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

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

With no annotations, the description carries the entire burden and does so: it discloses that the tool writes files to disk itself, that no canonicalContent is ever returned, the exact outcome shapes for the brain category, the beforeHash guard and refusal behavior on changed bytes, that user code and specs are never touched, and the MCP matching rules. This is unusually rich behavioral disclosure.

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

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

Purpose and usage are front-loaded in the first two paragraphs, and given the tool's branching brain/mcp behavior, most sentences carry operational weight. It is nevertheless very long and includes recursive prose (the nested brain steps) that partly duplicates the schema's own descriptions, costing some crispness.

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 and no annotations, the description must cover returns and it does: manifests, statuses, outcome values, refusal instructions, and the mcp prescription/tip semantics. Combined with 100% parameter coverage, an agent has everything needed to call this correctly across all five parameters.

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 real meaning beyond the schema: it explains that omitting category yields metadata-only summaries, that the second call is what performs writes, and that brainChange alone previews while brainChange + beforeHash applies. The only shortfall is that it reads more as workflow narration than as per-parameter discrimination.

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: compare AIDE methodology artifacts against canonical versions and return grouped JSON. It scopes the tool precisely, both positively (methodology infrastructure) and negatively (NOT user .aide specs), which cleanly separates it from sibling tools like aide_init, aide_cleanup, and aide_brain.

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 triggers are listed (update AIDE, sync AIDE, refresh AIDE, check for updates), an exclusion is stated, and the full agent workflow — call without category, ask per category, repeat with category — is spelled out. The one-at-a-time wizard pattern with AskUserQuestion leaves no ambiguity about when and how to sequence calls.

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 must disclose behavior. It lists the specific checks performed, which is good, but it omits details about the output format, side effects, or whether any changes are made. The description is somewhat transparent but incomplete.

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

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

The description is a single sentence but front-loaded with the main purpose. It lists multiple items clearly separated by commas. Could be improved with bullet points, but it's reasonably concise and informative.

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 of the tool (multiple checks) and the absence of an output schema, the description covers the input and the nature of the checks. However, it fails to describe what the tool produces (e.g., a report, exit code), which is important for an agent 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%, so the parameter 'path' is documented in the schema. The description adds that it defaults to the entire project, which is a slight extension. This meets the baseline for high coverage.

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

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

The description uses a specific verb 'health check' and resource '.aide spec files', and lists distinct detections like orphaned specs, missing specs, naming conflicts, etc. This clearly differentiates it from sibling tools like aide_init or aide_read.

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

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

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it. It simply states what it does.

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