lint_repair_prepare

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

Adds context beyond annotations: artifacts are private and immutable, canonical data is never mutated, lost responses may already have created artifacts, paging is byte-bounded, and the tool is local stdio only. These are meaningful mutation and retry semantics consistent with readOnlyHint=false, idempotentHint=false, and destructiveHint=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?

The description is front-loaded with purpose and then organized by mode, behavior, retry caveat, and environment constraint. Every sentence carries operational information for a complex six-parameter tool.

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

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

Covers the full calling model for a complex tool: opening a plan, paging with plan_id/plan_digest/offset, preparing a choice, artifact behavior, retry risk, and local-only constraint. No output schema exists, yet the description still explains the relevant returned fields and pagination handling.

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 schema coverage at 100%, the schema already documents each parameter, but the description adds mode-level semantics: which parameter combinations open versus page versus prepare, what next_offset means, and that choice turns exactly one Review Item into an approval-gated manifest. It also describes the return shape, including source_reports and page entries, despite no output schema.

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

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

States a specific verb and resource: plan or prepare lint repairs from cached reports for the exact lint_scope, explicitly excluding pasted reports. It also distinguishes its behavior from the apply step by saying it produces approval-gated manifests and never mutates canonical data.

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 branch conditions: only lint_scope opens a new plan, plan_id plus plan_digest plus offset pages an existing plan, and choice prepares exactly one Review Item. It also warns not to retry a lost plan response and notes the extra requirement for reclassification.

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