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

Annotations already provide readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable non-obvious output behavior: results are returned as Markdown inline below a configured token threshold, otherwise only as a new immutable snapshot path. This goes beyond the annotations and schema without contradicting them.

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, each earning its place: the first states the core operation, the second describes the output contract, and the third constrains the optional parameter. There is no filler, repetition, or ambiguity.

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 two-parameter read-only tool with no output schema, the description covers purpose, list-vs-fetch selection, and return behavior. It could add notes on error handling or how to consume the snapshot path, but these are minor given the tool's low complexity and strong annotations.

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?

The schema already documents id fully as 'Agent UUID or company shortname' and says to omit it for the roster. all_fields has no schema description, and the description adds a useful decision rule: use it only when compact agent fields are insufficient. This compensates for the 50% schema coverage, though it does not enumerate exactly which fields all_fields adds.

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 and resource: 'List company agents, or fetch one agent when id is supplied.' It clearly distinguishes the two calling modes (list vs. single fetch) and matches the title, making the tool's purpose immediately identifiable among siblings.

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 conditional guidance: omit id to list the company roster, supply id to fetch a single agent, and use all_fields=true only when compact fields are insufficient. It does not explicitly name alternative tools or exclusion conditions, but the read-only scope and parameter conditions are sufficiently clear.

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

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

The description usefully discloses that the tool returns only a compact acknowledgement and does not inject the full created comment response into context, which is valuable since there is no output schema. Combined with annotations that already signal a non-idempotent, non-destructive operation, this gives good behavioral transparency.

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?

Two short sentences, each earning its place: the first states the purpose, the second sets expectations about the response. No redundancy or filler.

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 core action and response behavior are covered, which is important given the lack of an output schema. However, the description omits the semantics of reopen, does not mention any workflow prerequisites, and leaves the relationship to sibling comment/issue tools implicit.

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%, and the description does not explain the parameters. 'Add a comment' implies that body is the comment text and issue_id identifies the target, but the reopen boolean is left entirely unexplained, and no parameter-level detail is provided.

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 clear action ('Add a comment') and a specific resource ('authoritative Paperclip state'), so an agent can tell this is a write operation for comments. It does not explicitly contrast with sibling tools like paperclip_comments or paperclip_issue_update, so it misses the top score.

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 intended use is implied: use this when you need to add a comment to Paperclip state. However, there is no explicit guidance about when to prefer this over paperclip_issue_update or paperclip_comments, nor any mention of prerequisites such as issue checkout.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, the description discloses important behavior: results come back either inline or as a new immutable snapshot path, and comments are not automatically fresh. This adds meaningful operational context.

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 tight sentences with no filler. The main verb and resource are front-loaded, and each sentence adds distinct useful guidance.

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 read-only fetch tool with no output schema, the description covers the core return behavior (Markdown, inline vs. snapshot path) and incremental fetching. It leaves some parameter semantics unexplained, but the essential invocation context is sufficiently communicated.

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 for explaining parameters. It explains after_comment_id, but provides no guidance for issue_id, limit, order, or all_fields. Most parameter semantics remain undocumented.

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 a specific action ('Fetch issue comments as Markdown') and identifies the exact resource (issue comments). It distinguishes this read operation from the sibling write tool paperclip_comment_add without ambiguity.

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 practical usage context, especially the guidance to use after_comment_id for deltas instead of replaying the full thread, and to call again for fresh comments. It does not explicitly name alternative tools or exclusion cases, but the read-vs-write distinction is implied by the title and sibling set.

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

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

The description goes beyond the readOnly and idempotent annotations by explaining the conditional return behavior: Markdown inline when within token threshold, otherwise an immutable snapshot path. This is valuable behavioral detail that the annotations do not convey.

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 compact and front-loaded: the first sentence states the core read action, and the second sentence adds the return behavior. Every sentence earns its place with no filler.

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 zero-parameter tool, the description sufficiently explains the two return modes and the no-API-call nature. A small gap is that it does not enumerate what the 'run/wake environment' actually contains, though the Markdown return is described as LLM-friendly.

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?

The tool has zero parameters, so there is no parameter semantics burden on the description. The schema is fully covered vacuously, and the description does not need to explain parameter meaning.

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 tool 'Read the current Paperclip run/wake environment', which is a specific verb and resource. It also distinguishes the tool by noting it works 'without an API call', but it does not explicitly differentiate it from the similar sibling paperclip_heartbeat_context.

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 phrase 'without an API call' implies this should be used when a lightweight, low-cost read of the current runtime environment is needed. However, the description does not explicitly state when to prefer this over siblings like paperclip_heartbeat_context or paperclip_raw, nor does it provide exclusions.

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

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

The description goes beyond the annotations by explaining that results are inline below a token threshold and otherwise returned as an immutable snapshot path. It also clarifies annotation loading behavior and the all_fields constraint, giving useful behavioral detail beyond readOnlyHint, openWorldHint, and idempotentHint.

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 three dense sentences with no filler: purpose and output format first, result-delivery behavior second, and parameter semantics third. Each 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 fetch semantics, Markdown output, snapshot-vs-inline behavior, and important boolean parameters, which is strong for a read tool with no output schema. The main gap is the lack of routing guidance against sibling read tools and the undocumented meaning of issue_id/key.

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 0% schema description coverage, the description partially compensates by explaining include_annotations, include_annotation_comments, and all_fields. However, the required parameters issue_id and key receive no semantic explanation beyond their names and schema constraints.

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 opens with 'Fetch one issue document as Markdown,' naming a specific verb, resource, and output format. It reads as a singular read operation and is clearly distinguishable from siblings like paperclip_document_put and paperclip_issues.

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?

There is no explicit guidance about when to use this tool versus paperclip_raw, paperclip_documents, or paperclip_issue. The only hint is the phrase 'one issue document,' which implies usage but does not rule out alternatives or provide selection criteria.

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

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.

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

Beyond annotations readOnlyHint, openWorldHint, and idempotentHint, the description discloses substantive behavior: results are inline below a token threshold and otherwise become an immutable snapshot path, and default output omits document bodies. This gives the agent useful operational expectations without contradicting 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 tight sentences, each earning its place: purpose, output behavior, and parameter/alternative guidance. The most important information is front-loaded, with no filler or restatement of the schema.

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 simple two-parameter, read-only listing tool with no output schema, the description covers purpose, output format, truncation behavior, default field omission, and the alternative for getting full bodies. Nothing essential for correct invocation is missing.

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. It does for all_fields by explaining that true returns every returned field. issue_id is not explained in prose, but its meaning is clear from the tool purpose and the required schema field, so the gap is minor.

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 opens with a specific verb and resource: 'List issue documents as compact Markdown.' It clearly identifies the tool's output format and scope, and distinguishes it from the sibling paperclip_document by noting that the singular tool is for fetching a document body.

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 tells the agent when to use an alternative: if a document body is needed, call paperclip_document, or set all_fields=true. It also explains the inline-vs-snapshot result behavior, which guides the agent on what to expect for large result sets.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses key conditional behavior: inline Markdown when under the token threshold, otherwise only a NEW immutable snapshot path, and the scope limitation of all_fields=true. This materially helps an agent predict the response shape.

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 compact sentences, with the endpoint and core behavior front-loaded before the usage guidance and all_fields caveat. No wasted words; every sentence contributes to selection or invocation.

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 two possible return behaviors and gives a concrete use case, which is sufficient given the simple schema and read-only annotations. It could be more complete by explaining what a snapshot path is or naming the alternative for larger context, but it is not critically incomplete.

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%, so the schema already documents both id and all_fields. The description repeats the all_fields scope restriction but adds no new parameter-level detail beyond what the schema provides.

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 names a specific verb and resource ('Fetch GET /api/issues/:id/heartbeat-context explicitly') and clarifies that it returns the smaller wake/execution context. This distinguishes it from siblings like paperclip_context or paperclip_raw by scope and intent.

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?

It gives an explicit usage condition: 'Use this when the smaller wake/execution context is what you want.' It does not name the specific alternative to use for larger context, so exclusions and when-not-to-use are only implied rather than stated.

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

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

Beyond readOnlyHint/openWorldHint/idempotentHint, the description discloses the conditional return behavior: Markdown inline when under token threshold, otherwise only a new immutable snapshot path. This is useful trait information that is not present in the annotations or schema.

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 concise sentences front-load the purpose, then explain the output condition and the polling cue. Every sentence adds distinct information with no redundancy or filler.

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 zero-parameter tool with no output schema, the description covers the important return cases (inline Markdown vs snapshot path) and when to call again. The configured threshold and snapshot concept are not detailed, but the description is sufficient for correct 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?

The tool has zero parameters and the schema already covers this completely, so there is no parameter documentation gap. The description adds context about token-threshold behavior, though parameter-specific semantics are naturally not applicable.

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 uses a specific verb ('Fetch') and resource ('current agent compact inbox'), making the tool's function immediately clear. It also distinguishes the tool from sibling paperclip_* tools by naming the inbox resource and the conditional return modes.

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 phrase 'Call again whenever fresh assignment state matters' gives clear situational guidance for when to invoke the tool. It does not name alternatives or exclusion conditions, but the tool is a singular fetch of the inbox and siblings are not obvious substitutes, so the guidance is adequate.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses meaningful conditional behavior: Markdown is returned inline only when it fits the token threshold, otherwise a new immutable snapshot path is returned. It also warns against editing snapshots to modify Paperclip, which is valuable context beyond 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?

Four dense sentences carry all essential information with no filler. The endpoint, conditional response behavior, parameter clarification, and safety warning are each placed in their own sentence, making the definition easy to parse.

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 read-only single-issue fetch with a small parameter surface and strong schema descriptions, the description covers endpoint, response format behavior, all_fields scope, and snapshot immutability. No output schema is present, but the description provides sufficient behavioral expectations for correct 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 100%, and both id and all_fields already have rich descriptions in the schema. The description mostly restates the all_fields semantics ('only expands fields from that same response; it never changes the endpoint') rather than adding new parameter insight, so the baseline of 3 is appropriate.

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 opens with a specific verb and resource ('Fetch one issue with GET /api/issues/:id'), making the tool's purpose immediately unambiguous. The word 'one' clearly distinguishes it from sibling list tools like paperclip_issues, and the title reinforces its read-only single-issue scope.

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 clearly establishes the context for use: retrieving a single issue. It also gives practical guidance on all_fields behavior and explicitly warns not to edit snapshots. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it stops short of full routing guidance.

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

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

Beyond the annotations (openWorldHint, idempotentHint, destructiveHint), the description discloses atomicity, lock-stealing prohibition, terminal 409 semantics, and the stale-reclaim recovery path. This adds meaningful behavioral context without contradicting any annotation. Minor gap: it does not state what the checkout returns or what state transition the issue undergoes.

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 terse sentences, each earning its place: purpose, conflict handling, and parameter condition. The core purpose is front-loaded in the first clause, and there is zero filler or repetition of schema content.

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 moderate complexity, the essential calling knowledge is present: the required id, the precise meaning of reclaim_stale, the terminal 409 behavior, and a safety profile from annotations. Remaining gaps — no return-value disclosure and no elaboration on expected_statuses semantics — are minor but worth noting.

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 only 33%, the description carries the burden for undocumented parameters. It compensates where it matters most: reclaim_stale has no schema description but is fully scoped here (true only when adopting your own stale in_progress checkout after a crash). expected_statuses is already covered by its schema description, and id is self-evident from the resource noun.

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 opens with a specific verb and resource: 'Atomically claim an issue for the current agent,' naming the operation, the object, and the actor scope. This clearly distinguishes checkout from siblings such as paperclip_issue_release (the inverse operation) and paperclip_issue_create without restating the title.

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 context is clear — this is the tool for claiming an issue before working on it — and it adds strong conditional guidance ('Set reclaim_stale=true only when adopting your own stale in_progress checkout after a crashed run') plus a failure rule (409 is terminal). However, it never routes to alternatives explicitly; nothing points to paperclip_issue_release for when work is complete, so when-to-use vs alternatives is only implied.

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

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

The description adds valuable behavioral context beyond the annotations by disclosing that it returns only a compact acknowledgement and intentionally does not inject the full created issue response into model context. This is a meaningful, non-obvious behavior. The description does not contradict the openWorldHint, idempotentHint, or destructiveHint 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?

The description is two tight sentences with no filler. The core action leads, and the important response behavior follows. Every sentence earns its place by either stating the tool's function or disclosing a critical output constraint.

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 tool with 12 parameters, no output schema, and minimal parameter documentation, the description is too thin to be complete. It clarifies the return behavior, but does not explain the semantics of the many optional fields, expected value formats for status/priority, or how relationships like parent_id, project_id, and blocked_by_issue_ids interact. An agent has to infer a lot from parameter names alone.

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 8%, with just the 'extra' parameter explained in the schema, and the description itself provides no parameter-level guidance. Names like title, status, priority, parent_id, and blocked_by_issue_ids are somewhat self-explanatory, but fields like extra, goal_id, label_ids, and assignee_agent_id lack sufficient semantic detail. The description does not compensate for the low schema coverage.

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 uses a specific verb and resource: 'Create an issue/subtask in authoritative Paperclip state.' It clearly identifies the tool's action and object, and the imperative 'Create' distinguishes it from sibling tools like paperclip_issue_update, paperclip_issue_release, and paperclip_issue_checkout.

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 implies usage through the verb 'Create,' so an agent can infer it should be used when creating an issue or subtask. However, it does not explicitly state when not to use it, mention prerequisites, or name alternatives such as paperclip_issue_update for modifications. Usage context is clear but relies on inference.

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

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

Annotations already signal destructive and non-idempotent behavior. The description adds useful context beyond that: the issue transitions to todo, and the response is only a compact acknowledgement. It does not contradict 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?

Two short sentences with no fluff. The core action is front-loaded, and the response behavior is stated in the second sentence. Every word 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 one-parameter destructive action, the description covers the core effect and return shape. However, it leaves meaningful gaps: the semantics of `id`, any prerequisites like an active checkout, and the exact contents of the compact acknowledgement are all unspecified.

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?

The schema has zero description coverage and the description never explains what `id` refers to. An agent must guess whether it is the issue id, a checkout id, or something else, especially since the wording emphasizes 'current agent checkout' without tying it to the required parameter.

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 ('release'), the target resource ('current agent checkout'), and the resulting state ('return the issue to todo'). This clearly distinguishes it from siblings like checkout, create, update, or comment operations.

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 role as the counterpart to paperclip_issue_checkout is implied, and an agent can infer it should be used when finished with a checked-out issue. However, the description never explicitly states when to use it, when not to use it, or names an alternative.

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

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

Annotations already mark the tool read-only and idempotent; the description goes further by revealing the compact Markdown output format, the default 'all visible issues' behavior, and the token-threshold condition where results are inline versus returned as a snapshot path. This is meaningful behavioral context that structured fields do not provide.

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?

Five short sentences, each carrying distinct information: endpoint/format, default behavior, filter/limit effects, threshold-based output, and routing to a sibling. No filler or redundancy.

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 core usage and the unusual snapshot-path behavior, but with 13 parameters and no output schema it leaves meaningful gaps: specific filter parameters are not enumerated, and the snapshot path mechanism is not explained. It is adequate but not complete for a tool of this complexity.

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 only 23% of parameters described in the schema, the description needed to compensate. It only says 'Filters narrow the list; limit caps it,' which is generic and names only the limit parameter. The other 10 filter parameters (label_id, origin_id, parent_id, etc.) remain semantically unexplained, so the description falls short of making the parameters usable.

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 opens with a specific verb and resource, 'Return a compact Markdown list from GET /api/companies/:companyId/issues', and clarifies the default scope ('all visible company issues'). The final sentence explicitly distinguishes it from the singular paperclip_issue tool, so an agent can tell which tool to use.

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 states when to use the tool (to get a list of issues) and explicitly points to paperclip_issue for detail on a single issue. It also explains the effect of no filters/no limit and that filters narrow the list, giving the agent clear conditions for parameterization.

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

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

Annotations already signal destructive, non-idempotent behavior, and the description adds useful context by calling the state 'authoritative' and noting it returns only a compact acknowledgement. It does not elaborate on what may be overwritten or which fields can have destructive effects, but it does not contradict 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?

The description is two tight sentences with no filler. It front-loads the core purpose, gives an immediate usage rule, states the key exclusion, and discloses the return behavior—all in minimal space.

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 tool has 17 parameters, no output schema, and almost no per-parameter documentation. The description covers purpose and broad usage but does not provide enough guidance for an agent to confidently choose and populate fields in complex update scenarios, nor does it explain destructive consequences beyond the annotation.

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 6%, and the description does not compensate. It vaguely maps to 'status/assignment/field changes and optional comments', but 17 parameters remain largely unexplained, including title, priority, labels, parent_id, project_id, hidden_at, interrupt, and blocked_by_issue_ids.

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 ('Update'), a clear resource ('authoritative issue state'), and the kinds of changes it supports ('status/assignment/field changes and optional comments'). It also distinguishes itself by saying 'never edit snapshot files', which separates it from related tools without ambiguity.

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?

It explicitly says when to use the tool: for status, assignment, field changes, and optional comments. It also gives a clear exclusion ('never edit snapshot files'), though it does not name a specific sibling tool as the alternative.

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

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

The annotations only provide openWorldHint, so the description carries the behavioral disclosure burden. It does well by explaining that GET/HEAD return inline Markdown below a token threshold or a new immutable snapshot path above it, and that mutations return only a compact acknowledgement. Error, auth, and rate-limit behavior are not covered, but the core response behavior is transparent.

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 tight sentences front-load the purpose, then the constraint, then the behavioral contract. There is no filler and 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?

For an open-ended fallback with no output schema, the description covers scope, path restrictions, response behavior, and sibling precedence. Auth and error details are absent, but they are somewhat endpoint-dependent and thus not critical for a raw fallback tool.

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 coverage is only 40%, and the description adds some method-level meaning by contrasting GET/HEAD vs mutations and by reinforcing the path restriction. However, it does not explain body, query, or all_fields beyond what the schema already offers, leaving a gap for a generic fallback tool with five parameters.

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 the tool is a raw fallback for Paperclip endpoints not covered by dedicated tools, and it specifies the HTTP surface through relative same-origin paths and method-specific behavior. This clearly distinguishes it from the many dedicated sibling tools on the same API.

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?

It explicitly says 'Prefer dedicated tools' and defines itself as the fallback for endpoints 'not covered by dedicated tools', giving an agent a direct decision rule. It also adds a hard constraint: relative same-origin paths only, with external URLs rejected.

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