patterncopy stamp

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

Annotations only give readOnly/openWorld/idempotent/destructive flags; the description adds the substantive behavior an agent needs: consent:true is mandatory, the file and options traverse RapidAPI to a NAS service, the call consumes the subscribed plan allowance, there are no automatic retries, originals are preserved and verified output is written as new local files. It also warns that returned artifacts contain untrusted data, which is valuable for an openWorldHint 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 core action is front-loaded in the first sentence, followed by operational constraints and safety notes. Every sentence carries information, though the middle sentence about layers and geometry plus review is slightly dense and the block could be separated into tighter clauses rather than one long run-on.

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, open-world mutation with no output schema, the description covers consent gating, transfer path, plan consumption, retry behavior, file preservation and where results land. It leaves out the numeric bounds/defaults and the exact shape of the returned artifact, which is the main 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?

Schema description coverage is only 17% (just the consent field), so the description carries extra burden. It partly compensates by naming the documented options (corner/position, font size, margin) and constraining input ('one line', 'left-to-right', 'PDF up to 20 MiB'), but it omits the actual ranges and defaults (margin 6-72, font_size 6-14) and never explains the 'text' or 'file' parameter format beyond size.

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 ('Add one line of supported left-to-right text to every page of a supported PDF') with concrete limits (20 MiB, corner/font/margin options). It is clearly distinct from the sibling patterncopy_inspect, but it never names a sibling or explicitly contrasts with one, so it stops short of a 5.

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?

Usage context is implied via 'reserve clear space on every page and review the result' and 'One request, no automatic retries', which tells the agent to call deliberately. However, there is no explicit when-to-use/when-not or routing to alternatives such as patterncopy_inspect for inspection or patterncopy for other operations.

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