patchLicense

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

Annotations already provide idempotentHint, readOnlyHint=false, and destructiveHint=false, and the description goes beyond them by spelling out the idempotency end-state guarantee. It also explains the dry_run behavior: previewing the exact request, redacting auth, summarizing binaries, and returning the preview as an error-flagged result. No annotation contradiction.

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 tool purpose and caveats are front-loaded in a compact first paragraph. However, the final sentence about tools with a typed output schema is not relevant here because this tool has no output schema, adding noise rather than value. The rest is efficient, but that misplaced conditional keeps it from scoring higher.

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 with a fully documented nested requestBody and strong annotations, the description covers the platform limitation, idempotency semantics, and dry-run preview workflow. It does not document permissions or response shape, but with no output schema those omissions are acceptable. The only notable gap is the irrelevant output-schema warning, which is minor.

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 100%, with both dry_run and requestBody already documented in the input schema. The description reinforces the dry_run parameter but adds no semantic meaning beyond the schema, so the baseline 3 applies.

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?

Opens with 'Updates the product License,' a specific verb and resource. 'Product License' distinguishes it from sibling tools like patchLicenseAssignments and setLicense, which operate on different license resources. The intended target is unambiguous.

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 a clear exclusion: not supported by cloud-based Polarion, telling the agent when the tool cannot be used. It also prescribes a dry_run-first workflow to preview the request safely. It does not name alternative tools for other license operations, but the main usage context is explicit.

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