fossa_unblock_package

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

The description goes far beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true). It discloses critical behavior: the tool rewrites the entire rule set, has no precondition for concurrency safety, may silently undo concurrent edits, reports surviving rules in `data.rules_sent`, preserves all non-block rules, and relies on an undocumented endpoint that may change without notice. This is exceptional transparency for a destructive mutation tool.

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 front-loaded: the first sentence states the core purpose. Every subsequent sentence adds critical safety or behavioral information. It avoids filler and uses clear formatting with bold warnings. Length is appropriate for the tool's complexity and risk profile.

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 (destructive mutation, concurrency risk, undocumented endpoint), the description covers all essential aspects: what it does, when it does nothing, what data it reports, and its stability caveat. An output schema exists (has output schema: true), so return values are presumably documented there, but the description still covers the non-obvious 'data.rules_sent' field. This is complete for an agent to use effectively.

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 must compensate. The description explains that 'package_locator' is the package whose block is being removed, and 'policy_id' identifies the policy. It also explains the behavior of the rule removal, which adds meaning beyond the raw parameter names. However, it does not specify formats, examples, or how to obtain valid values. With only two simple parameters, the description provides enough context to understand their roles, but a bit more detail on expected formats would be helpful. Baseline 3 is appropriate given the low coverage and the description's partial compensation.

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: 'Remove a package's blocked-dependency rule from one FOSSA quality policy.' It clearly identifies the action (unblock) and the target (a specific package's blocked rule in a policy). This distinguishes it from siblings like fossa_block_package and other policy tools, even without explicitly naming them.

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 explicitly warns about the destructive nature and required environment flags: 'WRITES TO FOSSA, DESTRUCTIVELY. Requires FOSSA_ALLOW_WRITES=true and FOSSA_ALLOW_DESTRUCTIVE=true.' It also provides a clear condition for when the tool performs no operation: 'If the policy carries no such block, nothing is sent and the policy is left alone.' This gives the agent actionable guidance on when to use (and avoid) this tool, including the concurrency caveat.

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