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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool as analyzing 'git history' and returning 'aggregate stats', which implies it's a read-only operation that processes data without modification. However, it lacks details on performance (e.g., time complexity, resource usage), error handling, or prerequisites like git repository availability. The mention of 'expensive to compute manually' hints at computational cost but isn't specific.

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 in two sentences. The first sentence clearly states the action and outputs, while the second adds context about the analysis being 'aggregate stats' and 'expensive to compute manually'. There's no unnecessary repetition or fluff, making it efficient. However, it could be slightly more front-loaded by integrating the cost hint earlier for better clarity.

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

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

Given the tool's complexity (analyzing git history with multiple outputs) and lack of annotations and output schema, the description is moderately complete. It specifies the analysis type and outputs but doesn't detail return formats, error cases, or dependencies. For a tool with no output schema, it should ideally describe the structure of returned stats (e.g., JSON format, keys), leaving gaps in contextual understanding.

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 input schema has 100% description coverage, with the single parameter 'dir' documented as 'Absolute path to the project root directory'. The description adds no additional parameter semantics beyond this, as it doesn't elaborate on path requirements, format, or constraints. With high schema coverage, the baseline score is 3, reflecting that the description doesn't compensate but also doesn't detract from the schema's information.

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's purpose: 'Run git history analysis on a codebase' specifies the verb and resource. It distinguishes from siblings by mentioning 'aggregate stats across hundreds of commits' and specific outputs like 'commit convention patterns, stale directories, and frequently changed files', which suggests a different focus than tools like 'get_code_samples' or 'save_snapshot'. However, it doesn't explicitly differentiate from 'full_analysis' or 'get_impact', which might have overlapping scopes.

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 no guidance on when to use this tool versus alternatives. It mentions that the analysis is 'expensive to compute manually', implying it's for automated processing, but doesn't specify scenarios where this tool is preferred over siblings like 'full_analysis' or 'get_impact'. There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage from context alone.

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 delivers the most important trait: managed page bodies are replaced and manual edits are overwritten. That destructive/overwrite semantics plus the config prerequisite is exactly the kind of context an agent needs. It stops short of auth/permission or failure behavior, so not a 5.

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

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

Three dense sentences with no waste: artifact list first, overwrite semantics second, precondition last. Everything is front-loaded and each sentence earns its place.

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

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

For a 6-param sync tool with no output schema, the description covers artifacts, destruction semantics, and the required prior call. It leaves out what happens on partial failure or how conflicts are handled, but nothing essential to correct invocation 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 description coverage is 100%, so the schema already documents all six parameters including defaults for indexPageTitle, featurePagePrefix, and changelogPageTitle. The description mentions the page types those parameters map to but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (sync/export) and resource (concept map to Confluence) and enumerates the exact artifacts produced: index page, one page per feature, changelog page. This distinguishes it cleanly from siblings like mason_set_confluence (which configures rather than exports).

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

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

Gives a clear precondition ('Requires `mason_set_confluence` to have been called first') that tells the agent the ordering constraint. It does not state when NOT to use it or name an alternative target, but the setup prerequisite is explicit and actionable.

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 burden; it discloses the return composition and the relative cost tradeoff versus get_snapshot ('it is cheaper'). It never explicitly states the operation is read-only or non-destructive, though 'orientation' and the preview-oriented returns strongly imply 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 tightly packed sentences with no filler; the trigger condition and the sibling routing are front-loaded ahead of the output enumeration. Every clause earns its place.

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

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

With no output schema, the description fully accounts for return values (git stats, structure, samples, test mapping) and the decision context for choosing it over get_snapshot. Nothing an agent needs to invoke it correctly 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% and the single 'dir' parameter is already documented as the absolute project root path, so the schema does the heavy lifting. The description adds no format or resolution details beyond that, matching the baseline for fully covered schemas.

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 (one-shot orientation) plus the resource (a project), and enumerates the concrete outputs: git history stats, structure with file counts, ~60-line code previews, and test-to-source mapping. It explicitly distinguishes itself from the sibling get_snapshot by condition (unmapped vs mapped project).

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 trigger ('WITHOUT a concept map', signaled by get_snapshot returning exists:false) and an explicit exclusion ('On a mapped project, prefer get_snapshot'). The alternative and the condition that selects it are both named, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the return payload composition, the agent-facing system prompt, the offset-based pagination loop, and the required interleaving with save_partial_snapshot. It omits failure modes and any permission or performance constraints, but otherwise gives strong operational context.

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

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

Three sentences, each carrying distinct value: role/return, iteration protocol, and merge-friendly naming. The critical scoping and loop instructions are front-loaded, and there is no filler.

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

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

With no output schema and no annotations, the description still communicates what is returned, how to paginate, what to call in between, and how partials integrate with the reduce step. An agent has everything needed to invoke and sequence this tool correctly.

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

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

Schema coverage is 100%, setting the baseline at 3. The description adds real meaning beyond the schema: the `files` list must be identical across every batch call of a refresh run and triggers refresh mode, and `offset` must be omitted on the first call and then fed the returned `nextOffset`. These operational semantics are not apparent from the schema alone.

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

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

States a specific role (map step of the concept-map build) and precisely what it returns (a batch of source file skeletons plus deeper-read bodies and a system prompt for deriving features and flows). This clearly distinguishes it from siblings like full_analysis, reduce_snapshot, and save_partial_snapshot.

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

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

Explicitly describes the iteration contract: call repeatedly with returned nextOffset until null, and invoke save_partial_snapshot between calls. It also names the downstream reduce step and the naming convention needed for partials to merge, leaving nothing to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behavioral traits: it reads files (implied read-only operation), provides previews limited to ~60 lines, samples multiple file types, and has a sampling approach. However, it doesn't disclose potential limitations like file size constraints, error handling, performance characteristics, or what happens with inaccessible files.

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 appropriately sized at two sentences. The first sentence efficiently conveys the core purpose and scope, while the second adds important behavioral context about file reading. There's minimal redundancy, though the phrase 'Read files natively for full content' could be slightly more precise about the relationship between previews and full content access.

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 2 parameters, 100% schema coverage, no annotations, and no output schema, the description provides adequate but incomplete context. It explains what the tool does and its sampling approach well, but doesn't describe the return format (what the previews look like structurally), error conditions, or how the sampling algorithm works in practice. The lack of output schema means the description should ideally cover return values more explicitly.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions the sampling approach and file types, but this doesn't directly enhance understanding of the 'dir' or 'count' parameters beyond their schema definitions.

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 specific action ('Get previews'), resource ('representative source files from the codebase'), and scope ('first ~60 lines'). It distinguishes from potential siblings by specifying it provides previews rather than full analysis or snapshots, with explicit mention of what types of files are included (entry points, config files, hot files, test examples, directory breadth).

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 when to use this tool: to get previews of representative files for an overview of the codebase. It mentions reading files natively for full content, implying this is for quick sampling rather than deep analysis. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses that proposals are suggestions, legacy records are unreviewed, accepted decisions are constraints subject to freshness, that map.status/diagnostics preserve missing or invalid knowledge, and that impact is capped at three unique files with directory-anchor expansion. Permission/read-only status is not stated, but the semantic and limit disclosures are substantial.

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 is front-loaded and the sentence count is reasonable for the amount of information conveyed. Some clauses are dense to the point of ambiguity (e.g., the map.status/diagnostics sentence, and referencing "map" before it is introduced), but there is little outright 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?

With no output schema and no annotations, the description must cover the return shape and it does so by enumerating the assembled categories and the freshness/constraint semantics. It is largely sufficient for an agent to call the tool correctly, though the exact result structure and read-only nature remain implicit.

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

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

Schema coverage is 100%, so dir, task, and files are already documented, including the boosting behavior of files. The description only restates "pass task and optional files" and adds the three-file impact cap, which is behavioral rather than parameter-level meaning. Baseline 3 applies when the schema does the heavy lifting.

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 ("Assemble task context") and enumerates the assembled content — decisions with rationale/approval/owner/sources/freshness, related tests, file impact, map entries. It is clear what the tool does, but it never names or contrasts with siblings like get_impact, get_snapshot, or full_analysis, which overlap heavily with its stated outputs.

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 initialization or map required. Pass task and optional files" gives prerequisites and a calling pattern, which is useful. However, there is no explicit when-to-use versus when-not, and no routing to the many sibling tools that also surface impact or decision 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 substantial work: deterministic, read-only, no prerequisite setup, and an important caveat that candidates are not proven dependencies (epistemic status of results). It still omits performance characteristics and the shape of returned results, so it falls short of fully 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?

Two dense sentences, correctly front-loaded with the purpose and then prerequisites and caveats. Every clause adds signal, though the colon-list of evidence types reads slightly stacked and 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?

For a two-parameter, required-only tool with no output schema and no annotations, the description supplies purpose, prerequisites, determinism, and a caveat about result reliability. It is close to complete, missing only any hint at result volume or how to interpret the evidence categories it mentions.

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

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

Schema coverage is 100%, so both parameters (dir, files) are already documented with examples in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('trace') and concrete resources (historical co-change partners, related tests, references), and even names the evidence types returned. It is clearly distinguishable from snapshot/decision siblings, though it never explicitly contrasts itself with the closest neighbors like get_context or full_analysis.

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

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

It tells the agent a precondition ('no initialization or concept map required') and implies read-only analysis, but gives no explicit when-to-use-this-vs-alternatives guidance against get_context or full_analysis. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full behavioral burden and does a reasonable job: it discloses the no-map fallback payload (project structure, Git signals, test pairs), the exists:false sentinel, and that downstream tools remain usable. It stops short of stating read-only/reversibility guarantees or whether the call has side effects.

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

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

Three short sentences, front-loaded with what is returned and immediately followed by the degenerate case. The trailing note about decision capture, get_context, and get_impact is somewhat tangential but still earns its place by reassuring the agent about downstream tooling.

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 annotations exist, so the description is the only source of return-shape information, and it covers both the success and the exists:false paths. It is nearly complete for a simple one-parameter read tool, missing only explicit side-effect and permission statements.

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?

Only one parameter (dir) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or path-syntax detail beyond what the schema provides, which is the baseline-3 case for a fully covered single param.

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 ('Return') and resource ('optional feature-to-file architecture map with drift and trust evidence'), which an agent can distinguish from write-side siblings like save_snapshot or generate_snapshot_batch. It does not, however, explicitly contrast itself with read-side siblings such as get_context, get_impact, or full_analysis.

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

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

'No initialization required' is a useful prerequisite, and the exists:false fallback tells the agent this call is safe even on uninitialized projects. But it never says when to prefer this over full_analysis or analyze_project, so the routing decision is left implied.

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 reasonably well: it declares status read-only, states that check writes local baselines and verification reports, and explicitly says it does not edit source or approve advisories. It also discloses the return shape (concise results plus a full report path), which is useful behavioral context.

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

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

It is appropriately short and front-loads the purpose, but the sentences are dense with undefined jargon ('host events', 'a map') that reduces clarity rather than earning its place. Structure is fine, wording is the problem.

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 2-param tool with no output schema it covers behavior and return shape adequately, but the cryptic terms leave real ambiguity about scope and preconditions. It is the minimum viable level of completeness.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantic value by explaining the two action values beyond the schema (status read-only vs check saving baselines/reports) and by clarifying the 'works without a map' condition for dir usage.

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 names two modes (inspect automation/host events, resume/check documentation repair evidence) and the action verbs, but the jargon ('observed host events', 'retained documentation repair evidence', 'a map') makes the actual purpose hard to parse. It never distinguishes itself from the many sibling mason_* 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 implied when-to-use guidance by contrasting the two enum values ('status is read-only; check saves local baselines...') and notes a precondition ('Works without a map'). However, it offers no explicit guidance on when to pick this tool over siblings like mason_check_drift or verify_snapshot.

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 determinism (git + filesystem, no LLM), enumerates exactly what is returned (stale features/flows, new files, ghost files, renames), and defines all three recommendation outcomes with their follow-up actions.

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

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

Front-loads the core purpose, then packs behavior, return shape, and usage timing into tight sentences with no filler. The recommendation enum is inline and self-explaining.

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?

Although no output schema exists, the description fully explains the return values and recommendation semantics, so an agent has everything needed to call and interpret the tool. Nothing material is missing for a single-param diagnostic.

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 'dir' parameter is documented there, so the description adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (check drift) and resource (the concept map) with a clear scope (drift relative to HEAD). An agent can distinguish it from siblings like verify_snapshot or get_snapshot 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?

Gives explicit timing guidance ('before trusting the map in a long session', 'periodically to keep the map and synced wikis fresh') and routes the incremental case to save_snapshot. It stops short of naming when to avoid the tool, but the when-to-use context is clear and actionable.

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 a good job: it discloses the two-file write behavior, the local-vs-shared split, and idempotency semantics ('repeated calls preserve the original setup time and existing settings'). It does not mention error behavior, permissions, or what happens if the files are missing, which keeps it short of a 5.

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

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

Three dense sentences that front-load the primary action and file targets, then cover the optional marker semantics and parameter behavior. Every sentence carries information, though the third sentence overlaps with the schema description of confluenceConfigured.

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

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

For a two-parameter marker-writing tool with no output schema and no annotations, the description covers destination files, idempotency, and conditional parameter behavior well. Only edge cases (write failures, missing directories, concurrent runs) are absent, which is a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented, including 'omit to preserve the existing value' for confluenceConfigured. The description restates that preservation rule rather than adding new 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?

States a concrete verb and resource: recording assistant instruction setup as a completion marker, and names the exact files written (.mason/local/project.json and .mason/config.json). It is clear what the tool does, though it never names a sibling (e.g. mason_init or mason_set_confluence) to distinguish itself 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 line 'Other tools work without this marker' implies this call is optional and not a prerequisite for the rest of the workflow, which is useful routing context. However, it gives no explicit guidance on when to prefer this over mason_init or when to call it relative to the other tools, leaving the user to infer timing.

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 well: it discloses that quickstart/map are read-only and deterministic, that setup mutates MCP config, instructions and lifecycle hooks while retaining original audit evidence, that evidence imports do not execute check commands, and that repeat calls refresh findings. It omits permission/auth requirements and error behavior, so not a 5.

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

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

Front-loaded with the payoff ('Inspect this project now: returns ...'), then mode behavior and parameter context. Five dense sentences, each carrying information, though the mid-paragraph jump between setup semantics and optional-parameter notes makes it slightly harder to scan.

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 5-parameter, multi-mode tool with no output schema and no annotations, the description covers return contents, read-only vs mutating modes, and evidence import behavior. It does not spell out the absolute-path requirement for dir or the failure mode when setup is invoked without an unambiguous host, leaving modest 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 100%, so the schema already documents dir, base, host, mode, and evidence in detail; the description mostly restates host selects codex/claude, base picks the review comparison, and evidence imports CI manifests. It adds the useful nuance that findings refresh on repeat calls but contributes little parameter meaning beyond the schema.

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

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

States a concrete verb (inspect) and enumerates exactly what comes back: documentation audit findings, committed-diff review findings, decision/map status, and a quickstart playbook. It also distinguishes its three modes (quickstart/map/setup) so an agent can tell what the call produces. It does not explicitly position itself against siblings like full_analysis or mason_complete_init, 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?

Gives clear mode-level guidance: quickstart and map are read-only and deterministic, and setup should be used 'only when the user requests setup'. This is an explicit when/when-not rule. It stops short of naming sibling tools as alternatives, so it is not a 5.

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

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

With no annotations, the description carries the disclosure burden and does well: it states the output categories for verify (resolved, unresolved, review-required, unverified, new findings), that suppressed advisories stay unresolved, that the tool never edits docs or approves decisions, and that no map is required. Remaining gaps are permissions and write-scope details for the baseline file that prepare saves.

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 tool's purpose, then the mode-by-mode flow, then constraints and scope exclusions. Four dense sentences, none of them 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 two-mode tool with no output schema and no annotations, the description covers the workflow, the verify result categories, and what the tool will not do. It is nearly complete; only the on-disk effect of prepare (where/how the baseline is stored) is left unspecified.

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 75%, so the schema already documents dir, checks, and baselinePath. The description reinforces the action/baselinePath relationship ('verify reads that baseline', baselinePath required for verify) but adds little syntax or format detail beyond what the schema states.

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

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

States a specific verb and resource ('Track documentation repairs against original audit evidence') and distinguishes the two modes: prepare saves a baseline and returns a work order, verify reads it and reports findings. It does not explicitly name sibling tools such as mason_check_drift or verify_snapshot, so sibling differentiation is left implicit.

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 prepare-then-verify workflow is spelled out with the condition that selects each action, and the negative scope ('Does not edit documentation or approve decisions') tells the agent when not to expect this tool to act. No named alternative tool is offered, so it stops short of full routing guidance.

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 well: it discloses the persistence location (~/.mason/config.json), the security caveat about tokens appearing in chat history, and the validation-then-persist behavior. It does not describe failure modes for invalid credentials or whether a re-run overwrites existing config.

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

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

Front-loaded with the core action, then numbered steps and a warning. Every sentence serves a purpose, though the prose is dense and the security warning could be marginally tighter.

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 annotations, yet the description covers what the first call returns (list of spaces), what the second call does (persist), where state is stored, and a user-facing warning. An agent has everything needed to drive the flow 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 baseline is 3, but the description adds cross-parameter workflow meaning: which params must be identical across calls and that spaceKey presence toggles list-vs-persist mode. parentPageId is left to the schema alone, so it is not a full 5.

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 ('Configure Confluence credentials') and immediately distinguishes itself from the sibling export_to_confluence by being a setup/credential tool. The two-step flow makes the operation's shape 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?

Gives explicit when-to-call guidance: first call without spaceKey to validate and list spaces, second call with the same credentials plus spaceKey to persist. This is a precise conditional branching instruction no agent could infer otherwise.

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, so the description carries the full behavioral burden. It usefully discloses that the tool returns every partial snapshot plus a system prompt, and that save_snapshot clears partials, but it doesn't state whether reduce_snapshot itself has side effects, requires permissions, or what the partial payload 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?

Four focused sentences, front-loaded with the tool's role, then return shape, merge rules, and next step. Some procedural detail could be trimmed, but each sentence carries actionable information.

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

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

With no output schema and no annotations, the description does a good job explaining the return value (partials + merge prompt) and the required save_snapshot follow-up. Missing details about partial structure or permissions are minor given the tool's narrow role.

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% for the single 'dir' parameter, so the description needn't restate it. The description adds no parameter syntax or format detail beyond the schema's absolute path description.

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

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

States a specific verb and resource ('Reduce step of the concept-map build') and clarifies it returns partials plus a merge prompt, distinguishing it from the downstream save_snapshot step. It doesn't explicitly differentiate from get_snapshot, but the reduce/merge framing 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?

Explains the merge rules and the required follow-up call to save_snapshot, which implies when this step belongs in the pipeline. However, there is no explicit when-to-use/when-not guidance or comparison against sibling snapshot tools beyond the next-step reference.

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 meaningful work: records are persisted in Git, relevant changes reopen reviews, and recorded identities are assertions rather than authenticated approvals. That last point is an important security caveat an agent could not infer from the schema. It omits error behavior, idempotency, and any permission requirements, so it is not exhaustive.

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

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

Four sentences, front-loaded with the core operation before the routing and lifecycle caveats. Every clause carries signal (sibling routing, reopen semantics, auth caveat), though the first sentence is overpacked and would read better split.

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 7-parameter, no-annotation, no-output-schema tool, the description explains the concept and some lifecycle behavior but leaves required-parameter semantics (findingId, baselinePath) and the prepare-vs-record workflow unclear. Given the low schema coverage, it should carry more of that load.

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 only 14% (just 'dir'), so the schema does not do the heavy lifting. The description names reviewToken, reviewer, note, and the three outcome actions, which maps to the action enum and three optional params, but the three required params (dir, baselinePath, findingId) are never explained and no format or validation details are added.

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

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

The description names a specific verb pair (prepare/record) and a specific resource (a repair advisory review, with addressed/inapplicable/deferred outcomes), and it explicitly differentiates from the sibling review_decision. The prose is dense and the underlying artifact ('original repair advisory', reviewToken lifecycle) is only loosely defined, 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 routes decision findings to review_decision and states this tool never approves decisions, giving a clear when-not condition and naming the alternative. It also notes that relevant changes reopen reviews while unrelated commits preserve them. It does not say when to use the prepare action versus recording an outcome, so it stops short of fully explicit guidance.

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 enumerates what prepare returns, states that acceptance replaces the operative revision and retirement withdraws the entire record including its proposal, notes that changed records or code invalidate the token, and warns that identities/approvals are recorded assertions rather than authenticated proof. This is exactly the behavioral context an agent needs before mutating a record.

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 prepare-phase return contents and the verdict workflow are front-loaded, and each sentence carries distinct information (returns, consequences, prerequisites, token invalidation, trust caveat). It is dense and somewhat long, but nearly every clause earns its place; only minor tightening is possible.

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 tool with no output schema and no annotations, the description covers the full lifecycle: what prepare yields, how verdicts are recorded, the prerequisites for acceptance, the destructive effect of retirement, token staleness rules, and the trust model. Nothing essential for correct invocation 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 baseline is 3, but the description adds real meaning: the reviewToken is tied to the prepared review and rejects stale record/code revisions, the note is the rationale required for a verdict, the reviewer must be the actual identity and never invented, and action distinguishes the read-only prepare from authorized verdicts. This goes beyond the schema's field 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 states a specific verb+resource ('prepare a decision review' / 'record accept, reaffirm, or retire') and cleanly separates the read-only prepare mode from the mutating verdict modes. It is unambiguous about what the tool does. It does not, however, differentiate itself from siblings like review_advisory or save_decision, which an agent must still infer.

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 a clear workflow: prepare first (read-only) to obtain the token, then record a verdict using that token, reviewer, and reason, and it lists the conditions for acceptance (owner, source, readable Git HEAD, committed anchor changes). It stops short of naming when to choose this over review_advisory or how verdict actions relate to save_decision, so exclusions and alternatives are absent.

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 richly: it discloses that changes create a pending proposal while the last accepted revision stays operative, that unchanged content does not re-verify or refresh, that content history is preserved, and that a proposal cannot supersede an operative accepted record. These are non-obvious write semantics an agent could not infer.

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

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

Front-loaded with the purpose and dense with meaningful rules; nearly every sentence earns its place. It is long and somewhat repetitive on the id/supersede flow, which the schema already covers, keeping it short of a 5.

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

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

For an 11-parameter, no-annotation, no-output-schema mutation tool, the description covers write behavior, history, and the review workflow thoroughly. Minor gaps remain around duplicate/force handling and the review handoff lifecycle, but it is largely complete.

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 91%, so parameters are already well documented (id, body, sources, supersedes all carry detailed schema text). The description restates id and actor behavior but adds little syntax or format meaning beyond the schema, so the baseline of 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 opening sentence gives a specific verb+resource ('Capture or revise a decision proposal') and enumerates the accompanying content (rationale, anchors, owner, sources, actor). An agent can distinguish this from siblings like review_decision and get_context without opening a 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?

Explicit routing rules: compare before saving, pass an existing id when evidence changes the same lesson, create new records for genuinely distinct lessons, skip unchanged restatements, and use review_decision for authorized acceptance. Both when-to-use and the alternative tool are named.

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 disclose the key behavioral traits: a persistence side effect, the destination path ('.mason/partial-snapshots/'), and the fact that partials are merged later in reduce. It does not cover overwrite/re-run semantics or error behavior if called twice for the same batch.

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

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

Three short sentences, zero filler, with the core action and cadence front-loaded ahead of the storage/merge 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?

For a five-parameter mutation with nested objects, no output schema, and no annotations, the description adequately covers what the tool does, when to call it, and where the data goes. It leaves the return value and re-invocation behavior unspecified, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the nested features/flows structure. The description adds only the sourcing of batchId from generate_snapshot_batch, which the schema description also states. 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?

States a specific verb and resource ('Persist the partial concept map') and scopes it precisely to 'one batch'. The sibling relationship to the full-snapshot flow is implied by 'partial' and 'merged in the reduce step', which separates it from save_snapshot.

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 cadence ('Call this once per batch') and tells the agent where the batchId value originates ('from the generate_snapshot_batch response'). It positions the tool in the generate -> save -> reduce pipeline without naming explicit when-not conditions or alternate siblings by 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?

With no annotations, the description has to carry the full behavioral burden, and it partially does: it discloses persistence across conversations and that no API key is needed. However, it omits critical save semantics — whether the map is merged or replaced, and how the removeFlows/removeFeatures deletions (documented only in the schema) interact with existing data.

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

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

Four short sentences, front-loaded with what the tool does before the persistence and access notes. Each sentence carries signal, though the closing 'you are the LLM generating the map' is slightly rhetorical rather than operational.

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 5-parameter tool with nested objects, three required fields, and no output schema, the description explains the data model adequately but leaves the merge/replace behavior and the effect of removeFlows/removeFeatures unstated. An agent would still have to infer how incremental saves behave.

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 five parameters in detail, including the feature/flow structure and the type enum. The description adds the conceptual meaning ('maps feature names and data flows to the files that implement them') but no field-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Save a concept-to-files map as a persistent project snapshot') and explains the payload semantics (feature names and data flows mapped to implementing files). It does not, however, distinguish itself from the very similar sibling save_partial_snapshot, leaving full-map vs. partial-map selection ambiguous.

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 implies a workflow by pointing to get_snapshot for future retrieval, so its role as the write side of a snapshot pair is inferable. But it never says when to prefer this over save_partial_snapshot or generate_snapshot_batch, and gives no exclusion guidance for incremental updates.

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 entire burden and does well: it discloses that ok entries are stamped verifiedAt, that failures are flagged verificationFailed with the supplied note, and that failed state propagates to three named downstream tools until corrected. It is silent on permissions, idempotency/overwrite behavior when a verdict is resaved, and whether clearing a failure requires an ok entry.

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

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

Three tight sentences, front-loaded with the core action, then the state effects, then the one constraint. Every sentence carries information an agent needs; there is no filler or restatement of the tool name.

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

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

There is no output schema, so the description must convey consequences — and it does, naming the exact state flags applied and the tools where failures resurface. Combined with the fully documented input schema, an agent has enough to call it correctly; the only gap is the semantics of overwriting or clearing a prior verdict.

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

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

Schema description coverage is 100%, so the schema already documents dir, verdicts, and the ok/note shape including that note is required when ok is false. The description's only parameter-adjacent statement ('Verdict notes are required for failures') restates what the schema says, adding no new syntax or format information. 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 opens with a specific verb+resource pair ('Record verify_snapshot verdicts') that clearly positions this as the persistence counterpart to the sibling verify_snapshot tool, which computes those verdicts. It does not spell out the compute-vs-record split explicitly, but the phrasing is enough for an agent to distinguish the two.

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 conveys the workflow context (this is where verify_snapshot verdicts get stored) and, more usefully, what happens afterwards — failures surface in get_context, get_snapshot, and mason_check_drift until corrected. There is no explicit 'when not to use' or exclusion statement, and no mention of re-verification cadence, so it falls short of a full 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 does well: it discloses the sampling policy (never-verified and least-recently-verified first), what is returned (entries plus skeletons of their claimed files), and the intended follow-up write via save_verification. It does not state permissions or whether the sample is deterministic in size beyond the default, but the behavioral picture is substantially richer than the 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?

Three dense sentences, front-loaded with the differentiator, then the return contract, then the call-to-action. Every clause carries distinct information and none is redundant.

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

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

For a two-parameter sampling tool with no output schema and no annotations, the description covers what is returned, in what order, why it is returned that way, and what to do with the result. Nothing an agent needs to invoke it correctly 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 description coverage is 100% and both parameters are documented there, including the default of 5 for 'sample'. The description adds no 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?

States a specific verb (spot-check) and resource (the concept map's correctness), and immediately distinguishes itself from the sibling mason_check_drift with the parenthetical 'drift checks freshness; this checks entries were right to begin with.' An agent can separate the two without opening either schema.

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

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

Gives explicit trigger conditions ('Run periodically, or after an automated refresh wrote entries no human reviewed') and names the follow-up tool (save_verification) plus the alternative (drift checks) with the condition that selects each.

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