The BugHerd MCP Server integrates BugHerd bug tracking with AI assistants, providing full API v2 coverage through 38 tools for managing your BugHerd data locally via the MCP protocol.
Organization
Retrieve organization/account details (name, timezone, etc.)
Users
List all users, members only, or guests only
Get tasks assigned to a specific user (with filters for status, priority, pagination)
Get projects accessible to a specific user
Projects
List all or only active projects; get project details
Create, update, or permanently delete projects
Add team members or guests to a project
Tasks
List tasks with filters (status, priority, tag, pagination)
List feedback (unprocessed), archived, or taskboard tasks
Get task details by project+task ID, global ID, or local ID
Create tasks with priority, tags, assignee, and status
Update task status, priority, description, or assignee
Move tasks between projects
Columns (Kanban Board)
List, get, create, and update columns/statuses for a project
Comments
List comments on a task and add new comments
Attachments
List, get details, create (from URL), or permanently delete task attachments
Webhooks
List, create, and delete webhooks for events like task_create, task_update, comment, project_create, and task_destroy
All operations run locally via the MCP protocol, so data never leaves your machine.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BugHerd MCP Server list my open tasks for the main project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Note: This is an unofficial, community-maintained, open-source (MIT) BugHerd MCP server. It runs locally, your data never leaves your machine. For BugHerd's official closed-source hosted server, see macropodhq/bugherd-mcp.
An MCP (Model Context Protocol) server that integrates BugHerd bug tracking with AI assistants.
Complete BugHerd API v2 coverage with 38 tools across all resource types:
Organization - Get account details
Users - List members, guests, user tasks and projects
Projects - CRUD operations, manage members and guests
Tasks - Full task management including feedback, archived, and taskboard views
Columns - Custom Kanban board management
Comments - Read and create comments
Attachments - Manage file attachments
Webhooks - Configure event notifications
Related MCP server: onion-mcp-server
Node.js 18+ or Bun
A BugHerd account with API access
BugHerd API key (get it from Settings > General Settings)
Clone the repository:
git clone https://github.com/berckan/bugherd-mcp.git
cd bugherd-mcpInstall dependencies:
bun install
# or
npm installBuild the server:
bun run build
# or
npm run buildSet your API key:
export BUGHERD_API_KEY=your-api-key-hereAdd to your MCP client config:
{
"mcpServers": {
"bugherd": {
"type": "stdio",
"command": "node",
"args": ["/path/to/bugherd-mcp/dist/index.js"],
"env": {
"BUGHERD_API_KEY": "your-api-key-here"
}
}
}
}Add to your MCP desktop app config:
{
"mcpServers": {
"bugherd": {
"command": "node",
"args": ["/path/to/bugherd-mcp/dist/index.js"],
"env": {
"BUGHERD_API_KEY": "your-api-key-here"
}
}
}
}Tool | Description |
| Get organization/account details |
Tool | Description |
| List all users (members + guests) |
| List only team members |
| List only guests/clients |
| Get tasks assigned to a user |
| Get projects for a user |
Tool | Description |
| List all projects |
| List only active projects |
| Get project details |
| Create a new project |
| Update project settings |
| ⚠️ Delete a project permanently |
| Add a member to a project |
| Add a guest to a project |
Tool | Description |
| List tasks with filters (status, priority, tag) |
| List unprocessed feedback tasks |
| List archived tasks |
| List taskboard tasks |
| Get task details with metadata |
| Get task by global ID |
| Get task by local ID (#123) |
| Create a new task |
| Move tasks between projects |
| Update task status/priority/description/assignee |
Tool | Description |
| List project columns (Kanban statuses) |
| Get column details |
| Create a new column |
| Update column name/position |
Tool | Description |
| List comments on a task |
| Add a comment to a task |
Tool | Description |
| List task attachments |
| Get attachment details |
| Create attachment from URL |
| ⚠️ Delete an attachment |
Tool | Description |
| List configured webhooks |
| Create a webhook |
| ⚠️ Delete a webhook |
List my BugHerd projects
Show me all critical bugs in project 12345Create a task in project 12345: "Fix the login button alignment"
Move task 678 from project 12345 to project 67890
Update task 678 status to "done"Show comments on task 678 in project 12345
Add a comment to task 678: "Fixed in latest deploy"List all webhooks
Create a webhook for task_create events pointing to https://example.com/webhookbun run devBUGHERD_API_KEY=xxx bun run inspectorbun run buildBugHerd allows an average of 60 requests per minute with bursts of up to 10 in quick succession. The server handles rate limiting errors gracefully.
MIT
Contributions are welcome! Please open an issue or submit a pull request.
Add a guest/client to a project by user ID or email.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| user_id | No | The user ID to add as guest | |
| No | Email of the guest to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must disclose behavior. It only states the input method but does not mention side effects, prerequisites (e.g., user existence), return value, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with clear action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing important context for a mutation tool: no indication of what happens on success/failure, whether it sends an invitation, or if the user must already exist. Without output schema, description should provide more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with minimal descriptions for each parameter. The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a guest/client to a project using user ID or email. It distinguishes from siblings like bugherd_add_member and bugherd_list_guests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Implied from context (adding guest vs member), but no direct when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a team member to a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| user_id | Yes | The user ID to add as member |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It only states 'Add', implying creation, but provides no information on side effects, permissions, reversibility, or limits. The tool could modify project membership without disclosing impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, given the simplicity, it could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tools (bugherd_add_guest) and no output schema, the description lacks completeness. It does not mention return values, differentiation from guests, or any constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The description adds no additional meaning to the parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and the resource 'a team member to a project.' However, it does not differentiate from the sibling tool bugherd_add_guest, which could lead to ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives like bugherd_add_guest, or any prerequisites or constraints for adding a member.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an attachment from a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID | |
| file_name | Yes | Name of the file | |
| url | Yes | URL of the file to attach |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not mention whether the operation is destructive, idempotent, requires authentication, or what happens on invalid URLs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and directly states the core functionality. However, it could benefit from slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, yet the description does not indicate what the tool returns (e.g., the created attachment object). It also lacks context about how this fits with project/task hierarchies despite parameters implying attachment to a task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the schema (100% coverage). The description adds no extra meaning beyond the schema, so it meets but does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'create', the resource 'attachment', and the method 'from a URL'. It distinguishes this tool from siblings like delete, get, and list that operate on attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., when to attach a file vs add a comment). No prerequisites or context for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new column in a project's Kanban board.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| name | Yes | Column name | |
| position | No | Column position |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It only mentions creation but omits details on side effects, permissions, rate limits, or response format, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence (8 words) that front-loads the action and object. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with well-documented parameters, the description is minimally adequate but lacks context on usage scenarios or output behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds no new meaning beyond the schema's descriptions. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), resource (column), and context (project's Kanban board). It is specific and distinguishes from sibling tools like bugherd_update_column or bugherd_list_columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites, or potential limitations. The agent lacks context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to a task.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID | |
| text | Yes | Comment text | |
| user_id | No | User ID posting the comment | |
| No | Email of the user posting the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description lacks any behavioral details such as authentication requirements, rate limits, side effects, or return value. It simply states the action without additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but its brevity sacrifices useful structure. While not verbose, it lacks front-loaded key information and is minimalistic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering the tool's complexity (5 parameters, no annotations, no output schema), the description is incomplete. It omits expected context like return behavior, permissions, or any side effects for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all 5 parameters (100% coverage). The tool description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a comment') and the target resource ('to a task'), using a specific verb and resource. It effectively distinguishes itself from sibling tools like bugherd_create_task or bugherd_create_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new BugHerd project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name | |
| devurl | Yes | Development URL for the project | |
| is_active | No | Whether the project is active | |
| is_public | No | Whether the project is public |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present; description only says 'Create', implying mutation. No details on side effects, authentication needs, rate limits, or error conditions. Lacks behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence without extraneous words. Appropriate length for a simple creation tool, but could include brief usage context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should explain return value. Lacks details on boolean parameter behavior or what happens on success/failure. Incomplete for a tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. Description adds no additional meaning or context beyond the schema, such as validation rules or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new BugHerd project' with a specific verb and resource. It distinguishes from siblings like bugherd_update_project and bugherd_delete_project by the action, but does not elaborate on scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention prerequisites or comparisons to siblings like bugherd_update_project or bugherd_list_projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task/bug in a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| description | Yes | Task description | |
| priority | No | Task priority | |
| status | No | Task status/column name | |
| tag_names | No | Tags for the task | |
| assigned_to_id | No | User ID to assign task to | |
| requester_email | No | Email of the requester | |
| external_id | No | External reference ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states 'Create' without details on side effects, permissions, or potential pitfalls like duplicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It is not verbose, though it could include a bit more detail without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a tool with 8 parameters and no output schema. It omits important context like required parameters (project_id, description) or what happens upon success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds no extra meaning beyond the schema; it does not elaborate on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new task/bug in a project' with a specific verb and resource. It distinguishes from siblings like bugherd_create_comment or bugherd_update_task, as it explicitly mentions creating tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as bugherd_update_task for updates or bugherd_create_comment for comments. The description lacks any usage context or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook to receive notifications for BugHerd events.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | Event type that triggers the webhook | |
| target_url | Yes | URL to receive webhook POST requests | |
| project_id | No | Optional project ID to scope the webhook |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits like authentication needs, webhook verification, retry behavior, or lifecycle. The description only states the basic purpose, omitting important details about the creation process and potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficient and front-loaded, but it sacrifices completeness for brevity. It earns its place but could be improved with a second sentence for context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more context about what the webhook returns (e.g., a webhook ID), error states, and prerequisites. The current description is insufficient for an AI agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes each parameter. The description adds no additional meaning beyond what is in the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('webhook'), and the purpose ('receive notifications for BugHerd events'). It implicitly distinguishes from sibling tools like bugherd_list_webhooks and bugherd_delete_webhook.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as listing existing webhooks or updating them. The description does not mention prerequisites, when-not to use, or provide any comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚠️ DESTRUCTIVE: Delete an attachment permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID | |
| attachment_id | Yes | The attachment ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description includes a warning emoji and states the action is destructive and permanent, but lacks details on idempotency, permissions, or whether the operation can be undone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with emoji warning, highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description mentions permanence but does not cover possible error conditions or return values, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no additional 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name and description clearly state it deletes an attachment permanently, which distinguishes it from siblings like bugherd_get_attachment or bugherd_create_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like get or create, nor any prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚠️ DESTRUCTIVE: Delete a project and all its tasks permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly labels the tool as destructive and states that deletion is permanent, which covers the primary behavioral trait. However, with no annotations, it could be more detailed about side effects (e.g., deleting associated data beyond tasks) or required permissions, but the warning is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence with a warning symbol—and every word is meaningful. It efficiently communicates the tool's purpose and risk without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description provides adequate context: it is destructive and permanent. It could mention that the action cannot be undone or requires specific privileges, but it meets minimum completeness for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes the only parameter (project_id) clearly. The description adds no additional meaning beyond what the schema provides, and schema coverage is 100%, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a project and all its tasks permanently, with a prominent 'DESTRUCTIVE' warning. This is specific and distinguishes it from sibling delete tools like bugherd_delete_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., archiving) or prerequisites. It does not mention when not to use it or provide context about project ownership or permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
⚠️ DESTRUCTIVE: Delete a webhook permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | The webhook ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description labels the tool 'DESTRUCTIVE' and notes permanence, which is useful. However, with no annotations, it fails to disclose permissions or side effects beyond deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded with a warning emoji. It is efficient but could be slightly expanded without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, the description is adequate but minimal. It lacks context on irreversibility (though implied) and authorization needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of webhook_id. The tool description adds no additional semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a webhook permanently' with a specific verb and resource. It distinguishes from sibling tools like create_webhook or list_webhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The warning emoji implies caution but no explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID | |
| attachment_id | Yes | The attachment ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation but does not disclose return format, error handling, or any side effects. Minimal behavioral information is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no extraneous information. Perfectly concise for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what 'details' are returned. It lacks completeness for an agent to understand the response or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description adds no additional semantic meaning beyond the schema definitions, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get details) and resource (specific attachment), distinguishing it from siblings like bugherd_create_attachment and bugherd_delete_attachment. However, it could be more explicit about the required IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as bugherd_list_attachments or bugherd_get_task. The description does not provide contextual cues for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific column.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| column_id | Yes | The column ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It fails to disclose that this is a read-only, idempotent operation. It does not specify what is returned beyond 'details', leaving the agent to infer behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is well front-loaded. It avoids unnecessary words, though it could be slightly more informative without increasing length significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description is insufficient. It does not explain what details are returned, any business logic, or how to interpret results, leaving significant gaps for a tool with two required parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are adequately described in the schema. The description adds no further meaning beyond 'specific column', which is already implied by the column_id parameter. Meets baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get details') and the resource ('a specific column'). It implies targeting a single column, but does not explicitly distinguish from bugherd_list_columns, which retrieves all columns. Still, it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like bugherd_list_columns. It does not mention that this tool is for retrieving details of a single column by ID, nor does it provide context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get organization/account details including name and timezone.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states that details are returned, but does not mention read-only nature, authentication requirements, rate limits, or whether the call is safe. The verb 'Get' implies idempotency, but explicit safety cues are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the purpose and key return fields without extraneous words. It is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the basic purpose and some return fields, it does not explicitly state that this is a read-only operation, nor does it list all possible account details. Given no output schema, the agent lacks full understanding of the response structure, though the tool is simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is complete. The description adds no parameter-specific info because none exist. Baseline 4 is appropriate given no parameters to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'organization/account details' along with specific fields such as name and timezone. This distinguishes it from sibling get/list tools that target other entities like projects, tasks, or users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not mention that this tool retrieves the top-level organization info and could be a first step before using other tools. Siblings like bugherd_get_project suggest differentiated usage, but the description lacks context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only says 'Get details'. It fails to disclose the read-only nature, authorization needs, rate limits, or any other behavioral traits that would help an agent understand the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the core functionality without unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description is still too minimal. It does not explain what 'details' include or how the return value looks, leaving an agent without enough context to fully anticipate the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, covering the single parameter 'project_id' with 'The BugHerd project ID'. The tool description adds no additional meaning beyond the schema, which meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Get' and resource 'a specific project', making the purpose clear. However, it does not differentiate from sibling tools like bugherd_list_projects or other getter tools, missing the chance to highlight its uniqueness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as bugherd_list_projects or other bugherd getters. There is no mention of prerequisites or contexts that favor this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific task including description, screenshot URL, selector info, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions retrieving details but lacks disclosure of potential errors, rate limits, or authentication needs. Adequate for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, no unnecessary words. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple read tool with 2 required params and no output schema. Could mention error handling or return format but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The tool description adds no additional meaning beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets detailed information about a specific task and lists some included fields. However, it does not differentiate from sibling tools like bugherd_get_task_by_local_id or bugherd_get_task_global.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus similar sibling tools. Does not specify prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a task by its local ID (#123) within a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| local_task_id | Yes | The local task ID (#123) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'Get a task', missing behavioral traits like read-only nature, required permissions, or effects. With no annotations, description should disclose more.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct and efficient with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description does not hint at return values or response structure. Incomplete for a fetch tool that returns task data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with parameter descriptions. Description adds context about local ID format, but doesn't add significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Get', resource 'task', and distinguishing identifier 'local ID (#123)' within a project. Differentiates from sibling tools like bugherd_get_task and bugherd_get_task_global.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when you have a local ID, but no explicit when-not or alternatives mentioned. Could direct users to bugherd_get_task for global IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a task by its global ID (without needing the project ID).
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The global task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states 'Get a task', implying read-only. It discloses no behavioral traits such as permissions, error behavior, or side effects, which is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool without output schema, the description covers the key differentiator. However, it lacks details on return format, error handling, or example usage, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter 'task_id' described as 'The global task ID'. The description adds the context 'by its global ID', reinforcing the parameter's purpose, but adds no extra semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a task by its global ID', identifying the verb and resource, and distinguishes itself from siblings like bugherd_get_task and bugherd_get_task_by_local_id by highlighting the global ID without needing project ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without needing the project ID' explicitly indicates when to use this tool (when only global ID is available), providing clear context. However, it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get projects accessible to a specific user.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the basic purpose. It does not disclose behavioral traits such as whether the tool is read-only, what fields are returned, or any authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) but could be more informative. It gets the job done without waste, but lacks structure or prioritization of key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and only one parameter, the description is minimally complete but misses important context such as whether results are paginated, what format the projects are returned in, or any error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% for the single parameter, providing adequate documentation. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get projects') and the scope ('accessible to a specific user'). However, it does not differentiate from sibling tools like bugherd_list_projects or bugherd_get_project, so it scores 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like bugherd_list_projects or bugherd_get_user_tasks. The description lacks any contextual cues for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks assigned to a specific user.
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | The user ID | |
| status | No | Filter by status | |
| priority | No | Filter by priority | |
| page | No | Page number for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially carries the transparency burden. It correctly indicates a read operation but omits details like pagination behavior or what happens if the user_id is invalid. The description is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description could explain what the return data looks like. It doesn't, but the core purpose is clear. It's adequate for a simple list tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no extra parameter meaning beyond the schema's own descriptions. Per guidelines, this scores a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('tasks'), and the filter ('assigned to a specific user'), distinguishing it from siblings like bugherd_list_tasks and bugherd_get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool vs. alternatives such as bugherd_list_tasks or bugherd_get_user_projects. No 'when not to use' or context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only active projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic function without disclosing traits like pagination, rate limits, definition of 'active', or that it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no unnecessary words; perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameter-less list tool, the description adequately conveys its purpose. However, it could benefit from explaining what 'active' means, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is complete. The description adds no param detail, but baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List only active projects' clearly states the action (list) and scope (active projects), distinguishing it from sibling tools like bugherd_list_projects (all projects) and bugherd_get_project (single project).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells the agent when to use this tool (to retrieve only active projects), but does not explicitly mention alternatives like bugherd_list_projects for all projects or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List archived tasks for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| page | No | Page number for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'List archived tasks' without disclosing pagination, authentication, or side effects. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, but lacks detail for a 2-parameter tool. Efficient but could be slightly more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and brief description leave gaps in understanding return format and pagination behavior. Incomplete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are documented. Description adds no additional meaning beyond the schema, meeting baseline but not exceeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists archived tasks for a project, but does not differentiate from siblings like bugherd_list_tasks which may include non-archived tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternative list tools. No context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all attachments on a task.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose any behavioral traits such as whether attachments are returned with full details, pagination behavior, required permissions, or any side effects. Merely stating 'List all attachments' is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It efficiently conveys the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a list operation with no output schema, the description should indicate what is returned (e.g., list of attachment objects or IDs). It does not. Combined with lack of usage guidance and behavioral transparency, the description is incomplete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as both parameters have descriptions in the schema. The description adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and specifies the resource ('attachments') with clear scope ('on a task'). It distinguishes from sibling tools like bugherd_get_attachment (single attachment) and bugherd_create_attachment (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It is implied that you need project_id and task_id, but no explicit when-to-use or when-not-to-use context is provided. The sibling list includes other 'list' tools and 'get_attachment', but no comparative direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all columns (statuses) for a project. Use this to find the correct status names for updating tasks in projects with custom Kanban boards.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'list all columns' implying a read operation, but lacks details on authentication, rate limits, or response format. For a simple listing tool, it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the absence of an output schema, the description provides sufficient context for an agent to understand what the tool returns (list of columns with status names). It is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds minimal value beyond stating 'for a project,' which is already implied by 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'columns (statuses)' for a project, clearly distinguishing it from siblings like bugherd_get_column (single column) and bugherd_create_column (create). It also adds context about finding status names for task updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'to find the correct status names for updating tasks in projects with custom Kanban boards.' It does not mention exclusions or alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all comments on a specific task. Returns comment text, author, and timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID to get comments for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the tool lists comments and returns specific fields, but does not clarify if it is read-only, whether pagination or rate limits apply, or any other behavioral traits beyond the basic fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using one sentence to state the action and another to mention return fields. Every word is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 parameters, no output schema), the description adequately conveys purpose and return fields. However, it lacks information on pagination, ordering, or potential limits, which are relevant for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with basic descriptions for both parameters (project_id and task_id). The description adds no additional meaning beyond that provided in the schema, such as format constraints or required relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (all comments on a specific task), and what is returned (comment text, author, timestamp). This distinguishes it from sibling tools like bugherd_create_comment (create vs list) and bugherd_list_tasks (listing tasks vs comments).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as bugherd_create_comment for adding comments or bugherd_get_task for task details. No usage context or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List feedback tasks (unprocessed/new) for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| page | No | Page number for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the purpose and does not mention pagination behavior, rate limits, ordering, or read-only nature (implied but not explicit).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence with no superfluous words. Front-loads the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple list tool but lacks details on return fields, default pagination, and sorting. Given no output schema, the description could provide more context on results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having clear descriptions. The tool description adds no additional semantic value beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'List', resource 'feedback tasks', and clarifies scope with 'unprocessed/new'. It clearly distinguishes from sibling tools like bugherd_list_tasks (all tasks) and bugherd_list_archived_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing new/unprocessed feedback tasks but does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only guests/clients in the organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It only states the purpose (listing) without mentioning pagination, rate limits, or that it's a read-only operation. For a simple list with no parameters, the description is minimally adequate but adds no extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential purpose with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is reasonably complete. It defines the resource and the action. However, it does not specify the output format, though the tool name implies a list of guest objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0 parameters and 100% schema coverage, the description does not need to explain parameters. The baseline for zero parameters is 4, and the description appropriately omits parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists 'only guests/clients', specifying the exact resource and scope. It distinguishes itself from siblings like bugherd_list_users and bugherd_list_members by explicitly limiting to guests/clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when listing guests/clients, but does not explicitly state when to use it over alternatives like bugherd_list_members or bugherd_list_users. No exclusions or contextual guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only team members in the organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as pagination, rate limits, or read-only guarantees beyond the minimal 'list' verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is mostly adequate but lacks any mention of pagination or ordering, which are common for list endpoints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description adds meaning by specifying 'only team members', which qualifies the result set. According to guidance, baseline for 0 params is 4, and the description provides that context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'team members', and the scope 'in the organization'. It distinguishes from sibling tools like bugherd_list_users and bugherd_list_guests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives. The phrase 'only team members' implies exclusion of guests, but it does not explicitly state conditions or provide examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all BugHerd projects accessible to the authenticated user. Returns project names, URLs, and IDs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read operation but doesn't mention pagination, ordering, or potential errors. For a simple list with no params, it's adequate but lacks full behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, highly concise, front-loaded with the key purpose. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Low complexity (no params, no output schema). Description adequately covers return fields but could mention sorting or total count for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (empty schema, 100% coverage). The description adds value by specifying return fields (names, URLs, IDs), which goes beyond the schema. Baseline for zero params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), resource (all BugHerd projects), scope (accessible to authenticated user), and output (names, URLs, IDs). It distinguishes from siblings like bugherd_list_active_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over siblings like bugherd_list_active_projects, bugherd_get_project, or bugherd_get_user_projects. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List taskboard tasks (not feedback, not archived) for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| page | No | Page number for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only discloses the scope (taskboard tasks, not feedback, not archived) but does not mention pagination behavior, default page size, rate limits, or any other behavioral traits. For a list tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action, and contains no unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with only two parameters, the description lacks details about the return format, pagination default or limits, and ordering. Given no output schema, the description should provide more context for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions for both parameters. The tool description adds meaningful context by clarifying that the project_id refers to a BugHerd project and that the result is limited to taskboard tasks, which adds value beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('taskboard tasks'), and explicitly excludes feedback and archived tasks. This clearly distinguishes it from siblings like bugherd_list_tasks, bugherd_list_archived_tasks, and bugherd_list_feedback_tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but provides no guidance on when to use it over the many similar list tools among siblings. It does not mention when not to use it or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks (bugs/feedback) for a specific BugHerd project. Can filter by status (use column name from bugherd_list_columns), priority, or tag.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| status | No | Filter by task status (use column name from bugherd_list_columns, e.g., 'backlog', 'todo', 'doing', 'Ready for review', 'done') | |
| priority | No | Filter by priority | |
| tag | No | Filter by tag name | |
| page | No | Page number for pagination (default: 1) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states that the tool lists tasks and can filter, but omits any side effects, authentication needs, rate limits, or error behaviors. For a read-only tool, this is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and filtering options. It is front-loaded and contains no unnecessary words or repetition. Every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the 100% parameter schema coverage, covers the tool's inputs well. However, there is no output schema, and the description does not explain the return format or fields. Given the complexity of listing tasks with filters, the lack of output details leaves a gap for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter already has a description. The description adds no new semantics beyond what is in the schema; it merely restates that status uses column names from another tool. With high schema coverage, the baseline is 3, and the description does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List tasks (bugs/feedback) for a specific BugHerd project.' It uses a specific verb ('list') and resource ('tasks') and distinguishes from sibling list tools by implying it lists all tasks for a project, not archived, feedback-only, or taskboard tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering capabilities and references bugherd_list_columns for status, but does not provide explicit guidance on when to use this tool versus other list tools like bugherd_list_archived_tasks or bugherd_list_feedback_tasks. The usage context is implied but not fully delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users (members + guests) in the organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the tool lists all users but gives no information about pagination, rate limits, or output format. For a simple tool with no parameters, this is minimally acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is fairly complete for a simple list tool. It could potentially mention if inactive users are included, but the context of sibling tools provides enough clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100%. The description adds no parameter information, which is acceptable. Baseline of 3 applies per rubric since coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List' and the resource 'all users (members + guests) in the organization.' This distinguishes from siblings like bugherd_list_guests and bugherd_list_members by explicitly including both types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing all users, contrasting with sibling tools that list only guests or members. However, it does not explicitly state when to use this over alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all webhooks configured for the organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only, non-destructive operation but does not disclose details such as whether disabled webhooks are included or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity and no output schema, the description is adequate but does not specify the return format (e.g., array of webhook objects) or any pagination details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100% (trivially). The description adds no extra parameter meaning beyond the schema, which is acceptable for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'webhooks' with scope 'organization'. It distinguishes from sibling tools like 'bugherd_create_webhook' and 'bugherd_delete_webhook'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing webhooks but provides no explicit guidance on when to use this tool vs alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move tasks from one project to another.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The source project ID | |
| task_ids | Yes | Array of task IDs to move | |
| destination_project_id | Yes | The destination project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only states the action 'move' without explaining side effects (e.g., removal from source project, impact on comments/history) or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no superfluous words. However, it could be slightly more detailed while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and no annotations, the description lacks critical behavioral details such as whether the move is reversible, what happens to the source task, or any permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with minimal descriptions. The tool description adds no extra meaning beyond what the schema already provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Move' and clearly identifies the resources 'tasks' and the context 'from one project to another', making it distinct from sibling tools like create or update tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., copying tasks, reassigning). No mention of prerequisites or conditions for moving tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a column's name or position.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| column_id | Yes | The column ID to update | |
| name | No | New column name | |
| position | No | New column position |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only says 'Update', which is tautological. It does not disclose behavioral traits such as whether updates are atomic, constraints on name uniqueness, or position bounds.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, conveying the core functionality without fluff. However, it could be slightly expanded to improve utility without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks explanation of required parameters (though in schema), return value, error conditions, and side effects. For a mutation tool with no output schema, more context is needed for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds no extra meaning beyond the schema, such as indicating name and position are optional or providing formatting hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool updates a column's name or position, clearly identifying the action and resource. It distinguishes itself from sibling tools like bugherd_create_column and bugherd_list_columns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like bugherd_create_column or bugherd_get_column. There is no mention of prerequisites or context for updating columns.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a project's settings.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| name | No | New project name | |
| devurl | No | New development URL | |
| is_active | No | Whether the project is active | |
| is_public | No | Whether the project is public |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only says 'update', implying mutation, but no details on permissions, idempotency, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundant words. Could benefit from more structure, but it's concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 5 parameters, no output schema, no annotations. Description does not cover return values, error handling, or context. Inadequate for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds no extra meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a project's settings' clearly states the action and resource. It distinguishes from create/delete/get siblings, though 'settings' is somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like bugherd_update_task or bugherd_update_column. The description lacks any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task's status, priority, description, or assignee. Use this to mark tasks as done, move them through workflow stages, or assign them to users.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The BugHerd project ID | |
| task_id | Yes | The task ID to update | |
| status | No | New status for the task (use column name from bugherd_list_columns) | |
| priority | No | New priority for the task | |
| description | No | New description for the task | |
| assigned_to_id | No | User ID to assign the task to (or null to unassign) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the tool updates fields, but does not mention authorization needs, rate limits, or whether changes are reversible. The verb 'Update' implies mutation, but no further behavioral details are given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, covering purpose and usage examples without any unnecessary words. It is front-loaded with the main action and immediately explains key use cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and 6 parameters (2 required), the description adequately explains what the tool does and provides usage examples. However, it lacks information on return values, error behavior, or prerequisites, which would be important for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context such as 'mark tasks as done' (for status) and 'assign them to users' (for assigned_to_id), which helps users understand how to use specific parameters. This slightly exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a task's status, priority, description, or assignee, and distinguishes from sibling tools by focusing on task attributes. It specifically mentions marking tasks as done, moving through workflow stages, and assigning, which sets it apart from other update tools like update_column or update_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'mark tasks as done, move them through workflow stages, or assign them to users.' This gives clear guidance on when to use the tool, though it does not discuss when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool targets a distinct resource or subset, with clear naming and descriptions that prevent confusion. Even similar tools like list_tasks, list_feedback_tasks, and list_taskboard_tasks are precisely differentiated.
All tools follow the consistent pattern 'bugherd_verb_noun' with optional qualifiers (e.g., get_task_by_local_id). The snake_case naming is uniform and predictable.
With 37 tools, the count is above the typical 3-15 range, but it is justified by the breadth of features (projects, tasks, columns, attachments, comments, users, webhooks, etc.). It's slightly over but still reasonable.
The tool set covers most CRUD operations for major resources, but notable gaps exist: no delete for tasks, columns, or comments, and no update/delete for comments. This limits lifecycle coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for building and testing AI agents with multi-model experimentation and insights.
An MCP server that integrates with Discord to provide AI-powered features.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Berckan/bugherd-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server