fossa_assign_package_labels

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

The description contradicts the idempotentHint=false annotation. It states 'Additive: existing assignments are left alone and duplicates are ignored,' which implies that repeated identical calls would have no additional effect (idempotent). This directly conflicts with the annotation, so transparency scores 1 despite the useful write requirement disclosure.

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 four dense sentences with no fluff. It front-loads the purpose, then covers write safety, behavioral nuance, and key parameter constraints. Everything earns its place.

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 6-parameter write operation with an output schema, the description covers purpose, prerequisites (FOSSA_ALLOW_WRITES), side-effect behavior, and the critical parameter constraints. It is complete enough for an agent to invoke correctly, despite the annotation contradiction which is separately flagged.

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 description coverage at 0%, the description compensates effectively. It explains the semantics of package_version vs. apply_to_all_versions, the scope_id omission rule for org scope, and implies label_ids must refer to existing labels. This adds substantial meaning beyond the bare 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?

The description clearly states the action: 'Assign one or more existing package labels to a single package.' This distinguishes it from siblings like bulk_assign_package_label and set_package_label_assignments by specifying 'single package' and 'existing labels'.

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 gives important usage constraints, such as the exclusivity requirement between package_version and apply_to_all_versions, and the conditional omission of scope_id for org scope. However, it does not explicitly mention alternatives or when-not-to-use scenarios, so it stops short of a 5.

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