paperclip-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.1.1
Disambiguation5/5
Each tool targets a distinct operation on a specific entity (e.g., approval comments vs. issue comments; agent hire vs. agent create). The verb-noun naming clearly separates concerns, and even similar verbs (list/create/update/delete) are paired with unique nouns, reducing ambiguity.
Naming Consistency5/5
All 104 tools follow the consistent snake_case pattern 'paperclip_<verb>_<noun>' (e.g., paperclip_create_agent, paperclip_list_issues). There is no mixing of styles; even edge cases like 'upsert' follow the convention. This is exceptionally consistent.
Tool Count2/5
At 104 tools, the server is excessively large for a single MCP surface. While the domain (company management) is broad, this number of tools risks overwhelming an LLM and would benefit from being split into smaller, focused servers (e.g., agent management, issue tracking, approvals).
Completeness4/5
The tool surface covers an extensive range of operations across companies, agents, issues, projects, goals, routines, plugins, costs, and more. Minor gaps include missing delete operations for core entities like issues, goals, and projects, which agents may need.
Average 4.7/5 across 100 of 104 tools scored. Lowest: 4.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on April 17, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint: true and idempotentHint: true. The description adds error handling details (400, 401, 404) and notes that the updated agent object is returned. It does not contradict annotations but also does not significantly expand on behavioral traits beyond what the annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into sections: purpose, Args, Returns, Examples, Error Handling. It is front-loaded with the main purpose. Although it is a bit long, every section earns its place and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects) and no output schema, the description covers purpose, all parameters with examples, return type, error handling, and usage guidance. It does not detail the fields of the returned object, but otherwise is thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description reinforces these with a structured Args list that includes examples (e.g., 'example: agt_abc123' for agentId). This adds minor extra value but is not essential.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb+resource: 'Update an agent's name, title, capabilities, status, heartbeat, runtime, or adapter config.' It lists the specific updatable fields and includes an examples section that distinguishes it from the sibling tool paperclip_update_agent_permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (e.g., adjusting heartbeat interval or capabilities) and when not to use (updating permissions, with a direct reference to paperclip_update_agent_permissions). This provides clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the bar is lower. The description adds '⚠ Board-only' (required API key type) and error handling details (401, 403), which enrich transparency beyond annotations. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with sections (Args, Returns, Examples, Error Handling), but somewhat lengthy. Every sentence adds value, though it could be more concise by omitting redundant schema details. Good front-loading of key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 pagination envelope and field names, filling the gap. Error handling covers auth and permission scenarios. Missing details like rate limits, but adequate for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description repeats the enum values for status and defaults for limit/offset/response_format, adding no new semantic meaning beyond what the input schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List installed plugins for the Paperclip instance', specifying a concrete verb and resource. It distinguishes from siblings like paperclip_get_plugin by noting the optional status filter and referencing the alternative for full detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 guide the agent: use for auditing or filtering by error status, avoid when full plugin detail is needed (referring to paperclip_get_plugin). This is exemplary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, but description adds context: board-only requirement, returns agent object, and lists error handling 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Front-loaded the board-only warning. Each sentence adds value, though slightly verbose in error handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return value, authentication, permissions, and error cases. No output schema, but description explains what is returned. Missing mention of whether rollback is reversible, but annotations cover destructive nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters (agentId, revisionId) with descriptions. Description repeats parameter info but adds example values, which is helpful but not essential beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Roll back an agent's config to a specific previous revision' with a specific verb ('roll back') and resource ('agent config'). It also distinguishes from sibling tools by mentioning 'use paperclip_update_agent instead' for targeted edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (reverting bad config that broke heartbeat) and when-not-to-use (targeted edits), including alternative tool. Also indicates board-only access and required API key permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (destructiveHint=false, openWorldHint=true) are consistent. Description adds error handling details (400, 401, 403), return format, and auth requirements. It doesn't mention reversibility or side effects, but overall provides good 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for warning, args, returns, examples, and error handling. Front-loaded with important board-only warning. No redundant or unnecessary sentences; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a tool with no output schema: describes return object, error codes, and parameter details. Distinguishes from sibling tools. Could add more about version validation but error section covers npm errors adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 explaining that packageName can be a local filesystem path when isLocalPath is true, and that version is optional. However, this mostly restates schema descriptions without significant new insight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the tool installs a plugin from npm into Paperclip instance. It specifies 'board-only' access and distinguishes from sibling tools like paperclip_enable_plugin for reactivating disabled plugins. The verb 'install' and resource 'plugin' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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' statements, including a sibling tool alternative (paperclip_enable_plugin). Also mentions the tool requires a board API key. This gives clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, but description adds value by detailing return format (pagination envelope with DocumentStub[]), mentioning body not included, and listing 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections (Args, Returns, Examples, Error Handling) and is concise at around 100 words. Every sentence adds useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 parameters and no output schema, the description explains pagination, return structure, and error handling. Could clarify that default values exist, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description's Args section only repeats parameter names and adds an example for issueId, adding marginal value beyond schema's existing descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all documents attached to an issue, using specific verb 'list' and resource 'documents attached to an issue'. It distinguishes from siblings like paperclip_get_document by noting it returns only keys, not body.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('discovering which document keys exist') and when-not-to-use ('already know the key – use paperclip_get_document directly') are provided, giving clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's mention of board-only scope and error handling (auth, permissions) adds useful context beyond annotations. It also describes the pagination envelope. 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.
Conciseness4/5
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 sufficiently detailed without being overly verbose, though some parameter repetitions could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 11 parameters and no output schema, the description comprehensively covers returns (pagination envelope), error handling (401, 403, 404), and filtering options. It provides complete context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning beyond what the schema already provides; it essentially repeats the parameter descriptions and examples. Therefore, no extra value for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists feedback traces scoped to a single issue with optional filters. It distinguishes from the sibling paperclip_list_feedback_traces by specifying scoping, and the 'Don't use when' section explicitly differentiates usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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' examples, including a direct reference to the alternative sibling tool paperclip_list_feedback_traces. This gives clear guidance on when to invoke this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint true, but the description adds specific behavioral details: cursor-based streaming, no pagination envelope, board-only auth requirements, and error codes with causes (401, 403, 404). This adds significant 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (header, args, returns, examples, error handling) but is somewhat lengthy; still, the information is efficiently organized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 covers the return shape (array with seq, type, data, createdAt), error handling, auth requirements, and a clear alternative tool. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal additional meaning. It restates defaults and examples but does not provide novel parameter details beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for streaming events for a heartbeat run using a cursor, distinguishing it from raw log retrieval via paperclip_get_run_log. The verb 'stream events' and resource 'heartbeat run' are specific, and the not-paginated cursor-based nature is emphasized.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 a named alternative (paperclip_get_run_log), plus board-only requirement and error handling conditions provide clear context for when this tool should and should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint and idempotentHint. Description adds that a comment can be attached and returns the updated issue. It does not mention dependencies like checkout lock, but error handling covers invalid state transitions. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose, args, returns, examples, and error handling sections. Front-loaded with key info. Slightly long due to 15 parameters, but each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 parameters, no output schema, and annotations present, the description covers all aspects: purpose, all params, return value, usage examples, and error handling. Fully adequate for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description repeats parameter details from the schema. While the description lists params clearly, it adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update one or more fields on an issue; optionally attach a comment in the same call.' This provides a specific verb and resource, and distinguishes it from sibling tools like paperclip_add_comment by allowing inline comment attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Don't use when' examples, referencing paperclip_checkout_issue for claiming issues. Also provides error handling guidance suggesting alternative tools like paperclip_list_issues and paperclip_get_issue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds specifics like error codes and return value details, but does not contradict annotations. Slightly enhanced transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Slightly redundant with schema but overall efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete coverage: lists all updatable fields, returns updated object, error codes, and alternative tool for triggers. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented. The description repeats these with an example UUID but adds minimal extra meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a routine's title, description, or scheduling policies.' The verb 'Update' and resource 'routine' are explicit, and it distinguishes from sibling tools 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Don't use when' sections, referencing the sibling tool paperclip_update_routine_trigger for trigger changes. Error handling is also provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the return object (updated workspace with id, cwd, repoUrl, updatedAt) and error codes (401, 404), providing behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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-loads the 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.
Completeness4/5
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 object. It covers parameter details, usage example, and error handling. It could be slightly more explicit about prerequisites (e.g., workspace must exist), but overall sufficiently complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description repeats parameter descriptions and adds example values (e.g., 'prj_abc123'), but does not significantly enhance understanding beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a workspace's cwd or repoUrl', specifying both the resource (workspace) and the action (update). It explicitly differentiates from the sibling tool paperclip_create_workspace by stating when not to use it. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage examples ('Use when: updating the workspace path after the repo was moved') and a clear exclusion ('Don't use when: you need to create a new workspace — use paperclip_create_workspace instead'). It also lists error handling scenarios, guiding the agent on troubleshooting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness3/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true. The description adds pagination details (max 50 per page) and specific error codes (401, 404) which are beyond the annotation. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with a one-line summary. It efficiently covers Args, Returns, Examples, and Error Handling without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with pagination and 4 parameters, the description is complete: purpose, parameters, return format, usage examples, error handling, and cross-references to related siblings. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear descriptions for all 4 parameters. The description adds a concrete agentId example and mentions the pagination limit, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the config revision history for an agent.' It uses a specific verb and resource, and distinguishes itself from the sibling tool paperclip_rollback_agent_config by explicitly saying 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Examples' section explicitly provides when to use (auditing, finding revisionId) and when not to use (for rollback, use paperclip_rollback_agent_config). Error handling further guides on authentication and agent ID verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return format (pagination envelope) and states it returns up to 50 skills per page. Error handling adds context. Annotations already declare readOnlyHint, so description adds useful detail 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one-line intro, structured return, usage examples, and error handling. No wasted words, each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with pagination, the description covers purpose, when to use, return structure, and common errors. No missing elements given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already describes parameters. Description does not repeat parameter details but reinforces pagination behavior (up to 50 skills per page). Adequate but no significant added value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all skills installed at the company level', using a specific verb and resource. It distinguishes from sibling tool paperclip_get_agent by 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.
Usage Guidelines5/5
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' with a named alternative (paperclip_get_agent). Also includes error handling tips for authentication and permission issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond readOnlyHint annotation by specifying authentication errors (401, 403) and the board-only restriction (requiring human-user API key). It also outlines the return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (warning, args, returns, examples, error handling). It is concise with no redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 specifies the return type (array of descriptors with fields) and covers error handling. The tool is a simple list operation, and the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter response_format is fully described in the input schema (100% coverage). The description repeats this information without adding meaningful extra semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'list', the resource 'example plugins', and the purpose 'for reference'. It distinguishes itself from sibling tool paperclip_list_plugins by noting 'available...that can be installed' vs. installed plugins.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear guidance is provided with explicit 'Use when' and 'Don't use when' sections, including a recommendation for the alternative (paperclip_list_plugins). Also includes a board-only requirement warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true. Description adds pagination envelope details, error codes, and return fields, providing 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with purpose, returns, examples, and error handling sections. Each sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 return format (pagination envelope with fields) and error conditions, making it self-contained for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already documented. The description does not add significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all routines defined for the current company' and distinguishes itself from the sibling `paperclip_get_routine` by explicitly stating 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.
Usage Guidelines5/5
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' sections, names the alternative tool, and includes error handling guidance for common HTTP status codes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds that secret values are never returned and explains error conditions, but could provide more insight into pagination behavior or outcomes beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Front-loaded with important caution about secrets. Every sentence is informative and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely covers the tool's purpose, parameters, return format (pagination envelope with field list), usage guidelines, and error scenarios. No missing context for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description repeats these but adds no additional semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists secrets for a company and returns only metadata. It distinguishes from siblings like rotate/update by specifying the action and never returning secret values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use cases (auditing, checking metadata) and when not to use (rotate/update) with specific tool names. Also includes error handling guidance for auth and permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. Description adds that it returns updated approval with status 'rejected' and timestamp, plus error codes. Does not mention reversibility or side effects, but sufficient given annotation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, examples, and error handling. Every sentence is useful and no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return value and covers error codes. Provides complete context for a mutation tool with given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds example values and clarifies 'reason' is human-readable. Does not add substantial meaning beyond schema, but consistent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it rejects a pending approval request with an optional reason. Specifically mentions 'board-only' and distinguishes from revision tool. Verb+resource is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 alternative tool (paperclip_request_revision). Also specifies API key requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so description does not need to repeat that. It adds value by detailing error conditions, validation requirements (costCents ≥0, valid ISO 8601), and the return structure. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with clear sections (Args, Returns, Examples, Don't use when, Error Handling). Each sentence adds unique value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-required-parameter tool with no output schema, the description covers all necessary aspects: purpose, parameters, return fields, usage guidance, and error handling. It is complete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. Description adds examples for some fields (agentId, provider, model, occurredAt) and clarifies constraints (non-negative cost, integer tokens). This provides marginal extra value, justifying a score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it reports token usage and cost events for budget tracking, with examples. Distinguishes from sibling tools like paperclip_get_cost_summary and paperclip_get_costs_by_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (recording a completed LLM API call) and when not to use (for cost summary, use alternatives). Provides error handling guidance for 400 and 401 errors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by detailing error codes (401, 404, 409) and return object fields (id, routineId, status, startedAt). Annotations already indicate non-destructive and non-open-world, so the description augments with precise runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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. Information is front-loaded and each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters and no output schema, the description fully covers behavior, error scenarios, return structure, and examples. It is complete and leaves no ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already has 100% coverage with descriptions. The description restates these and adds an example for routineId, but does not provide significant new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers a routine run immediately, bypassing its schedule. It uses specific verbs ('trigger', 'run') and distinguishes from sibling tools like paperclip_list_routine_runs for checking past runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 guide the agent, naming the alternative tool (paperclip_list_routine_runs). Error handling also advises on verification steps, providing clear context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. Description adds return object details and common error codes, but could further clarify consequences of updating a schedule on ongoing tasks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, args, returns, examples, error handling). Front-loaded and no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 annotations, the description adequately covers purpose, usage context, return object, and error handling. It explains optional parameters and gives concrete examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so description adds limited new semantic value. It provides examples for triggerId and cronExpression, but these are minor additions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the verb 'Update' and resource 'routine trigger', specifying what can be changed (kind or cron schedule). Differentiates from siblings by providing an explicit alternative for adding triggers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete examples of when to use (changing a schedule) and explicitly advises against using for adding new triggers, pointing to the sibling tool paperclip_add_routine_trigger. Error handling further guides correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, so the description adds value by detailing pagination, filtering, and error responses. It does not discuss rate limits or other side effects, but overall adequately 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with separate sections for purpose, arguments, returns, examples, and error handling. It is not overly verbose, though some sections could be slightly condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 fully explains the return envelope and item fields. Together with error handling and usage guidance, it provides a complete picture for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 useful context: status is comma-separated with an example, and response_format details are clear. This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists approval requests for the current company, using specific verbs and resources. It distinguishes itself from the sibling tool paperclip_get_approval 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use scenario (scanning pending approvals before escalation) and when-not-to-use (for single approval details, use paperclip_get_approval). Error handling also provides guidance on authentication and permission issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures include board-only auth requirement, pagination behavior, error handling (401, 403), and return format options. Annotations already indicate readOnlyHint, so 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for purpose, parameters, returns, examples, and error handling. A bit lengthy but each part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering 5 parameters, no output schema, and many siblings, the description covers all essential aspects: purpose, usage, parameters (with examples), return envelope, error codes, and alternative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions are already comprehensive. The tool description adds examples and context but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List heartbeat runs' with specific resource and filtering options. It distinguishes from sibling 'paperclip_list_run_events' 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (auditing runs, diagnosing failures) and when not to use (raw event stream) with alternative tool named. Also warns about board-only access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, and description adds details on pagination envelope, result limits, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for Args, Returns, Examples, Error Handling. However, it redundantly restates parameter descriptions that are already in the schema, slightly reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a list tool with many filters and pagination. Describes return format (pagination envelope) despite no output schema. Includes error handling and practical examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage; description repeats most parameter descriptions verbatim but adds example values and usage context like comma-separated status. Does not significantly enhance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List issues for the current company with filtering and pagination.' Distinguishes from sibling 'paperclip_get_issue' which retrieves a single issue. Verb+resource+scope are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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' examples, including the alternative tool name. Also covers error handling for common auth/permission issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=true; description adds return pagination envelope structure and error handling (401, 403) which inform agent behavior. Could mention ordering or scope beyond 'current company' but still 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured with clear sections (Args, Returns, Examples, Error Handling) but includes some redundancy (e.g., 'List all projects' and then 'Returns...'). Could be slightly tighter but is well organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description provides full return envelope structure. Includes error handling and usage examples. All parameters are described in schema, and description adds extra usage guidance. 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters 100%, but description adds context like response_format meaning and default, and explains the pagination envelope (which is not in input schema). This compensates for missing output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists projects for the current company, with specific verb 'list' and resource 'projects'. It distinguishes from siblings like paperclip_get_project (single project) and paperclip_list_workspaces (workspaces vs projects) via the 'Don't use when' example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' (finding projectId to link issues) and 'Don't use when' (needing workspaces, with alternative tool names). This differentiates from many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds the critical behavioral nuance that board-level authentication is required and agent keys are rejected (403). Error codes (401, 403, 404) are listed. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with distinct sections (warning, args, returns, examples, error handling). Every sentence adds value. Could be slightly more concise, but the organization aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains the return value ('updated company object with all fields and updated timestamps'). Covers authentication, error handling, parameter nuances, and usage context. Complete for a 4-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, so baseline is 3. The description adds value by providing example UUID, clarifying nullable description to clear, and stating budgetMonthlyCents must be a non-negative integer. These details enrich parameter understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update a company's name, description, or monthly budget', specifying verb and resource. Distinguishes from paperclip_archive_company by explicitly recommending it for archiving instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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' sections, naming an alternative tool (paperclip_archive_company) and noting the 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and idempotent behavior. Description adds significant context: board-only requirement, return format (value never returned), error handling. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for args, returns, examples, error handling. Front-loaded with key caveats. While detailed, every sentence serves a purpose; slight room for trimming but not excessive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a metadata update tool: covers purpose, usage boundaries, parameter details, return shape (despite no output schema), and error handling. Fully prepares the agent for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% with descriptions. Description restates parameter roles and notes null clears, but adds minimal new semantics beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates secret metadata (name, description, externalRef) and explicitly distinguishes from rotating the secret value. The verb 'update' and resource 'secret metadata' are specific, and it differentiates 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (renaming, updating description/reference) and when-not-to-use (changing value, directing to paperclip_rotate_secret). Also includes error handling guidance for 404, 401, 403 with actionable next steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=false, but the description adds valuable behavioral context: it creates a heartbeat run record, returns status, and handles conflicts (409). It also mentions prerequisites like wakeOnDemand config. 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.
Conciseness5/5
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 yet comprehensive, with no redundant sentences. Every sentence adds value for tool selection and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having only one parameter and no output schema, the description is complete: it covers when to use, error handling, return format, and prerequisites. This provides sufficient context for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description 'Agent UUID' for agentId. Description repeats this and provides an example ('agt_abc123') but does not add new semantic meaning beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Manually trigger an on-demand heartbeat run for an agent.' It uses a specific verb ('trigger') and resource ('heartbeat run'), and differentiates from siblings like paperclip_wakeup_agent and paperclip_list_heartbeat_runs by specifying manual on-demand invocation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Don't use when' sections, directing to paperclip_update_agent for agents with heartbeat disabled, and paperclip_list_agents for validation. Error handling also suggests alternative tools (e.g., paperclip_list_agents for 404). This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint), the description details pagination behavior, return envelope structure, and error codes. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise paragraphs: purpose, return format, usage guidance with errors. No wasted words, front-loaded key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a list tool: explains return shape, pagination limits, and error conditions. No output schema is needed given the thorough textual description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no additional parameter semantics beyond the schema, but is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists agents in the current company. Examples provide specific use cases and differentiate from similar tools like paperclip_get_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 guide the agent to appropriate contexts, including a direct sibling alternative (paperclip_get_agent). Error handling adds further clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds detailed return structure (pagination envelope) and error handling (401, 404) beyond the readOnlyHint annotation. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise and well-structured: purpose, Args, Returns, Examples, Error Handling. Every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all necessary aspects: return format, pagination, error codes, and usage examples. No output schema required since return is explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with good descriptions. The description does not add extra semantic details for parameters beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List comments on an approval request' with a specific verb and resource. It distinguishes itself from siblings like 'paperclip_add_approval_comment' and 'paperclip_get_approval'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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_get_approval for status, type, and payload'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds return format details (pagination envelope with fields), error handling (401, 404), and explains output format options. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: brief intro, Args table, Returns, Examples, Error Handling. Each section adds value without redundancy. Information is well-organized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully documents return structure (pagination envelope, item fields). Covers error cases and parameter constraints. Provides context for when to use, making it self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 param info but incorrectly states limit, offset, response_format are optional when schema marks them required. This misleads about parameter optionality. Adds example value for approvalId, which is helpful, but the error reduces reliability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists issues linked to a specific approval request. Uses specific verb 'List' and resource 'issues linked to approval', distinguishing it from generic list_issues and get_approval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use-case examples: 'Use when inspecting which issues are gated on a pending approval before deciding to approve or reject' and 'Don't use when you need approval metadata — use paperclip_get_approval instead'. Offers clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds behavioral details about pagination (has_more, next_offset) and error handling (401, 403), which are beyond the annotations. 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.
Conciseness5/5
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 without unnecessary verbosity, using bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 fully documents the return structure (pagination envelope with fields) and error handling. All parameters are explained. This is complete for a list tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds slight extra context like 'markdown (default, human-readable)' and 'json (structured)', but essentially matches the schema. Not significantly beyond.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all labels defined for the current company', which is a specific verb-resource combination. It is distinct from sibling tools like 'paperclip_create_label' by indicating it is a listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance with 'Use when: bootstrapping the label taxonomy...' and 'Don't use when: you already have the label UUID...', giving clear when-to-use and when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, consistent with listing historical runs. Description adds pagination envelope details, error handling (401, 404), and return structure. Contradiction: false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with Args, Returns, Examples, Error Handling sections. No wasted words, all sentences add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains pagination envelope and item fields. Also covers error handling. Complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds minimal extra value beyond parameter descriptions. It clarifies routineId format and response_format options, but baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists historical runs for a routine, ordered most-recent first. It distinguishes from siblings like paperclip_list_routines (lists routines) and paperclip_get_run_log (likely retrieves a single run log).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use-case example: 'auditing whether a scheduled routine has been firing and completing successfully'. Explicit don't-use case: 'need routines triggers or settings — use paperclip_get_routine instead'. Excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. Description adds pagination envelope details and error codes, which are useful beyond annotations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (header, args, returns, examples, error handling). Concise with no wasted words, front-loaded with main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without output schema, description specifies the pagination envelope and item fields. Covers all parameters, return format, and error scenarios. No gaps for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 example UUID for projectId, explanation of response_format enum, and return structure details. Exceeds basic schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all workspaces for a project' and provides specific use cases (finding workspace cwd or repoUrl). It distinguishes from sibling 'paperclip_get_project' which includes workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('finding the workspace cwd or repoUrl') and when not to use ('need the project record — use paperclip_get_project'). Includes error handling guidance for 401 and 404 responses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explains the effect of pausing (prevents new heartbeat runs, sets status to paused) and returns updated agent object. Annotations already indicate idempotent and openWorldHint false, which are consistent. Could mention that already running heartbeats are unaffected, but overall clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with sections (Args, Returns, Examples, Error Handling), front-loaded main purpose, no unnecessary words. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with one parameter and no output schema, the description covers purpose, usage context, alternatives, error handling, and return value. Complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with description 'Agent UUID'. Description adds value with example format 'agt_abc123' and context of use, but schema already describes the parameter adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'pause' and resource 'agent', with specific effect 'preventing it from starting new heartbeat runs'. It distinguishes from sibling tools like paperclip_terminate_agent and paperclip_resume_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit examples: when to use ('temporarily stopping a runaway or misconfigured agent during incident response') and when not to use (for permanent stop, use paperclip_terminate_agent). Also includes 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses that the tool modifies state (clears executionRunId) and returns the updated issue object. Error handling details (401, 404, 409) add transparency beyond annotations, though no destructiveHint is explicitly given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections for args, returns, examples, and error handling. No unnecessary text; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple release operation with one parameter and no output schema, the description covers purpose, usage, errors, and return value completely, enabling correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter. Description adds example value ('PAP-42') and context for verification with list_issues, enriching the parameter's semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool releases a checked-out issue back to the board without marking it done, which is a specific verb+resource. It distinguishes from siblings like paperclip_checkout_issue and paperclip_update_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Don't use when' guidance, naming alternative tool paperclip_update_issue for marking done. Also provides error handling steps, making usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true. Description adds details about authentication requirements (board-only) and error handling, beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, Examples, Error Handling) and is concise with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description includes return value details and error codes, making it complete for a mutation tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description adds example values and clarifies the 'path' parameter's role (null to clear). This adds moderate value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set or clear the AGENTS.md instructions file path for an agent.' It distinguishes from sibling tool paperclip_update_agent 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.
Usage Guidelines5/5
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' sections, and mentions that a board API key is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the tool modifies agent skills (adding/removing), which aligns with the destructiveHint annotation. It also details return values (added[], removed[], current[]) and error codes, adding 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with Args, Returns, Examples, and Error Handling sections. Every sentence is informative and front-loaded with the core purpose. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (sync operation), the description covers necessary context: prerequisites (agent ID), proper usage, error scenarios, and return format. It also references a sibling tool for checking, making it self-contained for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value with examples (e.g., 'example: agt_abc123', skill list example) and clarifies that desiredSkills must be valid skill names. This enhances understanding beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Sync' with resource 'agent's installed skills to match the desired list, adding or removing as needed.' This distinguishes it from sibling tools like paperclip_get_agent, which is for checking only. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 provide clear context for when to invoke this tool versus alternatives. Additionally, the error handling section guides the agent on common failures and resolutions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. Description adds error handling (401, 404) and return format (updated project object), but does not mention side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is front-loaded with purpose, structured into Args, Returns, Examples, Error Handling sections, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, description explains return value and includes error handling. It is fully sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description adds value with examples (e.g., 'prj_abc123', 'archived'), marks optional parameters, and clarifies status meaning (e.g., active, archived).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states verb 'Update', resource 'project', and lists the specific fields (name, description, status). It clearly distinguishes from sibling tool 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit 'Use when' (archiving, renaming) and 'Don't use when' (update workspace settings) examples, naming the alternative tool paperclip_update_workspace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds 'Non-mutating — no changes are applied' and explains that if source.type is 'github', the API fetches external content. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer but well-organized into sections (Args, Returns, Examples, Error Handling). It is slightly redundant with schema info, but the structure aids readability. Could be more concise, but earns its sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 format (JSON with fields). Error handling covers common HTTP codes. The description also mentions the sibling tool for applying. All necessary context is present for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well documented. The description adds integration context: e.g., target.companyId must match top-level companyId, collisionStrategy enum meanings, selectedFiles as a subset. This adds meaning beyond the schema, though schema already does heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Preview company import' and specifies that it's for inspecting what an import would change without applying. It distinguishes from the sibling tool 'paperclip_apply_company_import' by noting that preview is for inspection, not application.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when to use: 'inspecting what an import would change before committing'. Explicit when not to use: 'if you want to immediately apply — call paperclip_apply_company_import directly'. Also notes that preview is optional but recommended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: rotation increments version, previous versions remain valid unless purged, value is stored encrypted and never returned. It also notes the need for a board API key, which is not in annotations. No contradiction with destructiveHint=true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (warning, args, returns, examples, error handling) and is front-loaded with the core purpose. While fairly long, most sentences add value. Could be slightly more concise, but still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive action with 3 parameters and no output schema, the description covers purpose, usage, parameters, return behavior, error handling, and alternatives. It provides sufficient context for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing a baseline of 3. The description adds extra meaning: it explains that the 'value' parameter increments the secret version, and 'externalRef' is an updated external reference after rotation. It also describes the return metadata including incremented latestVersion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: rotating a secret's value and incrementing its version. It distinguishes from the sibling tool 'paperclip_update_secret' by specifying when not to use it. The verb 'rotate' and resource 'secret' are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidelines are provided, including when to use (rotating compromised or expiring credentials) and when not to use (renaming or updating metadata, with a pointer to paperclip_update_secret). Error handling instructions for 404, 401, 403 are also given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true, which are consistent with an update. The description adds value by stating the return behavior (returns the updated goal object) 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: main action, args with examples, return type, usage examples, and error handling. Every sentence adds value with no fluff. Approximately 10 lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All necessary information for an update tool is covered: parameters are fully documented, examples are given, error handling is included, and return type is mentioned. No gaps given the context signals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds meaningful examples (e.g., goalId 'gol_abc123', status 'completed'), clarifies that description supports markdown, and explains the format of each parameter beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a goal's title, description, or status' and distinguishes itself from the sibling 'paperclip_create_goal' in the usage guidelines. The tool name is self-explanatory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are provided: 'Use when: closing a completed goal or updating its description after a planning session' and 'Don't use when: you need to create a goal — use paperclip_create_goal instead'. Error handling for 401 and 404 is also included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds context about the byte-offset cursor, non-paginated nature, board-only restriction, and authentication requirements, complementing annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into clear sections (Args, Returns, Examples, Error Handling) with no redundant information, each sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All aspects—purpose, usage, parameters, return format, error codes, and continuation mechanism—are covered; no gaps given the tool's simplicity and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), but the description explains each parameter's purpose, provides examples, and clarifies the return object structure, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'read' and identifies the resource as 'raw log bytes for a heartbeat run', and explicitly distinguishes from sibling tool paperclip_list_run_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('reading raw execution log output for a heartbeat run') and when-not-to-use ('need structured events — use paperclip_list_run_events instead'), including error handling guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds pagination details, output format options, response structure (pagination envelope with item fields), and error handling (401, 404). 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.
Conciseness5/5
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 concise yet covers all necessary details without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description fully explains the return format: 'Pagination envelope { items: Attachment[], total, count, offset, limit, has_more, next_offset }' and item fields. Error handling is also covered. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. However, the description adds value by explaining the response structure and pagination behavior, which is not in the schema. It also provides examples and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all attachments on an issue', specifying the verb and resource. It distinguishes itself from sibling tools like paperclip_download_attachment and paperclip_delete_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use when: discovering attachment IDs before downloading or deleting a file' and 'Don't use when: you already have the attachment UUID — use paperclip_download_attachment directly'. This provides clear when-to-use and when-not-to-use with an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true), the description reveals behavioral traits like the client-side workaround for the broken server-side after parameter, error handling for 401, 404, 500, and the behavior of the total field when after is used. This adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: main sentence, arguments, returns, examples, error handling. It is front-loaded and every sentence adds value without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, pagination, cursor-based fetching), the description covers purpose, parameters, return envelope, examples, and error scenarios. No output schema exists, but the return format is described adequately. It is sufficiently 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.
Parameters4/5
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 extra context: explains the after parameter's workaround, the behavior of total with after, and provides examples of usage. This merits a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists comments on an issue, with optional cursor-based incremental fetching. It distinguishes from sibling tools like paperclip_get_comment (single comment retrieval) and paperclip_add_comment (adding comments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (reading new @-mention comments using the after cursor) and when-not-to-use (for a single comment by ID, use paperclip_get_comment). This directly guides the agent in tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint true, and description adds board-only restriction, pagination details, and error cases. No contradictions; adds significant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded warning, and concise sentences. Every part adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains return structure (pagination envelope with fields). Covers error handling, examples, and usage guidance completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, so baseline 3. Description repeats schema details but adds examples and context like output format and pagination envelope, earning a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all companies accessible to the authenticated board user, with specific verb and resource. Differentiation from paperclip_get_company is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (discovering all companies) and when not to use (if companyId known, use get_company). Also includes error handling for authentication issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=true, and the description adds behavior traits like pagination details (limit, offset, has_more, next_offset), default output format, and error handling for 401 and 403. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for args, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with three parameters and no output schema, the description thoroughly covers pagination behavior, return envelope, examples, and error handling, making it fully self-contained 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.
Parameters4/5
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 usage context like 'human-readable' for markdown and explicit range 1–100 for limit, but does not go beyond what the schema already documents for all three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all goals for the current company' with a specific verb and resource, and distinguishes from the sibling tool paperclip_get_goal for single goal retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Use when: finding the goalId to link when creating a new issue or project' and 'Don't use when: you need a single goal's full details — use paperclip_get_goal instead'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses board-only usage, required API key, and error handling for various HTTP statuses. Annotations (destructiveHint=false) are consistent; description adds significant context about state changes and permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 no unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return value and status. Covers error codes, required auth, and state constraints. Adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. Description adds example for approvalId format and clarifies feedback as optional, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it requests a revision on a pending approval, returning it to the requester. Distinguishes from sibling 'paperclip_reject' by explicitly saying 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases (e.g., a hire proposal before board approval) and when not to use (outright denial, use paperclip_reject). Also mentions board-only requirement and API key needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavior: returns updated approval with status 'pending', error codes (401, 404, 422) and their meanings. Annotations show destructiveHint false, which is consistent. 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.
Conciseness5/5
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. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 value. It covers prerequisites, state checks, and error scenarios. For a simple two-parameter tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The description adds an example format for approvalId ('apr_abc123') and clarifies that comment is optional and its purpose. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Resubmit an approval request after addressing revision feedback', specifying the verb and resource. It distinguishes from siblings like paperclip_approve, paperclip_reject, and paperclip_request_revision by focusing on resubmission after revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Don't use when' examples, directing to check status with paperclip_get_approval first. Error handling also guides on state mismatches, providing clear context for when to use this tool vs. others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return type (updated agent object with status set to active), error handling codes (401, 404, 422) with corrective actions, and prerequisite state (agent must be paused). No contradictions with annotations (idempotentHint is reasonable).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive with clear sections (Args, Returns, Examples, Error Handling). Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple tool: covers input, output, usage guidance, and error scenarios. No output schema needed as return is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers param fully (100% coverage). Description adds an example value ('agt_abc123') and links param to error conditions, providing helpful context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool resumes a paused agent, using specific verb and resource. It effectively distinguishes from sibling tools like pause_agent or terminate_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases ('re-enabling an agent after pausing it for maintenance or incident response') and when not to use ('if the agent is not paused'), with guidance to check status first using another tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the destructiveHint annotation: the token used for the call is immediately invalidated, and it includes specific error codes (401, 404) and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, with a clear warning, return value, usage 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, destructive annotation, and no output schema, the description fully covers the tool's behavior: what it does, side effects, return format, error handling, and usage constraints. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description correctly avoids adding parameter details, as none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool revokes the current board session token, specifying 'Board-only' and differentiating from checking login status. The verb 'revoke' and resource 'current board session' are clear and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('logging out a board session after completing administrative tasks') and when-not-to-use ('check who is logged in — use paperclip_get_current_user'), directly referencing a sibling tool. The 'Board-only' note further clarifies context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds irreversibility, return value details, and authentication requirements (board API key) beyond the destructiveHint annotation. No contradictions observed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence contributes value. Organized into clear sections (Args, Returns, Examples, Error Handling) with a warning emoji for emphasis. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single required parameter, no output schema, the description fully covers return value, error scenarios, and usage constraints. It's complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description for agentId. Description adds an example value ('agt_abc123') and confirms it's a UUID, providing extra context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'permanently deactivate an agent' with an irreversible action. It distinguishes from siblings like paperclip_pause_agent by emphasizing permanence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
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 provide clear context, directing the agent to paperclip_pause_agent for temporary stops. Error handling codes are also detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=false, and the description adds valuable behavioral context: it returns the created attachment record with fields, and lists specific error codes (400, 401, 404, 413) with explanations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: one-sentence summary, clear args list, returns, examples, and error handling. It is front-loaded with the core action and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, no nested objects, and good annotations, the description fully covers the tool's behavior, usage, error handling, and return format. It is complete for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented in schema. The description adds value by providing examples, clarifying defaults (e.g., filename defaults to basename), and requiring absolute paths. However, the schema already covers the meaning, so slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Upload a local file as an attachment to an issue.' It distinguishes from sibling tools like paperclip_download_attachment by explicitly stating 'Don't use when: you need to download an attachment — use paperclip_download_attachment instead.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('attaching a generated report, diff, or log file') and when-not-to-use ('need to download an attachment'). It also includes error handling guidance (e.g., check filePath exists, verify issue ID) that helps the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly covers behavior: returns a run object or { status: 'skipped' } if already running/paused, explains idempotency and forceFreshSession, and provides detailed error handling for 401, 404, 409. This goes well beyond the minimal annotations (destructiveHint: false, openWorldHint: false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
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 adds value, and it is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description defines the return object. All 7 parameters are documented, usage guidelines are provided, error handling is covered, and context signals show high schema coverage. The description is complete for a complex tool with many parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 including an example for agentId, specifying defaults for source (on_demand) and triggerDetail (manual), and explaining the idempotency window (60s). It adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Wake up an agent by invoking a wakeup request on-demand,' providing a specific verb and resource. It distinguishes from the sibling tool paperclip_invoke_heartbeat by noting that it is for on-demand wakeups, not scheduled heartbeats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when: triggering an agent to process a new assignment or respond to an @-mention' and 'Don't use when: the agent has a scheduled heartbeat... use paperclip_invoke_heartbeat for scheduled agents.' This provides clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures beyond annotations include pagination details (limit, offset, has_more, next_offset), board-only endpoint requiring board API key, and error codes with explanations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with sections: summary, args, returns, examples, error handling. No unnecessary detail, front-loaded with warning. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, pagination, and multiple filters, the description covers usage, all parameters, return envelope, and error handling. No output schema, but return format is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds structured parameter list with defaults, constraints, and formats (e.g., ISO 8601 for dates, 1-100 for limit), enhancing clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists feedback traces for a company with optional filters. It distinguishes from the sibling tool paperclip_list_issue_feedback_traces by explicitly advising against using it for 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Don't use when' examples, points to alternative tool, and mentions board-only restriction and error handling, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds board-only auth requirement, governance policy (CEO reserved field), and detailed error handling for 400, 401, 403, 404. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections (warning, args, returns, examples, errors). Front-loaded with purpose and board-only restriction. Every sentence adds value, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a permission update tool with no output schema: covers purpose, parameters, usage, error scenarios, return structure, and governance constraints. Fully equips an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but description adds extra context: example agent UUID, governance note for canCreateAgents, requirement that both fields are always needed even if unchanged. This significantly aids correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an agent's governance permissions with specific fields (canAssignTasks, canCreateAgents). It distinguishes from the sibling paperclip_update_agent by noting that tool handles config fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (granting/revoking after board decision) and when not to (config field changes, referencing alternative tool). Also notes board-only access, guiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description explains safe concurrent updates via baseRevisionId, idempotent behavior (retry safety), and error handling for 400/401/404/409. Annotations already declare idempotentHint=true, which is consistent. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (overview, Args, Returns, Examples, Error Handling). Each sentence adds value without redundancy. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description specifies return fields (key, title, body, revisionId, updatedAt). Covers error scenarios and prerequisite actions (verify issue ID, re-read on conflict). Complete for a create/update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds meaningful context: examples for issueId and key, explanation of optional format default, and detailed semantics of baseRevisionId for optimistic concurrency. This exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or update an issue document' with specific verbs and resource. It distinguishes from sibling tools by explicitly mentioning when not to use (paperclip_delete_document) and provides alternatives like paperclip_get_document for conflict resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (writing/updating implementation plan) and when-not-to-use (deleting). References sibling tools for alternative actions (paperclip_delete_document, paperclip_get_document, paperclip_list_issues). Includes guidance on baseRevisionId for first create vs update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![paperclip-mcp MCP server](https://glama.ai/mcp/servers/bruhsb/paperclip-mcp/badges/card.svg)](https://glama.ai/mcp/servers/bruhsb/paperclip-mcp)

Score Badge

Copy to your README.md:

[![paperclip-mcp MCP server](https://glama.ai/mcp/servers/bruhsb/paperclip-mcp/badges/score.svg)](https://glama.ai/mcp/servers/bruhsb/paperclip-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bruhsb/paperclip-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server