Create or update Paperclip issue document

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

Annotations already signal non-idempotent and destructive behavior, so the description does not need to repeat those. It adds useful behavioral detail beyond annotations: updates normally require base_revision_id from a fresh read, and the response is only a compact acknowledgement rather than full content. Nothing in the description contradicts the annotations.

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 short sentences with no filler. The primary action is front-loaded, the critical prerequisite is stated next, and the return behavior is summarized last. Every sentence 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?

The description covers the essential operation, the base_revision_id prerequisite, and the acknowledgement response. However, with six parameters and no schema-level descriptions, the lack of guidance on key semantics, body usage, and change_summary leaves the tool only partially specified for reliable invocation.

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 carries the burden of explaining parameters, but it only clarifies base_revision_id. It does not explain the meaning or relationship of key, body, title, issue_id, or change_summary beyond their names and types, leaving significant ambiguity for an agent choosing values.

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 action on a specific resource: 'Create a document or append a new revision' for a Paperclip issue document. It also distinguishes itself from read tools by noting the update precondition and the compact acknowledgement, making it clearly the write counterpart to paperclip_document.

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 clear usage context: use this tool to create a document or append a revision, and when updating, first obtain base_revision_id from a fresh paperclip_document result. It does not explicitly list exclusions or other sibling alternatives, but the workflow guidance is sufficient for selecting this tool over document read tools.

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