architect-anything-mcp

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

Annotations already disclose that this is a non-read-only, non-destructive, idempotent update. The description adds that it records one checklist item with a concrete note, but it does not explain overwrite behavior, permission requirements, or what happens when recording the same item again.

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 front-loaded sentence with no wasted text. It efficiently states the action and the two most important payload concepts.

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 mutation tool with no output schema and 0% schema description coverage, the description is too thin. It leaves required workspace semantics, enum meanings, and optional note behavior undocumented.

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 0%, so the description must carry parameter meaning, yet it only clarifies status and note and implies item. It omits the required workspace parameter, does not explain note optionality, and does not describe the status enum values.

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

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

The description uses a specific verb and resource: 'Record the answer to one investigation checklist item,' and names the key payload elements status and note. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as aa_upsert_claim or aa_upsert_section.

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 states the action but gives no when-to-use guidance, prerequisites, or alternative sibling tool to choose instead. An agent can infer that it is for checklist answers, but there is no explicit usage policy.

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=false, idempotentHint=true, and non-destructive, so the safety profile is covered. The description adds the append semantics and that the record is 'hashed,' but doesn't explain what file interaction occurs or what gets written when append is false.

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

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

A single compact sentence with the core action front-loaded and the append variant tacked on. Efficient, though it underspecifies rather than being truly concise.

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 7 parameters at 0% schema coverage and no output schema, the description should carry far more weight about the fields and the result. It leaves most parameters and the return behavior unexplained.

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 0% across 7 parameters. The description only touches 'path' (via 'local file') and 'append'; id, kind, note, lines, and workspace are completely undocumented anywhere, leaving the agent to guess their meaning.

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

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

States a specific verb and resource: 'Build a hashed evidence record for a local file.' This is meaningfully distinct from siblings like aa_inventory or aa_compare, though it never names an alternative 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 append=true clause explains one behavioral variant but gives no when-to-use guidance, prerequisites, or alternatives among the many sibling tools. An agent knows what it does but not when to pick it over aa_inventory or aa_upsert_claim.

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 readOnly, idempotent, non-destructive, and closed-world behavior, and the description adds no further behavioral context such as prerequisites, output characteristics, or handling of the compared artifacts. It does not contradict the annotations, but it contributes little beyond the purpose statement.

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 a single front-loaded sentence with no wasted words. Its brevity is efficient, though it is close to under-specified for a tool with four parameters.

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 tool with four parameters, no parameter descriptions, and no output schema, the description is too sparse to explain what the inputs represent or what a comparison produces. Annotations cover the safety profile, but key invocation details are 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 0% schema description coverage, the description must explain the four parameters, but it only implies that before and after are the two compared items and that kind selects inventory versus report. It says nothing about the optional 'out' parameter or whether before/after are paths, IDs, or raw content.

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 ('Compare') and resource ('two inventories or two reports'), so the tool's basic function is clear. It does not explicitly differentiate itself from sibling tools such as aa_inventory or aa_validate, which keeps it 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?

It gives no when-to-use guidance, prerequisites, or alternatives; it only names the operation. An agent must infer that this is the correct tool whenever two inventories or reports need comparison.

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=false and idempotentHint=true, so the agent knows this writes but is repeatable. The description adds real value with 'immutable snapshot', warning that the result is frozen, but it says nothing about what 'check collection state' enforces, what happens when the state check fails, or whether a prior snapshot is overwritten.

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

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

A single 14-word sentence with the verification step front-loaded before the publish action, and no filler whatsoever.

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

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

With no output schema, the description carries the burden of explaining what the resulting snapshot is and what the collection-state check can report, and it does neither. Combined with two undocumented parameters on a non-readOnly tool, an agent lacks what it needs to invoke this confidently.

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 only 33%: 'emit' is documented in the schema, while 'workspace' and 'partial' are bare. The description mentions no parameters at all, so it fails to compensate for the undocumented required workspace string and the partial-workflow flag, whose semantics are non-obvious for a publish operation.

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?

It states two concrete actions on a specific resource: verify collection state and publish the authored report as an immutable snapshot. That is far clearer than a tautology, though it never names how it differs from aa_validate or aa_render, which an agent could easily confuse with this step.

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?

There is no explicit when-to-use or when-not guidance, and no alternative is named. The only signal is the implied finality of 'publish ... as an immutable snapshot', leaving the agent to infer that this is the terminal step after aa_render/aa_validate rather than using those.

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=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the result goes into a *new* JSON file, which is consistent with non-destructive behavior, but it omits whether an existing 'out' file is overwritten, how large a tree it will walk, and what a 'fingerprint' contains.

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

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

A single front-loaded sentence with no filler and no repetition of the schema or annotations. It is efficient, though the terseness tips into under-specification rather than being maximally 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?

For a filesystem-writing tool with three parameters, partial schema coverage, and no output schema, the description leaves too much implied: fingerprint algorithm/fields, recursion behavior, overwrite semantics for 'out', and the shape of the produced JSON. An agent would have to guess before invoking it.

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 only 33%: 'exclude' is documented in the schema, while 'target' and 'out' are bare strings. The description only loosely maps them ('local files' for target, 'new JSON file' for out) and leaves open whether target is a directory, a single file, or a glob.

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: fingerprint local files into a new JSON file. An agent can tell this apart from the sibling aa_* workflow tools (start/status/upsert/render), none of which do file inventory. The verb 'fingerprint' is slightly jargon-y (hash? metadata?) but the core action is clear.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives or where this fits in the aa_* pipeline. 'Selected' hints that some scoping applies but never explains how selection works or when an agent should call this instead of plainly reading files.

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 it is not read-only, is open-world, and is non-idempotent, so safety framing is partly covered. The description adds meaningful context beyond that: output and a receipt are persisted at a new path. It doesn't say what happens if the path exists, whether the receipt format is fixed, or what errors look like, leaving gaps for a mutating, open-world tool.

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

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

A single front-loaded sentence with no filler. It is efficient, though arguably under-specified rather than concise — nothing wasted, but little delivered.

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 and no annotation-level detail on returns; parameters are undocumented; no explanation of the receipt or output artifacts the tool claims to retain. For a mutable, open-world CLI wrapper with a bare schema, the description is too thin for an agent to call 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 0% across three parameters, so the description must compensate and largely fails. 'At a new path' loosely hints at the required `out` parameter, but `arguments` (the CLI args array) and `config` are entirely unexplained in both schema and 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 verb 'Run' plus 'one REA CLI operation' identifies the operation type, but 'REA CLI operation' is opaque — it doesn't say what the CLI does or what kinds of operations exist. It is distinguishable from upsert/validate siblings by implication, but not explicitly from aa_rea_status.

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?

There is no guidance on when to use this versus aa_rea_status or the other aa_* tools, nor any prerequisites (e.g., a run must be started first with aa_start). The phrase 'one ... operation' implies single-call scope but nothing more.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds a useful limitation beyond annotations: it does not prove providers are ready or MCP is connected.

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

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

Two short sentences with no wasted language; purpose is front-loaded and the caveat follows directly. It is appropriately compact, though its brevity leaves gaps that other dimensions penalize.

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 and annotations cover safety, but the description does not explain what a probe returns or what the config parameter means. With no output schema and 0% parameter description coverage, those gaps matter.

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 has one optional config parameter with 0% schema description coverage. The description never mentions config or explains what it controls, so it does not compensate for the missing schema 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?

States a specific verb and resource: "Probe an existing REA CLI." The title reinforces this as a status check, but the description does not explicitly distinguish it from siblings such as aa_status or aa_rea_run.

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

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

The phrase "existing REA CLI" implies this is for an already-present CLI and the caveat clarifies what the probe does not establish. However, it gives no explicit when-to-use guidance or alternatives among sibling 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so safety basics are covered. The description adds nothing about what actually gets written, where output lands, or whether it overwrites existing files — the exact behavior an agent needs for a publishing step.

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 a single short sentence with no padding, which is good, but it is under-specified rather than concise — the one sentence spends its words on a cryptic qualifier instead of the operation's mechanics.

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/publish tool with three parameters, no output schema, and two undocumented required arguments, the description leaves too much unknown: input shape, output artifacts, and location. An agent cannot confidently invoke it from this text alone.

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

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

Schema coverage is only 33%: the emit enum is documented in the schema, but the required `report` and `output` parameters have no description anywhere. The description does not clarify whether `report` is a path, an ID, or an inline model, nor what `output` denotes (destination path? format?).

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 verb+resource pair ("publish an authored report model") gives a rough idea, but the qualifier "without an investigation workspace" is opaque internal jargon that an agent cannot decode. It does not distinguish this from siblings like aa_finish or aa_validate, which likely also conclude a report workflow.

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?

There is no statement of when to call this versus aa_finish, aa_validate, or aa_start, and no prerequisites (e.g. must the report be authored/validated first?). The only hint at a scenario — "without an investigation workspace" — is not explained.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds no behavioral context of its own: it doesn't say what the contract contains, what happens when subject is omitted (it is optional), or any rate/output characteristics.

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

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

A single front-loaded sentence with no filler. It is tight, though the brevity borders on under-specification rather than true economy.

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, so the description should hint at the returned contract's shape, yet it does not. Combined with an optional enumerated parameter whose default is unexplained, the definition leaves an agent short of what it needs to invoke confidently.

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 0%, so the description must carry parameter meaning. It merely restates the three enum values without explaining what a 'report', 'investigation' or 'commands' contract is, and critically it says nothing about the default when the optional subject is omitted.

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 verb ('Return') and an object ('machine-readable contract') and names the three subjects, which mirrors the enum. However, 'contract' is never defined, and nothing distinguishes this from siblings like aa_status or aa_inventory, so the agent cannot confidently tell what the tool produces.

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?

There is no statement of when to call this tool, no prerequisites, and no mention of alternatives among the fifteen aa_* siblings. The agent must infer usage entirely from the name.

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, and readOnlyHint=false, so the safety profile is covered. The description adds almost nothing beyond that — critically, it does not say whether setting one field overwrites or merges with existing metadata, which is the key behavioral question for a 'set meta' tool.

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

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

A single tight sentence with the verb front-loaded and no filler. Efficient, though the enumeration format consumes its length on field names already visible in the schema.

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

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

With 9 parameters, no schema descriptions, no output schema, and a mutation that touches report state, the description is too thin — it omits overwrite/merge semantics, the meaning of the two enum fields, and the role of the required workspace.

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 0%, so the description must carry the burden, but it only restates field names in prose without explaining values — e.g. what 'coverage' vs 'run_status' mean or how they differ, or what 'changes' and 'limitations' should contain. The required 'workspace' parameter is not even mentioned.

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 ('Set') and resource ('working report' metadata), then enumerates the fields it writes. This lets an agent know it is a metadata-writer rather than a content-writer, though it never distinguishes itself from siblings like aa_upsert_section or aa_finish.

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?

There is no guidance on when to call this versus aa_start, aa_finish, or the upsert tools, and no prerequisites or sequencing hints. The agent must infer that this is used mid-run to record report metadata.

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=false and destructiveHint=false; the description adds real value by warning that the call does not analyze the target, so the agent knows the work happens downstream. It does not say where the workspace is created, whether re-invocation overwrites prior state (idempotentHint=false), or how later aa_* calls reference it.

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

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

Two short sentences, front-loaded with the purpose and followed by the scope exclusion; nothing is padded. It is efficient, though the brevity edges into under-specification rather than true density.

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

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

For an 8-parameter, non-idempotent write tool with no output schema and four undocumented parameters, two sentences are not enough. The agent cannot tell what state is created, what the return looks like, or which sibling to call next.

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 only 50% and the description mentions no parameter at all. It never explains target format, what kind=auto infers, when lens/mechanism requires focus, or what output/depth control — leaving roughly half the parameters documented nowhere.

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 verb+resource combination ('Prepare ... investigation workspace') is specific, and the negative clause 'Does not analyze the target' carves out a distinct scope versus the analysis/upsert siblings. What 'target' actually is (repo path, URL, capture) is never stated, which keeps 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?

'catch-up or focused investigation workspace' implies when to use it, but no sibling is named and no sequencing is given, even though the sibling list clearly shows this is the entry point of an aa_* pipeline (aa_inventory, aa_status, aa_finish). The agent must infer that this call precedes them.

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 fully declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds the content of the read, but says nothing about permissions, failure modes, or result shape.

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

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

A single front-loaded sentence with no filler. Some domain jargon ('depth', 'lens') is left unexplained, which costs a point.

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 rich safety annotations and no output schema, the description is serviceable, but the unaddressed workspace parameter and the vague 'depth/lens' vocabulary leave gaps an agent must guess at before calling.

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

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

There is exactly one parameter (workspace) with 0% schema description coverage, and the description never mentions it — not its meaning, scoping role, or format. The sole undocumented parameter is left entirely to inference.

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?

Specific verb (Read) and resource (an investigation's status), with the returned facets enumerated: checklist, depth, lens, and report validation state. It reasonably distinguishes it from write/validate siblings, though it never names them 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 states what is read but gives no guidance on when to call it versus alternatives like aa_validate, aa_checklist, or aa_rea_status, nor any prerequisites. Usage is only inferable from the field list.

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 disclose that this is a non-readonly, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context with 'immediate reference validation,' but it does not explain what validation requires, what happens on invalid references, or how existing claims are affected.

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 front-loaded sentence with no filler. The core action and the validation qualifier both earn their 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 six-parameter mutation tool with two enums and no output schema, the description is too thin. It covers the core action but omits parameter meaning, expected reference behavior, and sibling routing. Annotations help with safety and idempotency, but they do not fill the remaining gaps.

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 0% across six parameters, including required workspace, id, and text, plus optional evidence, authority, and freshness enums. The description mentions no parameters at all, so it does not compensate for the schema's missing 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: 'Add or update a claim in the working report.' It also names a distinctive behavior, 'immediate reference validation,' which helps distinguish it from generic upsert tools. It does not explicitly differentiate from relevant siblings like aa_cite or aa_validate, 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?

Usage is implied: use this to create or modify report claims. However, there is no explicit guidance on when to choose this over aa_cite for references, aa_validate for validation, or aa_upsert_section for other content types. No when-not or prerequisite information is given.

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 and destructiveHint=false, so 'add or update' largely restates them; the real added value is 'immediate structural validation', which tells the agent invalid diagrams are rejected at write time. It does not say what a validation failure looks like, whether a failing upsert leaves the prior diagram intact, or whether the id keys a replace 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?

A single front-loaded sentence with no filler and no redundancy. It is efficient, though the brevity is a symptom of under-specification rather than tight writing.

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?

This is a mutating tool with 6 required parameters, nested node/edge structures with claim references, and no output schema, yet the description is one sentence. An agent gets no guidance on the node/edge/claims model, the 12-node cap, or how 'freshness' should be set, so it cannot call this correctly from the description alone.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the burden of explaining them and adds nothing. It never explains what 'kind' selects, what 'freshness' means for a diagram, that 'id' is the upsert key, or what the per-node/edge 'claims' references point at.

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 pair ('Add or update') and resource ('a diagram in the working report'), which is enough to tell it apart from aa_upsert_claim and aa_upsert_section by artifact type. It does not explicitly name those siblings as alternatives, so it stops 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?

No when-to-use or when-not-to-use guidance, and no reference to the sibling tools that write other report artifacts. The only hint about context is 'in the working report', which implies a pre-finish/render stage but leaves the sequencing 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 idempotency, non-destructiveness, and write behavior. The description adds one useful behavioral detail, that replaced scaffold placeholders are pruned, but it does not explain update semantics, how optional fields like table or freshness interact, or what the result looks like.

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

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

A single efficient sentence with no wasted words, and the core action is front-loaded. It is concise, though this brevity contributes to under-specification elsewhere.

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

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

For an 8-parameter mutation tool with a nested table object and no output schema, the description is far too thin. It omits parameter semantics, prerequisites, and any explanation of how updates merge with existing section content.

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 eight parameters with 0% description coverage, and the description gives no parameter-level meaning at all. It does not clarify required claims, workspace, id, body, detail, or freshness, nor the nested table object, so it fails to compensate for the schema gap.

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: add or update a report section. It implies the section-level counterpart to aa_upsert_claim and aa_upsert_diagram, but it never names or explicitly distinguishes those 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?

There is no guidance on when to use this tool versus aa_upsert_claim, aa_upsert_diagram, or other siblings, nor any prerequisites such as whether a run must be started first. The only operational note is a side-effect statement about pruning placeholders.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that validation can optionally check local files and hashes, which is useful behavioral context beyond the annotations. However, it does not explain what validation failures look like or how the report is interpreted.

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, front-loaded sentence with no wasted words. It immediately states the action and the optional 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?

With no output schema and 0% parameter description coverage, the description is too thin. It does not explain what a 'report model' is, what format the report parameter expects, or what a successful validation returns. For a tool with two undocumented parameters and no return schema, more context is needed.

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 0%, so the description must compensate. It clarifies check_files as 'optionally checking cited local files and hashes,' but the required 'report' parameter is left opaque—there is no indication whether it is a path, a JSON string, or an identifier. The description only partially covers parameter semantics.

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: 'Validate a report model.' This distinguishes it from sibling mutators like aa_upsert_claim and from aa_checklist, though it does not explicitly name an alternative. The purpose is clear enough for an agent to select it.

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

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

The phrase 'optionally checking cited local files and hashes' implies when the check_files option should be used, but there is no explicit guidance on when to call this tool versus aa_checklist or aa_finish, nor any prerequisites. Usage is implied but not fully spelled out.

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