innoslate_lint_requirements

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

Annotations already declare this a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds real behavioral value beyond that by defining the errors-vs-warnings outcome model and what the caller should do with each, which is not encoded in any structured field.

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

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

The purpose and the pre-apply condition are front-loaded in the first and last lines. Parameter details are packed inline somewhat telegraphically (nested curly-brace notation), but every sentence contributes 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, the description should fully define the return shape; it gestures at errors vs warnings but does not describe the result structure an agent will parse. For a lint tool with four parameters and no required fields, the coverage of inputs is good but output expectations remain thin.

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 carries the burden and largely does: it documents the items object shape (number, name, text, rationale?), the document selector (id/number/name), and extra_banned with a concrete regex example. Only project_url goes undocumented, which is a minor, self-evident 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: 'Check requirement wording' as a pre-write lint step, and notes it can also target an existing document. It differentiates by timing relative to writing and names the downstream sibling innoslate_apply, though it does not distinguish itself from the similarly-named innoslate_quality_check.

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 usage context ('before writing it' and 'before innoslate_apply') and an actionable rule (errors must be fixed, warnings need a human). It offers no explicit comparison or exclusion versus the overlapping innoslate_quality_check sibling, so it stops short of full when/when-not guidance.

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