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

Annotations already mark destructiveHint: false. The description adds behavioral context: returns the created comment object with fields, and error handling details for 400, 401, 404. No contradiction, and the description enriches understanding beyond 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 well-structured with sections (main purpose, Args, Returns, Examples, Error Handling), each sentence adds value, and the purpose is front-loaded. No fluff.

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?

Despite no output schema, the description lists return fields (id, body, authorId, authorType, createdAt). Error handling covers common failures. The tool is simple (2 params, no nested objects), and the description is fully sufficient for an agent to use it correctly.

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?

Both parameters are fully described in the input schema (100% coverage). The description adds example values and contextual explanations (e.g., approvalId example 'apr_abc123', body example in markdown), going beyond the schema's minimal description.

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 'Post a markdown comment on an approval request' with specific verb and resource, and distinguishes from siblings like paperclip_add_comment (general) and paperclip_resubmit_approval or paperclip_approve (status changes).

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 'Examples' section explicitly states when to use ('adding context to an approval request or responding to board revision feedback') and when not to use ('when you also want to change the approval status'), pointing to alternative 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?

Annotations indicate non-destructive and open-world false. The description adds that a Run ID header is injected for audit trail, and lists HTTP error codes (400, 401, 404) with troubleshooting tips. It also notes the return object. This provides useful behavioral context beyond 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 well-structured with Args, Returns, Examples, Error Handling sections. However, it is somewhat verbose for a simple two-parameter tool. A more concise version could omit the full list of return fields since they are straightforward.

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?

Given no output schema, the description explains the return shape. It covers error codes and prerequisites (Run ID header injection). For a simple comment creation tool, it provides sufficient context for an agent to use it effectively.

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 100%, so parameters are already documented. The description adds meaning with examples (e.g., 'body — Comment body in markdown (example: "@QA — ready for review on PAP-42. Changes: ...")') and clarifies that body must be non-empty (from error handling). This adds value.

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 'Post a markdown comment on an issue', using a specific verb and resource. It distinguishes from sibling tools like paperclip_add_approval_comment by not mentioning approval, and later contrasts with paperclip_update_issue when used to add a comment while updating fields.

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 provides explicit 'Use when' and 'Don't use when' guidance, including an alternative tool (paperclip_update_issue) for combined comment+field updates. This helps the agent choose correctly.

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?

While annotations are minimal (destructiveHint: false), the description adds behavioral context: creation action, error codes (400, 401, 404), and implication that duplicate triggers are not allowed. Lacks details on idempotency or rate limits, but adequate for a creation 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?

Well-structured with summary, args, returns, examples, and error handling sections. Front-loaded with purpose. Some minor redundancy (e.g., param descriptions overlap schema) but overall efficient.

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?

Given 4 parameters, no output schema, and no nested objects, the description fully specifies inputs, returns (fields), error cases, and usage context. No critical gaps.

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 covers all 4 parameters (100%), but description adds value with examples (e.g., routineId), enum meaning, cron format clarification, timezone default, and error conditions. Exceeds baseline 3.

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?

Explicitly states 'Add a trigger to a routine' with specific verb and resource, and distinguishes from siblings like paperclip_update_routine_trigger and paperclip_delete_routine_trigger through usage guidance and error handling.

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?

Provides explicit when-to-use and when-not-to-use guidance, including a direct sibling alternative ('use paperclip_update_routine_trigger'). Also implies verification with paperclip_list_routines for 404 errors.

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 provide destructiveHint=true; description adds that it writes new records, requires board-level authentication, and returns specific JSON counts. No contradictions, and sufficient behavioral context beyond 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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Front-loaded warning. Every sentence is informative without being verbose.

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?

Covers all essential aspects given no output schema: describes return format, prerequisites (preview first), authentication, error codes, and parameter behavior. Complete enough for correct agent 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 coverage is 100%, so baseline 3. Description adds meaningful context: explains source types, include options, target validation, and collision strategy. Adds value without redundancy.

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 'Apply company import' and explains it applies a validated import bundle, writing new records. It distinguishes from sibling paperclip_preview_company_import by noting it should be run first.

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?

Provides explicit when-to-use ('applying a validated import bundle'), when-not-to-use (inspect changes, use preview instead), and alternatives. Error handling section gives guidance on common failure scenarios.

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 indicate destructiveHint: true and openWorldHint: false. The description adds behavioral context: it triggers a workflow, returns an updated approval with status 'approved' and approvedAt timestamp, and details error codes (401, 403, 404, 422) with their meanings. No contradiction with 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 well-structured with sections for arguments, returns, examples, and error handling. It front-loads the warning and purpose. Every sentence contributes useful information without unnecessary verbosity.

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?

Although there is no output schema, the description explains return values (updated approval with status and timestamp). It covers error handling exhaustively and provides context about board-only usage and workflow triggering. This is complete for a single-parameter tool with complex error scenarios.

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 100% for the single parameter (approvalId described as 'Approval UUID'). The description adds an example ('apr_abc123') and states it is required, but these add minimal meaning beyond the schema. Baseline is 3 due to high 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 clearly states the tool's function: 'Approve a pending approval request, triggering the associated workflow.' It uses a specific verb (approve) and resource (approval request), and distinguishes from siblings by mentioning alternatives like paperclip_reject or paperclip_request_revision for different actions.

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 provides explicit when-to-use guidance: 'Use when: approving a hire_agent or budget_override request after board review (requires board API key)' and 'Don't use when: you want to reject or request changes — use paperclip_reject or paperclip_request_revision instead.' It also specifies prerequisites (board API key) and error handling scenarios for erroneous use.

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 destructiveHint annotation, the description adds that the action is irreversible through the API and uses a specific POST endpoint, which are important behavioral traits not captured by annotations alone.

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?

Well-structured with sections for args, returns, examples, and error handling. The warning icon and front-loaded critical info (board-only, irreversible) make it concise yet informative.

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?

Fully covers purpose, usage, parameters, return value, and error handling. Given the simple single-parameter input and no output schema, the description leaves no gaps.

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 100%, so the description adds value by providing an example UUID and clarifying the parameter purpose, though the schema already has a description. The error handling section also adds context.

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 it archives a company by setting status to 'archived' and uses a dedicated POST endpoint, not PATCH. It distinguishes from paperclip_update_company, which is for other field updates.

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?

Provides explicit when-to-use (decommissioning a company) and when-not-to-use (updating other fields), with a direct reference to the sibling tool paperclip_update_company. Also notes board-only authentication requirement.

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 indicate non-destructive, non-idempotent. The description adds behavioral context: sets executionRunId, details error handling for 401, 404, 409, 422, including specific retry advice for 409. No contradiction with 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 well-structured with distinct sections for action, arguments, returns, examples, and error handling. It is concise yet comprehensive, with no unnecessary verbiage.

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?

Despite lack of output schema, the description explains the return value (updated issue object with executionRunId). Error handling covers all relevant HTTP statuses with actionable advice. The tool's complexity is fully addressed.

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?

Input schema covers both parameters with descriptions (100% coverage). The description adds examples for issueId ('PAP-42') and expectedStatuses (['todo']), and clarifies that checkout fails if current status not in list, which adds value beyond 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 tool claims an issue for work by checking it out to the current agent. The title from annotations ('Check out issue for work') reinforces this. It distinguishes from sibling tools like paperclip_get_issue (read-only) and paperclip_release_issue.

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?

Explicit usage guidance is provided with 'Use when: claiming an assigned issue before starting work' and 'Don't use when: you only need to read the issue — use paperclip_get_issue instead'. It also advises using expectedStatuses to guard kanban column.

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 indicate non-destructive and non-open-world behavior. The description adds context such as requiring a board API key, detailing error codes (400, 401, 403), and specifying that it bypasses approval flow. No contradictions with 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 well-structured with clear sections (Args, Returns, Examples, Error Handling). It is front-loaded with the important warning about board-only usage. While it is somewhat lengthy, each section serves a purpose and no information is redundant.

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?

Given the complexity (14 parameters, nested objects), the description covers parameter details, error scenarios, and usage context. There is no output schema, but the return object is described generically. The error handling and examples provide sufficient completeness.

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 input schema has 100% description coverage, so baseline is 3. The description adds value beyond the schema by explaining some parameters in more detail (e.g., permissions.canCreateAgents as CEO-level, icon as UI identifier). It also lists all parameters with types, but the schema already does that.

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 directly creates an agent and distinguishes it from the sibling tool paperclip_create_agent_hire, which handles approval-flow hires. The verb 'create' and resource 'agent' are specific, and the contrast is explicit.

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 provides explicit usage guidance: it is for board-only direct hires, prefers the alternative sibling for approval flows, and includes 'Use when' and 'Don't use when' examples. Error handling also clarifies authentication and permission requirements.

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?

Discloses governance flow, pending approval, error codes, and permission restrictions (only CEO agent). Annotations already indicate non-destructive, so description adds value.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). No unnecessary words; all sentences add value.

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?

Complete given no output schema: explains return object type, when to use, and error handling. Covers all key aspects.

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 baseline 3. Description adds example values and context but doesn't significantly expand beyond schema for optional params.

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?

Clear verb+resource: 'Create an agent hire request, triggering the governance approval and onboarding flow.' Distinguishes from siblings like paperclip_create_agent and paperclip_create_approval.

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?

Explicit 'Use when' and 'Don't use when' with alternative tool name and rationale: 'use paperclip_create_approval with type: hire_agent for custom payloads'.

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?

Discloses critical behavior: key shown only once (store securely), board-only access, and detailed error handling (401, 403, 404). Annotations only provide destructiveHint false and openWorldHint false, so description adds substantial value.

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?

Well-structured with sections for warning, arguments, returns, examples, and error handling. Front-loaded with important security note. Every sentence is informative and concise.

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?

Despite no output schema, the description details the return value (key record with fields). Covers error states, usage scenarios, and prerequisites. Tool is simple and all relevant context is provided.

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 covers all parameters with descriptions (100% coverage). The description adds example values and clarifies optionality, providing moderate additional value beyond the 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 (create) and resource (long-lived API key for an agent). It is distinct from sibling tools like paperclip_create_agent or paperclip_create_secret by focusing on agent-specific keys.

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?

Includes explicit use cases: 'Use when provisioning a new API key... or rotating a compromised key' and 'Don't use when the agent already has a valid key' with alternative tool suggestion (paperclip_get_agent). Also specifies board-only requirement.

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 indicate destructiveHint=false and openWorldHint=false. The description adds behavioral details beyond these: it describes the return object structure (id, type, status:'pending', payload, createdAt), error handling for 400 and 401, and the optional override for requester. This enriches the agent's understanding of the tool's behavior.

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 well-structured with clear sections (Args, Returns, Examples, Error Handling), making it easy to scan. However, it is somewhat verbose (e.g., repeating the enum in the description and the schema). It could be slightly more concise without losing essential information.

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?

Given the tool has 3 parameters, no output schema, and nested objects, the description covers all necessary aspects: purpose, usage guidelines, parameter semantics, return format, and error handling. It is complete and leaves no significant gaps for an agent to understand the 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 description coverage is 100%, so baseline is 3. The description adds meaningful extra context: for the 'type' parameter, it lists enum values; for 'payload', it gives an example for hire_agent; for 'requestedByAgentId', it clarifies override and default behavior. This adds value beyond the schema descriptions.

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 creates an approval request for board review, with a specific verb 'Create' and resource 'approval request'. It explicitly distinguishes from a sibling tool by advising to use 'paperclip_create_agent_hire' instead when doing a streamlined hire, satisfying the sibling differentiation criterion.

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 provides explicit usage guidance with an 'Examples' section that includes 'Use when' and 'Don't use when' directives, and directly names an alternative tool (paperclip_create_agent_hire). This gives clear context for when to use this tool vs. alternatives.

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?

Description discloses board-only auth requirement and auto-generation of issuePrefix. Annotations already set destructiveHint: false, so no contradiction. However, it doesn't explicitly mention mutation or side effects beyond creation, though that's implied.

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?

Well-structured with distinct sections (Args, Returns, Examples, Error Handling). Each sentence adds useful information, no fluff. Length is appropriate for the complexity.

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?

Despite no output schema, the description details the return object (UUID, issuePrefix, status, timestamps). Error handling covers 400, 401, 403. For a creation tool, this is complete and eliminates ambiguity.

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 100%, so baseline is 3. Description adds value with examples (e.g., budgetMonthlyCents example), explanation of issuePrefix auto-generation, and notes name is required. This exceeds the schema's basic descriptions.

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 'Create a new company' and specifies the auto-generated issuePrefix, distinguishing it from other company tools like paperclip_update_company and paperclip_archive_company. The verb 'create' and resource 'company' are explicit.

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 guidelines are explicit: 'Use when: onboarding a new organization or setting up a tenant on the board' and 'Don't use when: you need to update an existing company — use paperclip_update_company instead'. Also notes board-level authentication requirement.

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 indicate non-destructive behavior. The description adds that companyId is injected from auth config and returns the created goal with UUID. No contradictions. Could mention more about side effects or permissions.

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 well-structured with sections (Args, Returns, Examples, Error Handling), concise yet comprehensive, and front-loaded with the key purpose. Every sentence adds value.

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 creation tool with 5 parameters and no output schema, the description covers purpose, parameters, return value (goal object with UUID), error codes, and usage examples. Could elaborate on return fields, but sufficient.

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 100% schema coverage, baseline is 3. The description adds value by providing examples (status='active', level='company') and clarifying that title is required and parentId is for hierarchy, 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 clearly states it creates a new company goal, with a specific verb and resource. It distinguishes from the sibling tool paperclip_update_goal by explicitly noting when not to use it.

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?

Provides explicit when-to-use (creating quarterly or product-level goals) and when-not-to-use (goal already exists, use update instead), along with error handling guidance for different HTTP status codes.

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 only indicate destructiveHint=false and openWorldHint=false. The description discloses return behavior (returns created issue object with identifier) and error codes for 400, 401, 404. No contradiction, but lacks details on side effects beyond creation.

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?

Well-organized with separate sections for Args, Returns, Examples, and Error Handling. Every sentence adds value, no repetition of schema. Concise yet comprehensive.

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?

Addresses all key aspects: purpose, parameters, usage context, return type, and error scenarios. Despite 11 parameters and no output schema, description fully compensates with clear return description and examples.

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 100%, baseline 3. Description adds value beyond schema by clarifying default status behavior ('pass 'backlog' explicitly (API default is todo)') and explaining inheritExecutionWorkspaceFromIssueId ('for follow-up tasks on same checkout').

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 'Create a new issue in the current company', specifying the action, resource, and scope. It distinguishes from sibling 'paperclip_update_issue' by explicitly noting when not to use this tool.

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?

Provides explicit 'Use when' and 'Don't use when' examples, including a direct alternative ('use paperclip_update_issue to modify it'). Also includes error handling with actionable remediation steps.

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 significant behavioral context beyond annotations: return shape (id, name, color, createdAt), error handling codes (400, 401, 409), and the suggestion to check for existing labels. Annotations only declare non-destructive and non-open-world, so description carries the burden and does so thoroughly.

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 well structured with clear sections (Args, Returns, Examples, Error Handling). It is concise, front-loaded with the main purpose, and every sentence adds value without 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?

Given no output schema, the description fully explains the return object, error scenarios, and usage context. It covers all essential information for an agent to correctly invoke the tool, making it highly complete.

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 100%, so baseline 3 is appropriate. The description repeats schema info for name and color, adding only minor nuance like 'typically namespaced' for name. No significant new meaning beyond what schema already 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 clearly states 'Create a new label for the current company' with a specific verb and resource. Among siblings, there is no other label creation tool, and paperclip_list_labels exists for listing, so it distinguishes well.

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?

Explicit guidance: 'Use when: seeding a missing taxonomy label... Don't use when: the label already exists — use paperclip_list_labels to check before creating.' Provides clear when-to-use and when-not-to-use with an alternative tool named.

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 indicate non-destructive and open-world false. The description adds that the tool returns the created project object with UUID, and covers error handling for validation, auth, and not-found cases. No contradictions with 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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). No redundant sentences; each part provides unique information. Length is appropriate for the complexity.

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?

Despite no output schema, the description explains the return value. Includes error scenarios. Could mention more sibling alternatives for related operations (e.g., update_project), but the coverage is solid for a create 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 100%, baseline 3. The description adds value by providing example values for parameters (e.g., status: 'active', workspace.cwd: '/home/user/repo') and clarifying the workspace is optional and created alongside the project. This goes beyond the schema descriptions.

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 'Create a new project' and mentions optional workspace config. It explicitly distinguishes from the sibling tool 'paperclip_create_workspace' in the 'Don't use when' section, making the purpose 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?

Provides explicit 'Use when' and 'Don't use when' guidance, including a specific alternative tool for adding workspace to existing projects. This gives the agent clear decision rules.

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?

Description adds behavioral context beyond annotations, including that it is a creation operation (non-destructive per annotations), return value structure, and error handling for common failure modes. It does not contradict 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 well-structured with sections for args, returns, examples, and error handling. It is front-loaded with the main action. While comprehensive, it could be slightly more concise by trimming redundant phrases.

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?

Given 5 parameters, no output schema, and the need to guide an agent, the description covers purpose, usage context, parameter explanations, error scenarios, and return format. It is fully sufficient for correct selection and 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 provides descriptions for all parameters (100% coverage). The description adds value by providing specific examples and explaining options for concurrencyPolicy and catchUpPolicy, clarifying the meaning beyond the 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 tool creates a routine for an agent and distinguishes from sibling tools like paperclip_add_routine_trigger and paperclip_run_routine by specifying that triggers are added separately and that this is for scheduled workflows.

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?

Explicit when-to-use and when-not-to-use guidance is provided: 'Use when: setting up a scheduled workflow for an agent before adding a cron trigger' and 'Don't use when: you want to trigger immediately — use paperclip_run_routine after creating the routine.' This effectively differentiates from alternatives.

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?

Discloses board-only requirement, encryption, non-return of value, and error codes (400, 401, 403, 409). Annotations only provide destructiveHint=false and openWorldHint=false, so description adds essential 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?

Well-structured with sections (Args, Returns, Examples, Error Handling). Uses bullet points and emoji for caution. Every sentence is informative and no 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?

Covers all aspects: purpose, parameters, return shape (value never returned), usage guidance, error handling, and security considerations. No output schema, but description provides return fields.

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 100%, so baseline is 3. Description repeats schema info but adds context like default provider and meaning of externalRef (ARN). Also emphasizes value is never returned.

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 'Create a new secret for a company' with a specific verb and resource. It includes behavioral warnings (board-only, encrypted storage, value never returned) and distinguishes from the sibling tool paperclip_rotate_secret.

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?

Explicit 'Use when' and 'Don't use when' sections with alternative tool (paperclip_rotate_secret) for updating existing secrets. Error handling also guides correct usage.

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?

Description adds return format (workspace object with fields) and error handling (400, 401, 404) beyond annotations. No contradiction with annotations (destructiveHint: false).

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Every sentence adds value; no fluff.

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?

Complete for a creation tool: explains return fields, error conditions, and usage context relative to siblings. No output schema, but description adequately documents return value.

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 100%, but description adds value by providing example values for each parameter and clarifying the conditional requirement (at least one of cwd or repoUrl) which is not fully captured in 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?

Clearly states 'Create a new workspace for a project' with specific verb and resource. Explicitly distinguishes from sibling tool paperclip_create_project by providing when-to-use and when-not-to-use examples.

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?

Provides explicit examples for when to use (adding a second workspace) and when not to use (creating a project), including naming the alternative tool. Also specifies the condition that at least one of cwd or repoUrl is required.

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 set destructiveHint=true, so description adds value by confirming 'Permanently delete' and describing the return stub. Does not contradict 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?

Well-structured with Args, Returns, Examples, Error Handling sections. Front-loaded with main action. No fluff.

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?

Covers purpose, parameter example, usage guidance, error codes. Lacks prerequisites or permission requirements, but given simplicity and no output schema, it's sufficient.

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?

Only one parameter with schema description 'Attachment UUID'. Description adds example format ('att_abc123') and links to paperclip_list_attachments for verification, going beyond 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?

Clearly states 'Permanently delete an attachment by ID.' Verb+resource is specific (delete attachment). Distinguishes from siblings like download_attachment, upload_attachment, list_attachments.

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?

Explicitly says when to use (remove superseded/mistakenly uploaded file) and when not to use (read first, use paperclip_download_attachment). Also provides error handling guidance for 401 and 404.

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 mark destructiveHint=true, and the description goes beyond by listing error codes (401,403,404) with remedies, return type (deleted document stub), and access constraints (Board-only). No contradictions with 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?

Information is logically sectioned with emojis, bullet points, and clear headings. Every sentence serves a purpose—no redundancy. Front-loaded with the critical action and context.

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 delete with 2 params and no output schema, the description fully covers purpose, usage, parameters, errors, and return value. No gaps remain.

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 100% so baseline is 3. Description repeats parameters (issueId, key) with examples but adds no new semantic detail beyond what the schema provides. The Board-only context is the only additional insight.

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 explicitly states 'Delete a document from an issue by key', specifying the action (delete), resource (document), and scope (by issue key). It distinguishes from siblings like paperclip_upsert_document by noting the Board-only requirement and providing a concrete usage example.

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?

Provides clear when-to-use ('removing an obsolete document') and when-not-to-use ('clear the body' → use upsert) guidance. Also specifies that board API key is required, which sets expectations for auth context.

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 indicate destructiveHint=true, and the description adds that the trigger is deleted but not the routine. It also includes error handling for 401 and 404, which adds behavioral context beyond the schema and 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 well-structured into clearly labeled sections (Args, Returns, Examples, Error Handling) and is concise with no unnecessary words.

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 one-parameter destructive tool with no output schema, the description covers all necessary aspects: action, parameter, return value, usage guidance, and error handling. It is fully self-contained.

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 100% and the description merely restates the schema's parameter description ('Routine trigger UUID') with an example value. It adds minimal additional meaning beyond the 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?

Clearly states the verb 'Delete' and resource 'routine trigger', and explicitly distinguishes from deleting the entire routine by stating 'The routine itself is not deleted.' This differentiates it from the sibling tool paperclip_delete_routine.

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?

Provides explicit 'Use when' and 'Don't use when' scenarios, and directly names the alternative tool paperclip_delete_routine for the opposite use case.

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 indicate destructiveHint=true. Description adds board-only requirement and error handling details, but does not mention potential side effects like cascade deletes or impact on related data.

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?

Description is well-structured with warning, action, returns, args, usage guidance, and error handling. All sentences add value.

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 destructive tool with no output schema, the description provides return fields, error codes, and usage context. It is complete given the 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?

Schema coverage is 100% with descriptions. The description adds example values for both parameters and lists return fields, providing meaning beyond the 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 'Permanently delete a workspace from a project' and notes it is board-only. It uses a specific verb and resource, distinguishing it from paperclip_update_workspace.

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?

Explicit when-to-use (removing unneeded workspace) and when-not-to-use (updating settings, with alternative paperclip_update_workspace) are provided.

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 indicate destructiveHint=true, so the description adds extra context: disabling is reversible, URL-encoding is automatic, and error handling covers 404, 401, and 403. The board-only requirement is also disclosed. No contradictions with 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 well-structured with sections (Args, Returns, Examples, Error Handling). It is concise, with each sentence providing essential information. No fluff.

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?

Given the simple tool (one parameter, no output schema), the description covers purpose, usage, error handling, and reversibility. It could mention the shape of the returned object, but that is likely standard. Overall, sufficient for the agent to use correctly.

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 only parameter 'pluginKey' has 100% schema description coverage with an example. The tool description adds that it is 'URL-encoded automatically', which is not in the schema. This extra detail enhances understanding beyond the 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 ('Disable an active plugin by its key without uninstalling it'), includes a specific verb ('disable'), and distinguishes from the sibling uninstall flow by noting it's reversible. The title in annotations also confirms 'Disable plugin'.

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 provides usage context: 'Board-only', 'Use when: temporarily deactivating a plugin...', and 'Don't use when: you want to permanently remove the plugin — use the uninstall flow instead'. This clearly differentiates from alternatives.

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 set readOnlyHint=true, aligning with 'Fetch'. The description adds transparency by detailing the return envelope (attachmentId, contentType, size, contentBase64), response format behavior, and error codes. No contradictions.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Every sentence serves a purpose, no redundancy. Efficiently conveys all necessary information in a compact format.

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?

Despite no output schema, the description fully explains the return envelope. It covers main usage, differentiates from siblings, and addresses error cases. For a simple 2-param read tool with rich annotations, this is comprehensive.

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 100%, and the description adds value with an example value for attachmentId ('att_abc123') and clarifies the default and behavior of response_format. This goes beyond the schema by providing contextual examples.

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 'Fetch the content of an attachment by ID' using a specific verb and resource. It distinguishes itself from siblings like paperclip_list_attachments by specifying that it retrieves content, not just metadata.

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?

Explicitly provides when to use ('when reading a previously uploaded attachment') and when not to use ('need metadata only' → use paperclip_list_attachments). Also includes error handling with actionable advice (check API key, verify UUID).

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 indicate idempotent and non-destructive; description adds board-only constraint, confirms safe if already enabled, and mentions return object, providing context beyond 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?

Well-structured with sections and bullet points, but could be slightly more concise; still clear and 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?

Complete for a one-parameter tool without output schema; covers purpose, usage, error handling, and parameter details adequately.

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?

Only one parameter with 100% schema coverage; description adds that pluginKey is URL-encoded automatically, which is helpful beyond the 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 it enables a disabled plugin by key, specifies 'board-only', and distinguishes from siblings like paperclip_install_plugin and paperclip_disable_plugin.

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?

Explicit when to use (re-activating a disabled plugin), when not to use (plugin not installed, use install_plugin instead), and error handling for 404, 401, 403 with corrective actions.

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?

Discloses crucial behaviors: Board-only authentication requirement, JSON-only output, response truncation at 25k chars (files can be very large), and error codes. Annotations only provide destructiveHint and title, so description adds substantial value.

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?

Well-structured with warning, args, returns, examples, and error handling. Each section is concise and front-loaded (first line is 'Board-only: Export company package'). No unnecessary words.

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?

Comprehensively covers purpose, usage, parameters, output format (including truncation example), error handling, and examples. Despite 7 parameters, nested objects, and no output schema, everything needed for correct invocation is present.

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 100%, so baseline is 3. Description adds value by showing default values for include subproperties, clarifying optional filters (e.g., 'omit for all skills'), and explaining expandReferencedSkills. This goes beyond mere repetition.

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 exports a company package (specific verb and resource). It includes 'Board-only' to indicate access level and distinguishes from import tools (paperclip_preview_company_import, paperclip_apply_company_import) in the usage examples.

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?

Explicit sections 'Use when' and 'Don't use when' with alternatives provided. Error handling details per HTTP status code (401, 403, 404) give clear corrective actions.

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 declare readOnlyHint=true. The description adds value by detailing the paginated return structure, specifying error codes (401, 403) with remedies, and implying the tool is safe and non-destructive. Does not mention rate limits but overall sufficient.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Each sentence adds value, though slightly verbose in the Returns section with detailed typing. Still efficient.

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?

Given no output schema, the description thoroughly explains the return format. Covers parameter usage, examples, and error handling. Lacks mention of rate limits or data retention, but these are minor omissions.

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 100% with clear parameter descriptions. The description restates parameters with examples and default values, adding marginal value beyond the schema. Baseline score 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?

Clearly states 'Get the audit trail activity feed for the current company' with a specific verb and resource. Explicitly distinguishes from sibling tool paperclip_list_comments in the 'Don't use when' section.

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?

Provides explicit when-to-use ('auditing what an agent did on a specific issue or reviewing recent company actions') and when-not-to-use ('you need issue comments — use paperclip_list_comments instead'), along with error handling hints.

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 value beyond annotations by detailing return fields (Agent object with specific properties) and error handling (401, 404). Annotations already declare readOnlyHint=true, so the mutation risk is known, but the description enriches behavioral 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?

The description is concise, well-organized with clear sections (Args, Returns, Examples, Error Handling). Every sentence provides necessary information without fluff. The structure aids quick parsing by an AI agent.

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 purpose, parameters, return fields, usage context, and error handling. Despite the absence of an output schema, the description lists the returned fields (id, name, urlKey, etc.) which compensates. For a simple get tool, this is complete.

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 100%, so baseline 3. The description adds a concrete example for agentId ('agt_abc123') and implies the response_format via the 'Returns' section mentioning format. While it doesn't elaborate on response_format, the schema is clear with enum and default. The example adds moderate value.

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 'Get full details for a single agent by UUID', specifying a verb and resource. It distinguishes from sibling tools like paperclip_list_agents which lists agents, and paperclip_update_agent which modifies. The title annotation 'Get agent by ID' reinforces this.

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?

Explicit usage guidance is provided: 'Use when: reading an agent's current config before updating it or checking its heartbeat settings' and 'Don't use when: you need a list of agents — use paperclip_list_agents to discover IDs first'. Error handling hints also guide when to use alternative 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?

Annotations declare readOnlyHint=true; description adds that linked issues are not included and details error codes (401, 404). Provides useful behavioral context beyond 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?

Description is concise with sections (Args, Returns, Examples, Error Handling) and front-loaded with the core purpose. No extraneous sentences.

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?

Given no output schema, the description lists return fields and common errors, making it complete for a single-entity fetch. Could mention response_format effect, but not critical.

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 100%; description adds an example for approvalId and lists the return fields (id, type, status, etc.) which is not in the input schema, adding value for understanding the response.

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?

Description clearly states 'Get a single approval request by ID' with a specific verb and resource. It distinguishes from siblings like paperclip_list_approvals (for lists) and paperclip_approve (for approving).

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?

Explicitly provides when to use ('checking status/payload before acting') and when not to use ('for a list, use paperclip_list_approvals'), including a named 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 declare readOnlyHint=true, matching the read-only nature of fetching a comment. The description adds value by specifying the returned object fields (id, body, authorId, authorType, createdAt) and error handling (401, 404 with remedies). No contradiction exists.

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 well-organized with headings (Args, Returns, Examples, Error Handling). It is concise yet comprehensive, with no wasted sentences. Every section adds essential information.

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?

Despite lacking an output schema, the description explicitly lists the returned fields. It also covers error cases and usage context. For a simple fetch tool, this is fully complete.

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 100% so baseline is 3. The description enhances parameter semantics by providing examples (e.g., 'PAP-42' for issueId, 'cmt_abc123' for commentId) and clarifying their role, particularly that commentId is a UUID. This adds context beyond the schema's descriptions.

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 'Fetch a single comment by ID' with a specific verb and resource. It also distinguishes from sibling tool paperclip_list_comments by noting it is typically for the triggering comment from a wake event.

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?

Explicitly provides use cases: 'Use when: PAPERCLIP_WAKE_COMMENT_ID is set' and 'Don't use when: you need all comments on an issue — use paperclip_list_comments instead'. This clearly guides the agent on when to select this tool.

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 declare readOnlyHint=true, but the description adds that the endpoint is 'Board-only' and requires board-level auth (error 403), which is beyond what annotations provide. It also lists return fields and common errors, offering comprehensive behavioral insight.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Front-loaded with purpose and warning. Every sentence is informative and non-redundant.

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?

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: authentication requirements, parameter details, return fields, usage examples, and error handling. References sibling for list operation, ensuring full context for correct use.

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 baseline is 3. The description adds examples (companyId UUID), clarifies response_format enum values and defaults, and lists all return fields, thus providing meaningful extra context beyond the 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 'Get a single company by UUID', specifying the verb and resource. It distinguishes from sibling 'paperclip_list_companies' by explicitly stating when not to use and directing to the alternative.

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?

Provides explicit when-to-use examples ('reading a company's budget, status, or branding configuration') and when-not-to-use ('need to list all companies'), with a direct alternative. Also includes error handling guidance for auth and not found scenarios.

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 declare readOnlyHint=true, but description adds error handling details (401, 403) and return structure, which provides useful behavioral context beyond 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?

Description is concise with clear sections (Args, Returns, Examples, Error Handling). Only relevant information is included, no fluff.

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?

Given the tool is simple (1 param, no output schema), annotations cover safety, and description covers usage, examples, and errors, everything is complete for an agent to use correctly.

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 100% and parameter is well-described in schema with enum. Description adds context about default and purpose, but does not significantly extend beyond schema information.

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?

Description clearly states 'Get LLM token costs broken down by agent for the current company'. It uses specific verb+resource and distinguishes from sibling tools like paperclip_get_costs_by_project.

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?

Explicitly says 'Use when: identifying which agent is consuming the most budget this period' and 'Don't use when: you need project-level costs — use paperclip_get_costs_by_project instead', providing clear context and 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 declare readOnlyHint=true, so description is not required to reemphasize safety. The description adds useful behavioral context such as error codes (401, 403) and hints about authentication. However, it does not mention pagination or performance limitations, which could be added.

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 concise with clear sections (Args, Returns, Examples, Error Handling). Every sentence adds value, and the structure is easy to parse for an AI agent.

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?

Given the low complexity (one optional parameter, no output schema), the description fully covers return format and error handling. It provides enough context for correct invocation without requiring additional documentation.

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 100% and the schema already describes the parameter well. The description adds minor details like default value and output format human-readable vs structured, but does not significantly enhance meaning beyond the 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 tool retrieves 'LLM token costs broken down by project for the current company', specifying the verb, resource, and scope. It also distinguishes from the sibling tool paperclip_get_costs_by_agent by mentioning when not to use it.

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 'Examples' section explicitly states when to use ('comparing spend across projects') and when not to use ('need agent-level costs'), directing to the alternative tool paperclip_get_costs_by_agent. This provides excellent 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?

Annotations already declare readOnlyHint=true, and description adds return format details (object with total cost, breakdown) and error cases. No contradictions. Adds value beyond 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?

Description is concise with clear sections (Args, Returns, Examples, Error Handling). Every sentence adds value, no fluff.

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?

Despite no output schema, description explains return structure adequately. For a simple read-only tool with one parameter, the description is complete and self-contained.

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?

Only one parameter (response_format) with 100% schema coverage. Description repeats the enum values and defaults but adds little beyond schema. Baseline 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 clearly states the tool retrieves a rolled-up cost summary for the current company across agents and projects, and it differentiates from sibling tools like paperclip_get_costs_by_agent and paperclip_get_costs_by_project.

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?

Explicit when-to-use ('checking overall spend before requesting a budget override approval') and when-not-to-use ('need per-agent costs — use paperclip_get_costs_by_agent') with alternative tool named. Also includes error handling 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?

Annotations already declare readOnlyHint=true, and the description adds important behavioral context: it is board-only, requires a board API key, and includes error handling details for 401 and 404 cases. No contradictions with 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 well-structured with sections (Args, Returns, Examples, Error Handling), front-loads a warning icon for visibility, and every sentence adds essential information without 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?

For a simple read-only tool with one parameter and no output schema, the description fully covers return type, error handling, and usage context. It is sufficiently complete for an AI agent to invoke correctly.

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 100% with a well-described parameter, but the description adds the clarification that response_format is optional (despite schema marking it required) and reiterates the default. This adds value beyond schema, but the improvement is marginal.

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 returns the authenticated board user and session identity, with a specific verb 'Return' and resource 'board user'. It directly distinguishes itself from the sibling tool paperclip_get_me by specifying board user vs agent identity.

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 provides explicit 'Use when' and 'Don't use when' instructions, including a named alternative (paperclip_get_me), giving clear guidance on when to select this tool over siblings.

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 indicate readOnlyHint=true, and the description consistently describes a read operation ('return'). The description adds beyond annotations by detailing error scenarios (401, 403) and describing the return structure, which informs the agent of the tool's behavior without 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 description is well-structured with clear sections: purpose, args, returns, examples, error handling. It is front-loaded with the main purpose and each sentence adds value without redundancy. At multiple paragraphs, it remains efficient and scannable.

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?

Given the simple input schema (1 optional param with enum) and no output schema, the description is complete. It explains the return object's structure (goals array, projects array, etc.) and covers error cases, leaving no gaps for an agent to understand what the tool returns and when to use it.

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 input schema has 100% coverage with a description and enum for the single parameter. The description repeats the parameter enum and default but adds no additional semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate since the schema already documents the parameter sufficiently.

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 returns a 'company-level health summary' including specific components (goals, projects, issues, agent workload), using a specific verb ('Return') and resource ('dashboard'). It distinguishes from sibling tools like paperclip_list_issues and paperclip_get_issue by specifying it's a board-level overview.

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 provides explicit 'Use when' and 'Don't use when' guidance, naming alternative sibling tools (paperclip_list_issues, paperclip_get_issue). It also includes error handling instructions for authentication and permission failures, helping the agent decide when to use this tool.

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 declare readOnlyHint=true, so safety is clear. Description adds error handling details (401, 404) and return structure, which provides useful behavioral context beyond the annotation.

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?

Well-structured with sections for Args, Returns, Examples, Error Handling. Efficiently presents all necessary information without verbosity, though slightly expanded by examples and error details.

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?

Despite no output schema, description fully covers return structure, error handling, and usage examples. The tool is simple (3 params, read-only) and the description leaves no gaps in understanding its operation.

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 100%, so parameters are documented. Description provides example values (PAP-42, 'plan') and mentions return fields, but does not significantly add meaning beyond the schema's descriptions.

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?

Description clearly states 'Get the full content of a specific issue document by key,' with explicit verb, resource, and scope. It distinguishes from sibling paperclip_list_documents by specifying that to discover all keys, use that tool first.

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?

Provides explicit when-to-use ('reading the plan or notes document before writing an update') and when-not-to-use ('need all document keys — use paperclip_list_documents'), with an alternative tool named.

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 indicate readOnlyHint=true; description adds return structure details (fields) and behavior, no contradictions.

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?

Well-organized with sections: main sentence, Args, Returns, Examples, Error Handling. Each sentence is valuable and front-loaded.

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?

Covers purpose, parameters, return values, usage guidance, error handling, and distinguishes from siblings. No gaps given annotations and schema coverage.

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 100%, but description adds examples for issueId and key, and ties parameters to error handling scenarios.

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?

Clearly states 'Get the full revision history for an issue document.' Distinguishes from siblings like paperclip_get_document (current body) and paperclip_list_documents.

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?

Explicitly provides 'Use when' and 'Don't use when' with specific sibling references, plus error handling 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?

Annotations show readOnlyHint=true, consistent with fetch operation. Description adds key behaviors: board-only endpoint requiring board API key, specific error handling (401, 403, 404) with troubleshooting tips, which is beyond 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?

Well-structured with clear sections, but somewhat verbose with error handling details. However, all content is relevant and earns its place; front-loaded with purpose.

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?

Comprehensive for a read tool with no output schema: mentions return fields (traceId, events, metadata, related context), covers prerequisites (board-only, API key), and error handling. Sibling context is rich but tool is fully documented.

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 100%, baseline 3. Description adds example value ('ft_abc123') and clarifies default for response_format, providing minor added utility over schema alone.

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?

Description explicitly states 'Fetch the full bundle for a single feedback trace by its UUID', using a specific verb and resource. Among siblings, it distinguishes from list tools by targeting a single trace UUID.

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?

Clearly states when to use (retrieving complete payload) and when not (browsing traces, with explicit sibling alternatives paperclip_list_feedback_traces and paperclip_list_issue_feedback_traces).

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 declare readOnlyHint=true, description adds return fields and error codes. No 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?

Clear sections (Args, Returns, Examples, Error Handling). Concise and well-organized.

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?

No output schema, but description lists returned fields and error codes. Complete for a read 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 100% so baseline 3, but description adds context like UUID format, default output format, and examples.

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?

Clearly states it gets a single goal by UUID, including status and linked projects. Distinguishes from list tool.

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?

Explicitly provides when-to-use (reading goal status before creating issue) and when-not-to (use list_goals for discovery). Includes error handling 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?

Annotations already declare readOnlyHint=true; description adds context on returning a compact object with specific fields and error handling for 401 and 404. No contradictions. Fully discloses behavior beyond 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?

Description is well-structured with sections (overview, args, returns, examples, error handling) and uses bullet points. It is concise but includes necessary detail; no wasted sentences.

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?

Given no output schema, description sufficiently explains what is returned (compact context object with specific fields) and handles error cases. It is complete for a read-only tool fetching context.

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 100%, so baseline 3. Description adds an example for issueId but does not mention response_format. While schema describes response_format fully, description adds minimal extra value for 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 clearly states it gets a compact heartbeat context for an issue, listing specific components (state, ancestors, goal/project, comment cursor). It distinguishes from sibling tool paperclip_get_issue by noting when not to use it.

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?

Provides explicit when-to-use (orienting at start of heartbeat run) and when-not-to-use (if full issue needed, use paperclip_get_issue), giving clear guidance on tool selection.

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 declare readOnlyHint=true, so the bar is lower. The description adds behavioral context by specifying the return structure (array with fields like id, status, priority) and error handling codes (401, 404). This goes beyond the annotations 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?

The description is well-structured with clear sections (main sentence, Args, Returns, Examples, Error Handling). Every sentence is relevant and concise, with no fluff. It effectively front-loads the key purpose.

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?

Although there is no output schema, the description explains the return structure (array of assignments with specific fields) and covers error scenarios. For a simple read-only tool with one parameter, this provides sufficient context 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% for the single parameter (response_format), including its enum values and default. The description echoes this information but adds no additional meaning beyond what the schema provides. Baseline 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 clearly states 'Return the current agent's compact list of active issue assignments.' This specifies the verb (return), resource (active issue assignments), and scope (current agent). It also distinguishes from sibling tools like paperclip_get_issue and paperclip_list_issues by mentioning what it does not do.

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 includes explicit usage guidance: 'Use when: finding which issue to work on after waking from an @-mention' and 'Don't use when: you need full issue details — use paperclip_get_issue or paperclip_list_issues instead.' This provides clear context and alternatives.

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 provide readOnlyHint, but description adds extensive behavior: returns full details, ancestor chain, specific return fields, and error handling (401, 404). No side effects beyond read.

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?

Well-structured with clear sections (Args, Returns, Examples, Error Handling). Each sentence is necessary, no fluff. Front-loaded with main purpose.

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?

Fully covers parameters, return fields, usage guidance, and error cases. No output schema but description enumerates return fields. Complete for a read operation without complex side effects.

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?

Description adds useful context (default format, examples) but contradicts schema: schema marks response_format as required, description says '(optional)'. This inconsistency undermines agent understanding.

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?

Description uses specific verb 'Get' and resource 'issue', and includes 'by ID' and 'full details and ancestor chain'. Clearly distinguishes from list/inbox tools by mentioning 'a single issue'.

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?

Explicitly states 'Use when: reading a specific issue's full state before making changes' and 'Don't use when: you need a list of issues' with named alternatives (paperclip_list_issues, paperclip_get_inbox).

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 declare readOnlyHint=true, so the tool is known to be safe. The description adds detailed return field structure, error codes, and authentication requirements. No 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 description is well-structured with clear sections (Args, Returns, Examples, Error Handling), front-loading the key purpose. Every sentence adds value, and the formatting aids readability.

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 no output schema, but the description fully documents the return fields. With one optional parameter, clear usage guidance, and error handling, the description is complete for an agent to select and invoke correctly.

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 100% with description and enum for the single parameter. The description repeats this information and adds default value clarification, but does not add significant new meaning beyond the 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 explicitly states it returns the current agent's full identity record, and distinguishes from the sibling paperclip_get_agent for retrieving other agents. The verb 'return' and resource 'full identity record' are specific and clear.

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 provides explicit when-to-use examples (start of run, after @-mention) and when-not-to-use (need another agent's details), pointing to the sibling tool. It also includes error handling guidance for authentication and not-found cases.

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 declare readOnlyHint=true. Description adds details about return structure (nested tree) and error handling, providing value beyond 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?

Description is well-structured with sections for Returns, Examples, and Error Handling. Every sentence adds value without 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?

Given one parameter, no output schema, and informative annotations, the description covers purpose, usage, return format, and error scenarios sufficiently.

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 covers the single parameter response_format with description and enum. Description does not add extra meaning beyond what schema provides, so baseline score of 3.

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?

Clearly states it gets the full company agent hierarchy as an org chart, differentiating from the flat list sibling tool paperclip_list_agents.

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?

Explicitly includes 'Use when' and 'Don't use when' with a specific alternative sibling, guiding appropriate invocation.

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 indicate readOnlyHint=true, and the description adds important behavioral context: Board-only requirement, URL-encoding, and error handling details (404, 401, 403). No contradictions.

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 well-structured with sections: warning, Args, Returns, Examples, Error Handling. It is concise and front-loaded with essential information. Every sentence adds value.

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?

Despite no output schema, the description fully explains the return object fields and error handling. It is complete for a simple get tool, covering all necessary context.

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 100%, so baseline is 3. The description adds value by explaining URL-encoding for pluginKey, the default for response_format, and the structure of the returned object, which goes beyond the 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 it gets detailed information about a specific plugin by its key, using specific verbs and resource. It distinguishes from sibling tools like paperclip_list_plugins by specifying it's for a single plugin.

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 provides explicit when to use (inspecting a specific plugin before enabling) and when not to use (listing all plugins, use paperclip_list_plugins). It also includes error handling 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?

Annotations already indicate readOnlyHint=true, but the description adds valuable behavioral details: error handling for 401 and 404 status codes, and a clear listing of return fields. No contradiction with annotations; the description enhances 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?

The description is well-structured with clear sections (Args, Returns, Examples, Error Handling). It is concise, each sentence is meaningful, and the most important information is front-loaded.

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 read tool with two parameters and no output schema, the description is complete. It lists return fields, provides usage examples, and covers error handling. No gaps given the tool's complexity and the presence of rich 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?

Schema coverage is 100% and baseline is 3. The description adds extra value by providing an example UUID ('prj_abc123') for projectId and explaining the default and purpose of response_format, which goes beyond the schema's enum list.

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 'Get a single project by UUID, including its associated workspaces', specifying the verb (get), resource (project), and scope (single by UUID). It distinguishes itself from sibling tools like paperclip_list_projects by mentioning alternative use cases.

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?

Explicitly provides when to use ('reading project details or checking workspace cwd') and when not to use ('need a list of projects — use paperclip_list_projects'), along with an alternative tool name. This is excellent guidance for an AI agent.

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 declare readOnlyHint=true and destructiveHint=false. Description adds value by listing specific fields returned and error conditions (401, 404). It does not contradict 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?

Well-organized with sections (Args, Returns, Examples, Error Handling). No redundant sentences; every part adds value.

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?

Though no output schema, description explicitly lists return fields (id, name, triggers, etc.). Error handling covers authentication and not-found cases. Sufficient for a single-resource retrieval 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 already has 100% coverage with descriptions. Description adds example values and default for response_format, but this is marginal beyond schema content.

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 it retrieves a single routine by UUID, and specifies included data (triggers, recent runs). It differentiates from the sibling paperclip_list_routines which lists all routines.

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?

Explicitly provides when to use (inspecting triggers before modification) and when not to use (need all routine IDs, use paperclip_list_routines first). Includes example usage and error handling scenarios.

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