mason_automation

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 declares status read-only and states that check saves baselines and reports 'without editing source, approving advisories or consuming pending completion notices' — valuable negative-side-effect disclosure. It also notes a return shape ('full report path'), though it omits permissions and idempotency details.

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 two sentences are front-loaded with the inspection targets and avoid obvious padding, but the second sentence piles several negated caveats together and the trailing 'Works without a map' is an unexplained fragment. Some jargon could be trimmed without loss.

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, two-mode tool with no output schema and no annotations, the description adequately covers modes, side-effect profile, and return hint. It is nevertheless thin on how each mode relates to the numerous sibling tools and leaves cryptic phrases undefined, so it is complete only at a minimum-viable level.

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 in the schema, setting the baseline at 3. The description adds a behavioral gloss on the two action values in prose, but no format or semantics beyond what the enum and dir descriptions already provide.

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 two specific verbs ('Inspect' for status, 'check' for the second mode) and enumerates resources (installed automation, host events, decision records, documentation findings). However, the resource list is dense domain jargon ('notification baseline', 'works without a map') and the tool bundles two distinct actions, so an outside agent gets only an approximate sense of purpose. No sibling tool is named or contrasted.

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 implies when each mode applies ('status is read-only' vs 'check saves local baselines and verification reports'), which gives an agent a rough basis for choosing an action. But no explicit alternatives are named (e.g., mason_check_drift, review_advisory) and no conditions for when NOT to use this tool are given, so routing against the many siblings is left to inference.

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