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

Beyond the annotations (which only state idempotent/not-destructive/not-read-only), the description discloses the resulting state ('pending verification'), what happens on re-audit (closes if gone, reopens if not), that a human can verify in the dashboard, that ref is surfaced to a reviewer, and the crucial scoping fact that this changes Loomaly's work item and never the website.

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, front-loaded with the action and its scope options, then the lifecycle, then the boundary of the side effect. No filler and no repetition of schema fields.

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 mutation tool with no output schema, the description adequately covers the post-call state and the non-destructive boundary, and annotations cover safety. It omits error/validation behavior (e.g., what happens with an invalid combination of targeting parameters), which is a minor remaining 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?

With only 38% schema coverage, the description carries most of the parameter burden: it defines the three valid targeting combinations covering findingId, ruleId, pathTemplate, sampleUrl, and allPages, and explains that ref holds the commit/PR URL shown to the reviewer. It adds little on siteId or note, but compensates well for most of the 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?

The description states a specific verb ('marks ... as fixed') and resource ('a finding / group / whole rule'), and it enumerates the exact parameter combinations that select each scope (findingId, ruleId+pathTemplate, ruleId+sampleUrl, ruleId+allPages). An agent can distinguish this mutation from siblings like verify, ignore_finding, and verify_status without opening the 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?

It gives clear usage context: only the change (commit or open PR) is needed, not a deployed page, and it explains the pending-verification lifecycle. It does not, however, name alternative tools (e.g., ignore_finding or the dashboard verify path) with explicit when-to-use conditions, so routing between siblings is still partly inferred.

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