hacknplan-mcp

Server Quality Checklist

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

Latest release: v0.3.0
Disambiguation5/5
Each tool targets a distinct resource and action (e.g., create_work_item vs. update_work_item vs. delete_work_item), and even similar operations like list_work_items, find_work_items, and my_work are clearly differentiated by their descriptions. The naming and descriptions make the purpose of each tool unambiguous, despite the large number of tools.
Naming Consistency4/5
The majority of tools follow a consistent snake_case verb_noun pattern (create_, update_, list_, get_, delete_, etc.). A few tools like portfolio_overview, schedule_overview, recent_activity, hacknplan_whoami, and my_work deviate from this pattern but remain in snake_case and are still readable and logically named.
Tool Count1/5
With 75 tools, this server far exceeds the typical well-scoped MCP server size of 3-15 tools and even the 25+ threshold for 'too many'. While the breadth reflects the full HacknPlan API, this is an extreme number that would overwhelm an agent and make tool selection unwieldy.
Completeness4/5
The tool set provides comprehensive CRUD coverage for most core resources: projects, stages, categories, tags, importance levels, boards, milestones, work items, subtasks, dependencies, comments, and design elements. A few minor gaps exist, such as lacking attachment upload/delete, user management within a project, and the ability to edit or delete comments, but the overall lifecycle is well-covered.
Average 3.7/5 across 75 of 75 tools scored. Lowest: 2.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- Last stable release on June 18, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only says 'assign' without explaining side effects, whether the assignment is idempotent, permissions needed, or what happens if the user is already assigned. This is a significant transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence, which is concise and front-loaded. However, it is under-specified given the tool's mutation nature and lack of other documentation. It earns its place but does not provide enough substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 required integer parameters, no schema descriptions, no annotations, and a mutation operation, the description is inadequate. It does not explain the assignment semantics, any constraints, or expected behavior, making it incomplete for safe and correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter semantics. It does not explain the role of project_id, user_id, or work_item_id, nor the relationship between a project user and a work item. The agent is left to infer everything from the bare parameter names, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Assign') and the resources involved ('project user' to 'work item'), distinguishing it from the sibling 'unassign_user'. However, it lacks any additional context such as whether this replaces or adds an assignee, so it is not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that this should be used for adding an assignee to a work item, nor does it indicate any prerequisites like the user being a project member. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
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 simply says 'Close (end)' which merely restates the tool's name and implies an ending, but does not disclose any side effects, reversibility, or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it is under-specified. While concise, it lacks detail that would make it more useful, so it only earns a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description should explain more about the operation's effects and context. It only states the action, leaving questions about prerequisites, consequences, and return values unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the two parameters (board_id, project_id) at all. No meaning is added beyond the raw integer types in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Close') and resource ('a board/sprint'), clearly indicating the tool's function. It distinguishes from siblings like create_board, update_board, and reopen_board, although it doesn't explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It only states what it does, leaving the agent to infer when it should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only repeats the action 'Create' without disclosing any behavioral details. It does not mention side effects, permissions, idempotency, or what happens on success/failure. The description adds no value beyond what the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It earns its place, but the brevity borders on under-specification, which is captured by other dimensions. Structure is simple and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no annotations, this description is grossly incomplete. It provides only the basic purpose and leaves agents with no information about required fields, parameter syntax, or expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes three parameters (name, color, project_id), but the description mentions none of them. With 0% schema coverage in the description, agents receive no explanation of what each parameter means or how they relate to the category creation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a work-item category with a specific verb and resource. This distinguishes it from sibling create tools for projects, stages, tags, milestones, etc. Even though 'work-item category' is slightly specific, it is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 or when to prefer alternatives. It does not mention prerequisites, contraindications, or relationships with other tools like list_categories or update_category.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it only says 'Create a tag (label).' It fails to mention any creation constraints, uniqueness expectations, project association, or return behavior. The lack of any side-effect or requirement information is a notable gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler, making it efficient and easy to parse. While it could include more detail, its brevity is appropriate for a simple operation and does not violate conciseness principles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is too sparse. It does not mention that project_id is required for project association, nor does it explain any naming or color constraints. The minimal context leaves the agent to guess operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters with 0% description coverage, and the description provides no explanation of any parameter. The agent must rely solely on the raw schema, which omits property descriptions. The description does not compensate for this documentation gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create) and the resource (tag), with the parenthetical 'label' providing a useful synonym. It is unambiguous, though it does not explicitly distinguish itself from sibling tools like create_category; however, the token name itself provides sufficient resource identification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as create_category or create_stage, nor does it mention prerequisites like the need for an existing project. It states only what the tool does, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It reveals the critical behavior that confirm=true is required for deletion, which is a safety guard. However, it does not disclose whether deletion is permanent, any permissions needed, or potential cascading effects, leaving the agent with limited understanding of the operation's consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, consisting of two short sentences. While it is front-loaded and waste-free, it is so terse that it sacrifices necessary detail. The structure is acceptable, but the brevity borders on under-specification, warranting a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations, no output schema, and four parameters, the description is incomplete. It mentions the critical confirm requirement but omits other context like the hierarchical relationship between project, work item, and subtask, or any expected side effects. This leaves the agent with insufficient information to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters. The description only adds meaning for the confirm parameter, specifying that it must be true. It does not explain project_id, work_item_id, or subtask_id, though these names are self-explanatory due to the tool's context. This partial compensation is insufficient given the complete lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a sub-task,' which identifies a specific verb and resource. It distinguishes from sibling tools like delete_work_item or delete_project, but it doesn't explicitly differentiate from add_subtask/update_subtask/list_subtasks beyond implying the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only usage-related information is the requirement that confirm=true, but this is more of an invocation requirement than a contextual guideline about when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the creation action and due_date format, omitting side effects, permissions, return behavior, or reversibility. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: the core action 'Create a milestone' comes first, followed by the essential due_date format clarification. Both sentences earn their place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 milestone is tied to and what happens upon creation. It does not mention project association (beyond the schema parameter) or any return values, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does clarify due_date's ISO 8601 format, which is valuable, but provides no meaning for name, project_id, or general_info. Thus it only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a milestone' with a direct verb and resource. However, it does not differentiate from sibling create_* tools beyond the resource name itself, and lacks additional scope or context. The added due_date format note prevents it from being a pure tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 update_milestone or create_work_item. There are no contextual cues or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a write operation ('Attach') but does not disclose whether the operation is idempotent, whether it can be undone, what permissions are needed, or what happens if the tag or work item does not exist. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action. It has no redundant words or filler. However, it is arguably too terse, as it omits important context that could be included without much added length, so it is not perfectly 'appropriately sized'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three required parameters, no annotations, and no output schema. The description fails to provide essential context such as return values, error conditions, idempotency, or side effects. Given the lack of annotation support, the description is incomplete for an agent to confidently invoke the tool without additional knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that tag_id refers to an 'existing tag' and work_item_id to a 'work item', but it entirely omits project_id. It does not explain the relationship between the parameters (e.g., that the tag must belong to the project) or provide any additional constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Attach') and clearly identifies the resource ('work item') and the object ('existing tag'). It distinguishes this tool from siblings like create_tag, detach_tag, and update_tag by implying that the tag already exists and the action is to link it. This is a precise and unambiguous statement of purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention prerequisites (e.g., that the tag must already exist, that the work item must be in the same project), nor does it contrast with detach_tag or create_tag. The description simply states the action with no contextual usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only states the action and the color/icon aspect, without covering side effects, permission requirements, response format, or handling of duplicates/errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, making it efficient. However, it is so brief that it sacrifices valuable contextual detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, this description is far from complete. It fails to specify required inputs, default behavior, or return values, leaving significant gaps for an agent attempting to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to explain parameters. It only mentions color and icon, but does not clarify the required project_id and name fields, nor the is_default boolean, leaving the agent without sufficient semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: creating an importance/priority level. The verb 'Create' combined with the resource 'importance/priority level' and the parenthetical '(color+icon)' provides a specific, differentiated purpose from sibling tools like update_importance_level or list_importance_levels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as the need for an existing project, nor does it reference any related tools or actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavior, but it only states the action and a cryptic status note. It does not explicitly mention read-only nature, response structure, or any side effects, leaving important behavioral details undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, using one sentence for the core purpose. However, the trailing 'status is...' fragment is ambiguous and not well-integrated, slightly reducing structural clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too sparse. It does not specify what the output contains, ordering, or how 'format' affects results, leaving the agent with an incomplete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'format' parameter (though the schema does) and only implicitly references project_id via 'a project's stages'. The 'status is created|started|completed' line could be misread as a parameter, adding confusion rather than clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('a project's stages'), and clarifies with 'kanban columns'. It clearly distinguishes from sibling tools like list_boards and list_milestones by naming the project resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives such as list_boards or list_milestones. No exclusions or alternative references are provided, leaving the agent to infer usage from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions the updatable aspects but does not disclose permissions, side effects, reversibility, or impact on related work items. The verb 'update' implies mutation, but no further behavioral traits are shared.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action ('Update') and resource, and the parenthetical adds concise scope. Every word earns its place, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and 5 parameters, the description is too sparse. It does not explain return values, error behavior, required identifiers, or any consequences of the update, leaving the agent without enough context to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It maps to the 'name', 'color', and 'icon' parameters via the re-name/re-color/re-icon phrase, adding some meaning beyond the bare schema names. However, it does not explain the purpose of project_id and category_id or the required status of name, leaving a partial gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates a work-item category and specifies the scope (re-name / re-color / re-icon), giving a specific verb and resource. It does not explicitly distinguish from sibling update tools (e.g., update_stage, update_tag), so it lacks overt sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like create_category or update_stage. It does not mention prerequisites, context, or situations where this tool is preferred, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It only says 'Create', which implies a write operation, but does not mention side effects, permissions, required relationships, or any other behavioral traits. The semantic clarification that it's a node category is helpful, but not enough for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose efficiently. There is no wasted wording, and the structure is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with four parameters, no annotations, and no output schema, a one-sentence description is insufficient. It lacks information about required fields, return values, and any side effects or special conditions, making it incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the four parameters (icon, name, color, project_id). Since the description adds no meaning to the schema, the agent is left to guess parameter semantics. This is a severe gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a design-element type' with a clarifying parenthetical that it is a node category for the design/feature tree. This is a specific verb+resource and distinguishes it from siblings like create_design_element or update_design_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when creating a category/node type) by clarifying what a design-element type is, but it does not explicitly mention alternatives or provide any usage exclusions. It gives minimal context beyond the tool's core purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must fully convey behavior. It only states 'List the attachments' which implies a read-only operation, but provides no additional context such as permission requirements, return format, or whether file contents are included. This is thin disclosure for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no wasted words. It is appropriately front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 output schema and no annotations, this description is minimal. It lacks parameter semantics, any indication of the return value shape, and usage context, making it incomplete for an agent to confidently invoke without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines project_id and work_item_id as required integers but gives no descriptions. The description mentions 'work item' which maps to work_item_id, but does not explain the role of project_id or how the identifiers relate. With 0% schema description coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list), the resource (attachments), and the container (work item). It is unambiguous and distinguishes this tool from siblings like list_work_items or get_work_item, which do not focus on attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that it is specifically for retrieving attachments or how it differs from get_work_item, which might return work item details including attachments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 implies a read-only list operation but does not disclose access requirements, return format, pagination, or any side effects. The parenthetical about tree nodes adds minimal context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. Every word adds value, and the optional filter is clearly communicated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no annotations and no output schema, the description is too sparse. It omits the required project_id context, does not clarify what a design element is beyond the brief parenthetical, and lacks behavioral or return-value details that would help the agent use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains type_id as an optional filter but does not mention project_id, which is required. Only one of two parameters receives semantic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('design elements'), and the parenthetical ('nodes of the design/feature/knowledge tree') adds specificity. It distinguishes from sibling tools like list_design_element_types by focusing on elements rather than types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The optional filter by type_id implies a use case, but there is no mention of when to prefer this over other list tools or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the core mutation ('reopen') and implies the milestone must be closed, but it does not disclose any side effects, required permissions, error conditions, or return value. This is a minimal description for a state-changing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no irrelevant information, making it highly concise and front-loaded. However, it is so short that it borders on under-specification, though it does convey the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two integer params, no output schema, no annotations), the description provides the basic purpose but lacks any context about the transition of state, potential failure modes, or post-conditions. It is adequate for a minimal tool but not complete enough to fully inform an agent without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no information about the two required parameters (project_id and milestone_id). The parameter names are self-explanatory, but the description does not compensate for the lack of schema descriptions, leaving the agent without guidance on how to obtain or format these IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Reopen') on a specific resource ('previously closed milestone'), which distinguishes it from sibling tools like close_milestone, update_milestone, and reopen_project. It conveys exactly what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previously closed milestone' implies the use case: to change a closed milestone back to open. However, there is no explicit guidance on when to choose this over alternatives like update_milestone or close_milestone, nor any mention of prerequisites beyond the implied closed state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the update action and date format, but does not disclose whether changes are irreversible, whether partial updates are supported, required permissions, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and field list. There is no filler or redundancy; every word contributes to understanding the tool's basic function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, and no output schema. The description covers only the basic update action and a few fields, but omits crucial context like partial-update semantics, validation, ID requirements, and response/return value. This is inadequate for an update tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the 6 parameters. It adds meaning for name, due/start date, and general info, plus ISO 8601 date format, but does not explain the required project_id and milestone_id parameters or their role in routing the update. This leaves half the parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: updating a milestone with a specific verb ('update') and resource ('milestone'), plus enumerates the editable fields (rename, due/start date, general info). This distinguishes it from sibling tools like create_milestone, close_milestone, or delete_milestone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 update_work_item, reopen_milestone, or close_milestone. Prerequisites, scoping (e.g., which milestones are eligible), and exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full responsibility for behavioral disclosure. It only states the action ('Add...') without mentioning side effects, prerequisites (e.g., existing work item), return value, or any side effects. This leaves the agent without knowledge of mutation effects or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every word earns its place, making it highly concise and easily scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter create operation, the description covers the core purpose but lacks contextual details such as required parameter semantics, return behavior, or any preconditions. Given the absence of annotations and output schema, a bit more context would be helpful, but the tool's simplicity partially mitigates this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, and the description does not explain the parameters. Although parameter names (title, project_id, work_item_id) are self-evident to some degree, the description adds no explicit mapping or constraints beyond what the schema names provide. This fails to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Add' with a clear resource ('one sub-task (checklist item)') and target ('to a work item'). The parenthetical 'checklist item' disambiguates from other add_* tools like add_comment or add_dependency. It clearly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case for adding a subtask to a work item but provides no explicit guidance on when to use this versus alternatives like update_subtask or create_work_item. No exclusions or alternative tool references are given, so usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 of behavioral disclosure. It states 'Get one design element' but does not mention whether the operation is read-only, what happens if the element is not found, permission requirements, or any side effects. The only added detail is 'with its documentation/description,' which hints at return contents but does not elaborate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core purpose efficiently. The parenthetical adds a small amount of useful context without excessive padding. It is appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations, output schema, and parameter descriptions, the description is minimal and incomplete. It does not explain the return structure beyond 'documentation/description,' nor does it clarify the role of project_id or the relationship between the two parameters. For a simple read tool, more context would be expected, especially since the tool is part of a large sibling family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention either parameter. The parameter names 'project_id' and 'element_id' are somewhat self-explanatory, but the description does not explain their relationship (e.g., why both are required, how to obtain them, or how they are used together). This leaves the agent to infer semantics from naming alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get') and the resource ('one design element'), and the qualifier 'one' distinguishes it from the sibling tool list_design_elements. The parenthetical '(with its documentation/description)' adds specificity about the return content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single design element by ID, but it does not explicitly contrast with list_design_elements or state when to choose this tool over alternatives. No exclusions or prerequisites are mentioned; the context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It only says 'Get', implying a read operation, but does not mention return format, permissions, error behavior, or any side effects. The description focuses on value proposition rather than operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the verb and object front-loaded. The trailing clause 'analytics Trello lacks' adds some contextual value but is slightly non-essential. Overall, it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description provides minimal return content (completion %, totals) but lacks enough context to fully guide an agent. It does not address usage distinctions from related metric tools or operational edge cases, making it barely adequate for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It references project_id indirectly as 'a project's metrics' but does not explain the ID format, constraints, or how metrics relate to the parameter. The description mostly mentions output content rather than input semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a project's metrics', specifying content '(completion %, totals)'. It distinguishes from sibling metric tools like get_milestone_metrics and get_board_metrics by scoping explicitly to project-level metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'analytics Trello lacks' implies the tool fills a gap for analytics unavailable in Trello, but it does not explicitly state when to use this tool over alternatives or name sibling metric tools. Usage guidance is mostly implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 lists supported update actions but does not state whether updates are partial or full, what permissions are required, whether changes are reversible, or what the response/error behavior looks like. This is a meaningful transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a compact parenthetical list. It conveys the core purpose and editable fields with no filler, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description does too little. It omits required identifiers (project_id, importance_level_id), outcome/return behavior, preconditions, and any caveats. The description is adequate for identifying the tool but not sufficient for a fully informed invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, but the parenthetical adds some semantic meaning: 're-name' -> name, 're-color' -> color, 're-icon' -> icon, 'set default' -> is_default. However, project_id and importance_level_id are left to inference from their names, and no value formats or constraints are explained, so the description only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update) and resource (importance level), and the parenthetical enumerates the exact editable aspects: re-name, re-color, re-icon, set default. This makes the tool's purpose unambiguous and distinguishes it from create/list importance level tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as create_importance_level or list_importance_levels. There are no prerequisites, exclusions, or decision criteria mentioned, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must disclose behavior, but it only says 'update' with the two actions. It does not mention the schema requirement that 'title' must be supplied even when only marking completion, nor does it describe error behavior or side effects for missing IDs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence that directly states the action and scope, with no wasted words. It is front-loaded with 'Update a sub-task'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is too sparse. It omits the requirement that title must always be supplied, and provides no information about return values, errors, or additional side effects, making it incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps 'rename' to the title parameter and 'complete/incomplete' to is_completed, adding semantic meaning to those fields. However, it fails to explain the required-title quirk and doesn't elaborate on the ID parameters, which are nominally self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb 'Update' with a specific resource 'sub-task' and parenthetical scope 'rename and/or mark complete/incomplete', which distinguishes it from sibling tools like add_subtask, delete_subtask, and update_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like add_subtask or delete_subtask. It does not state prerequisites, exclusions, or alternative tools, leaving the agent to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral context. It only states 'List all HacknPlan projects,' which implies a read-only operation but provides no detail on permissions, return structure, pagination, or the format parameter's effect. This is minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasteful words. It is appropriately front-loaded with the essential action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter, the description is minimally adequate. However, it does not mention the 'format' parameter or clarify what the 'detailed' vs 'concise' formats return. Without an output schema, some return-structure context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the 'format' parameter with an enum, default value, and description. The tool description does not mention this parameter, but since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all HacknPlan projects.' It clearly distinguishes from siblings like get_project (single project) and list_workspaces (workspaces). The scope is explicit with 'all' projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 get_project or list_workspaces. There are no exclusions, prerequisites, or context cues beyond the basic function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only implies a read-only operation via the verb 'List'. It does not disclose any additional behaviors such as output format variations, response structure, or permissions requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that contains no filler. Every word serves a purpose, and it is immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 is too sparse. It does not mention that the tool supports multiple output formats via the format parameter, nor what the return payload contains, leaving an agent with incomplete information for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level meaning; it only restates 'project's tags' which maps to project_id. The schema already describes the format parameter with an enum, but the description doesn't explain how format affects results, leaving the undocumented project_id without added context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('a project's tags'), clearly distinguishing it from sibling tools like create_tag, update_tag, and delete_tag. It unambiguously identifies the object and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, lacks any exclusions or prerequisites, and does not mention any related tools for tag management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the action but does not disclose whether the operation is only for unassigning (vs. deleting), any permission requirements, effects of unassigning a user who is not assigned, or reversibility. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff. It is front-loaded and every word earns its place, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but lacks an output schema and annotations. The description does not explain the return value, whether the operation is idempotent, or any parent constraints (e.g., project ownership). Given the low complexity, it is slightly under-specified but not severely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the relationship between the three parameters (user_id, project_id, work_item_id). The parameter names are self-explanatory, but the description adds no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') with a clear resource ('a user assignment') and context ('from a work item'). This distinguishes it from sibling tools like assign_user and update_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The implied usage is clear—it is the inverse of assign_user—but no exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. The verb 'Get' implies a read-only operation, but the description does not mention side effects, return format, permission requirements, or any other behavioral detail. It is minimal and leaves many assumptions unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the tool's purpose efficiently and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple metric-reading tool with two integer parameters and no output schema, the description provides the metric categories (burndown/completion) but lacks details about return structure, error cases, or authentication. It is minimally viable but leaves gaps an agent must infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters. While project_id and milestone_id are somewhat self-explanatory, the description adds no semantic detail about how to obtain them, their relationship, or any constraints beyond the schema's integer type and required flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('milestone's metrics'), with parenthetical scope ('burndown / completion') that clarifies what kind of metrics. This clearly differentiates it from sibling metric tools like get_project_metrics, get_board_metrics, and get_design_element_metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (whenever milestone-level burndown or completion metrics are needed) but does not explicitly contrast with sibling metric tools or state when not to use it. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing behavior. It only restates the operation implied by the name; it does not mention output details, filtering, ordering, or side effects. The format parameter's behavioral impact is also not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single clear sentence that front-loads the action and object, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the one-sentence description is a minimum viable explanation. However, the presence of a format parameter with three modes, no output schema, and no annotation means the agent gets no guidance on what 'detailed' vs 'json' returns or what category objects contain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents 'format' fully with enum/default, but 'project_id' lacks a description (50% coverage). The description says 'a project's' which hints at project_id but does not define how to supply it or what values are valid; it adds no detail for format beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('a project's work-item categories'), immediately distinguishing it from sibling list tools like list_tags/list_stages. No ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use, exclusions, or alternative guidance is given. The purpose statement implicitly tells the agent this is the read operation for categories, but it does not address when to prefer it over other list tools or mention related create/update/delete category tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 listing action and the dependency direction. It does not mention that this is a read-only operation, the return format, error handling, or any side effects. For a read tool without annotations, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource, and includes clarifying parenthetical information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 output schema or annotations, the description gives the core action but omits information about the response format and any operational context. It is adequate for a basic list, but not fully complete given the lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two integer parameters with zero descriptions. The description clarifies that work_item_id refers to the work item being queried, but it does not explain the role of project_id or provide context on how the parameters relate. With 0% schema coverage, the description should compensate, but it only partially does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and names the exact resource: 'a work item's dependencies' with clarification that they are 'the predecessors that block it.' This clearly distinguishes from sibling tools like add_dependency and remove_dependency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you need to see dependencies of a work item—but it does not provide explicit context, exclusions, or mention of alternatives. There is no when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List'), implying a read-only operation, and gives examples of the content. However, it does not disclose that the list is scoped by project_id or describe the output format, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences that are front-loaded and free of fluff. The second sentence, 'Repurpose as a feature-tree taxonomy,' is a useful tip but slightly tangential; nevertheless, the overall structure is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description defines the domain but omits the required project_id semantics and any details about the response shape. Since there is no output schema and no annotations, the agent must guess these crucial aspects, leaving the tool incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required integer project_id with no description, and the description makes no mention of this parameter. With schema description coverage at 0%, the agent receives no guidance on what project_id means for the request, so the parameter is completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'List' with a specific resource (design-element TYPES), and explains what these types are with concrete examples ('System / Module / Feature'). It also clarifies that these are 'node categories of the design model,' which distinguishes this from listing design elements themselves or from creating design element types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool by defining exactly what it returns. However, it does not explicitly state when not to use it or compare it to alternatives like list_design_elements or create_design_element_type, nor does it mention that the required project_id scopes the results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the functional consequence (successor blocked) but omits operational details such as whether existing dependencies are overwritten, cycle detection, permission requirements, or the response format. This is a mutation tool with minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and immediately explains the effect. Every word adds value; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters and no output schema, the description covers the core behavior but omits the role of project_id and any constraints or side effects. It is adequate for basic use but not fully complete for a mutation tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameter descriptions, so the description must compensate. It provides meaning for work_item_id and predecessor_id by defining their roles as successor and predecessor, but project_id is not explained at all. This partial coverage leaves a gap for one of the three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: making work_item_id depend on predecessor_id, with an explicit explanation of the dependency semantic (successor blocked until predecessor is done). This is a specific verb+resource pair and distinguishes the tool from siblings like remove_dependency and list_dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context by defining the dependency relationship, but it does not explicitly state when to use this tool over alternatives or mention any prerequisites or exclusions. The effect is clear, but there is no guidance on scenario-specific usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It does add the note about default levels, but it does not state that the operation is read-only, how results are ordered, or whether custom levels are included. This is a notable gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the core purpose and an important default in a compact, efficient manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters, but the description does not mention the return structure or how the format parameter affects the output. Given the absence of an output schema and annotations, the description is only partially complete, though it does give the essential purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the 'format' parameter with a clear description, but 'project_id' is undocumented. The description adds meaning by saying 'a project's', which clarifies that project_id identifies the project, but it does not elaborate on format values beyond what the schema already says. Overall, it partially compensates for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('a project's importance/priority levels'), and it distinguishes this tool from sibling list tools such as list_categories and list_tags by specifying the focus on importance/priority levels. The parenthetical '(Urgent/High/Normal/Low by default)' adds detail about the content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit 'when to use' or 'instead of' guidance, but the purpose is self-evident. There are no exclusions or alternative tool references, so the usage is merely implied by the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states it lists subtasks with completion state, implying read-only behavior, but does not explicitly disclose side-effect-free nature, ordering, pagination, or error handling. The 'completion state' adds some return context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, immediate verb, no fluff. Efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and only a terse description, the tool lacks context about required project_id and return structure. It covers the basic purpose but misses parameter semantics and behavioral details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only implies the role of work_item_id ('a work item's'), and does not explain project_id or the relationship between the two. Both parameters are required but the description gives no guidance on their format or semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('a work item's sub-tasks, its checklist') and adds output detail ('with completion state'). It distinguishes itself from siblings like 'list_work_items' and 'list_dependencies'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use whenever a work item's checklist is needed, but provides no explicit when-to-use vs alternatives or exclusions. No mention of 'list_dependencies' or 'add_subtask' for related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 usefully specifies that status must be lowercase, color is hex, and icon is a HacknPlan icon name. However, it does not mention whether the update is partial or full, the effect of changing status on related work items, or any required permissions, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with three brief clarifications. Every sentence element serves a purpose: defining the operation, listing updatable attributes, and formatting constraints. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no annotations, and no output schema, the description should offer more context. It covers status/color/icon well but omits the semantics of 'is_unblocker', whether partial updates are allowed, and any caveats about changing a stage that is in use. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates partially by explaining the status enum, color format, and providing icon examples. It does not clarify 'is_unblocker' or the exact interpretation of required parameters like 'name' beyond their obvious meaning, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (update) with a clear resource (kanban stage) and enumerates the exact aspects that can be changed (re-name, re-color, re-icon, change status). This clearly distinguishes it from sibling tools like update_category or update_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 (e.g., create_stage or update_board). The context is implied by the name and sibling list, but the description does not explicitly state prerequisites, exclusions, or comparison with other update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states the action (update) and the fields, but does not mention that it overwrites existing values, requires prior existence of the tag, or any side effects. The added contextual value beyond the schema is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the main verb and includes a concise parenthetical list of specific operations. Every word earns its place, with zero redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description captures the core function but lacks details about required identifiers and behavior when unspecified fields are not provided. Given no annotations and no output schema, it could benefit from a bit more context to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps to four parameters: name (re-name), color (re-color), icon (re-icon), and display_icon_only (toggle icon-only display), providing meaning beyond raw parameter names. However, it omits the required identifiers tag_id and project_id, which are crucial for identifying the target tag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'update' and enumerates the exact updatable attributes (name, color, icon, display_icon_only), which clearly distinguishes it from sibling tools like create_tag, delete_tag, and attach_tag. It unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying existing tags, but it does not explicitly mention alternatives (e.g., use create_tag for new tags) or when not to use it. There is no explicit guidance on prerequisites such as requiring the tag to already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It adds useful details like ISO 8601 date format and optional milestone nesting, but does not mention permissions, validation, side effects, or response behavior. For a create tool, the core mutation is obvious, but other behaviors remain opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two short sentences front-load the primary action ('Create a board') and then list optional capabilities without waste. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters, no annotations, and no output schema, the description provides the essential creation action and optional parameters, but it does not mention required fields (project_id, name) or what happens after creation. It is sufficient for a simple tool but leaves gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates for some parameters: it explains milestone_id (nesting) and date parameters with ISO 8601 format. However, it does not elaborate on project_id, name, or description parameters, though these are somewhat self-explanatory from the schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'board' and clarifies that a board represents a sprint/iteration, making it distinct from sibling tools like create_project or create_milestone. The core action is immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implicit context (boards can nest under milestones) but does not explicitly state when to use this tool versus alternatives like create_milestone or update_board. No exclusions or prerequisite conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 states the core action (removal of a tag assignment) but does not disclose idempotence, error behavior, or whether the tag itself is deleted. For a simple detach operation, the primary side effect is clear enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter operation with no output schema and no annotations, the description is sufficiently complete; it states the action and target, and little else is needed for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description mentions no parameters. Although the parameter names (tag_id, project_id, work_item_id) are self-explanatory, the description adds no context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and clearly identifies the resource ('tag') and target ('work item'), distinguishing it from sibling tools like attach_tag, delete_tag, and update_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by the name and description, but there is no explicit guidance on when to use this tool versus alternatives like delete_tag. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 correctly implies a read-only operation ('List') and adds context that these are part of a design-doc discussion thread. However, it does not disclose return format, ordering, or any required permissions, which would be valuable for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the verb and resource. It could be slightly more informative without harming conciseness, but it is appropriately compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple read-only tool with no output schema, the description needs to explain what it returns. 'List the comments/notes' implies the return is a list, but it does not explicitly describe the response structure or how the two parameters interact. Given the minimal complexity, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameter semantics. It does not mention project_id or element_id at all. While the parameter names are self-explanatory, the description fails to clarify their role or relationship, adding no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource: 'comments/notes on a design element'. The parenthetical '(design-doc discussion thread)' adds context and distinguishes it from sibling tools like add_design_element_comment and get_design_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the tool's function, implying it is used when you need to view comments or notes on a design element. However, it does not explicitly name alternatives or when-not scenarios, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and return fields, but does not disclose whether authentication is required, whether the project must exist, pagination behavior, or any side effects. This is minimal for a 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource, with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and no output schema, but the description is quite sparse. It lacks context about prerequisites, authentication, pagination, or other behavioral aspects. However, for a straightforward list operation, the basic purpose is adequately conveyed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should clarify parameter semantics. It mentions the output includes id and username, but the single project_id parameter's meaning is only implicit from the phrase 'of a project'. This adds little beyond the schema, which already specifies it as a required integer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' with the resource 'members of a project', and clarifies the return fields (id, username). This clearly distinguishes it from sibling tools like list_projects or get_project, which address different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need the members of a particular project, which is clear given the project_id parameter. It does not explicitly mention when not to use it or alternatives, but no direct sibling tool serves the same purpose, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only operation by using 'List', but it does not mention ordering, authorization requirements, pagination, or behavior when no logs exist. It adds minimal context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the core action and object efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is mostly adequate given the two-parameter schema and no output schema. However, it lacks any mention of return format or edge cases, and the absence of annotations means the agent must infer behavior from the term 'List' alone. Still, it is not severely incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It only mentions 'on a work item' which maps to work_item_id, but project_id is left unexplained. The schema provides names and types but no descriptions, so the agent gains little additional semantic meaning from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a specific resource 'work logs (time entries)' on a work item, making the operation unambiguous. It clearly distinguishes from sibling tools like 'log_work' (which creates time entries) and other list-type tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The context is implied: one uses this to retrieve time entries for a work item, but no alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a valuable behavioral trait: logs can only be edited within ~1 hour of creation. It also explains the value unit (hours or points). However, it does not mention permissions, return values, or idempotency, leaving some behavioral aspects opaque.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding essential information: the purpose, the parameter semantics for value and comment, and a critical behavioral constraint. It is front-loaded with the primary action and contains no redundant or irrelevant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, no annotations, no output schema), the description covers the core usage well: what it does, the value unit, optional comment, and edit window. It does not mention what the tool returns or potential error cases, which are relevant for a mutation operation. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clearly explains 'value' as the amount worked in the project's costMetric unit, and 'comment' as an optional note. The remaining parameters, project_id and work_item_id, are left to be inferred from their names, which is reasonable but not explicitly clarified. This provides partial compensation for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Log time/effort on a work item.' This uses a specific verb ('log') and resource ('work item'), and adds scope by defining the value unit and edit constraint. It readily distinguishes itself from sibling tools like list_work_logs (read-only) and add_comment (different purpose).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recording effort but provides no explicit when-to-use or alternative guidance. Siblings like list_work_logs for viewing or add_comment for notes are not mentioned. The edit constraint gives some context but does not clarify when to choose 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Update' without disclosing behavioral traits such as partial update semantics, side effects, permission requirements, or whether all fields are optional. This leaves the agent without critical information about how the update behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extra words, effectively conveying the tool's purpose and fields. It is front-loaded and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description covers the core fields and enum values, but lacks behavioral context such as partial update behavior, prerequisites, or return value. No output schema exists, so not explaining return values is acceptable, but the description is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates by naming the updatable fields and explicitly specifying allowed cost metric values ('Hours' or 'Points'). This adds meaning beyond the raw schema, though it does not describe the required project_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' with a specific resource ('a project') and explicitly lists the fields (name, description, cost metric). It distinguishes from sibling tools like update_work_item or update_design_element by naming the project scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action 'Update a project', but no explicit context or alternatives are mentioned. There are no exclusions or guidance on when to prefer this over other update tools, making it adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses the core state-changing behavior ('Reopen a previously closed board/sprint') and the precondition ('previously closed'). However, it does not mention idempotency, error handling for already-open boards, permissions, or side effects, which leaves some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource, includes a useful counterpart reference, and contains no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-ID mutation tool, the description adequately conveys the primary purpose and relationship to close_board, but lacks details such as behavior when the board is already open, required preconditions beyond 'previously closed', or what response to expect. No output schema or annotations increase the burden on the description, so this is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema contains two required integer parameters (project_id, board_id) with no descriptions, and the description adds no parameter-level meaning. With 0% schema description coverage, the description should compensate but does not; only the self-explanatory parameter names provide minimal guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Reopen' and identifies the resource as 'previously closed board/sprint', which clearly states the tool's action and scope. It also mentions 'counterpart to close_board', uniquely distinguishing it from sibling reopen tools like reopen_project and reopen_milestone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating the tool is for previously closed boards/sprints and explicitly identifies it as the counterpart to close_board, implying it should be used to reverse a close_board action. However, it does not explicitly list when not to use it or name alternative tools, though the sibling distinction is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It states the core action ('reopen') but does not mention permissions, reversibility, side effects on related entities (e.g., boards, milestones), or what happens to the project's state after the operation. This is minimal for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It immediately states the action and condition, earning its place with high efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter state-change tool, the description provides the essential context (what and when). It lacks details about return values or side effects, but in the absence of an output schema and with a simple resource type, this is adequate. The sibling context (close_project) is not explicitly referenced, but the tool's purpose is clear enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The only parameter, project_id, is self-explanatory by name, but the description does not add any detail about its format, requiredness, or relationship to the target project. The trivial nature of the parameter keeps the score at a baseline level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reopen') and resource ('project'), and clarifies the scope with 'previously closed/archived'. This distinguishes it from sibling tools like reopen_milestone and reopen_board, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'previously closed/archived' provides clear context for when to use the tool: when a project is in a closed or archived state. It doesn't explicitly mention alternatives, but the condition is enough for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that comments support markdown and are capped at 5000 characters, and the verb 'Add' clearly implies a non-destructive mutation. It does not mention permissions or return values, but these are less critical for a simple comment-add operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource, with parenthetical constraints. Every word earns its place; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create-type tool with three required parameters, the description covers the core operation and a key constraint. However, it does not mention any connection to project or element IDs, nor does it address when to use this versus the sibling 'add_comment' tool. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It adds meaning to the 'text' parameter by noting markdown and character limits, but it does not clarify the 'element_id' and 'project_id' parameters beyond their self-explanatory names. While those names are intuitive, the description still leaves some semantic burden on the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Add' and the resource 'design element' clearly, making it unambiguous what action is performed and on what. It also provides distinguishing details (markdown support, 5000 char limit) that go beyond a bare label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the resource type ('design element'), which tells the agent when to use this tool. However, there is no explicit mention of alternatives or exclusions, such as noting that 'add_comment' is for work items instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It explicitly says 'Destructive' and instructs 'set confirm=true to proceed', which are critical behavioral traits. However, it does not disclose cascading effects or permanence beyond the term 'destructive'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences. No fluff, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but lacks output schema and annotations. The description covers the basic action and confirmation requirement, but does not explain return values, failure modes, or side effects like cascading deletion. This is adequate for a simple delete tool but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives meaning to the confirm parameter by stating it must be true to proceed. It does not explain project_id and work_item_id beyond their schema types, despite 0% schema coverage. The parameter names are self-explanatory but not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a work item' — a specific verb and resource, and the destructive warning distinguishes it from update or create operations. Among siblings, it clearly targets only work items, not design elements or milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative comparison provided. Usage is implied: to delete a work item, use this. There is no mention of when not to use or which alternative to choose for similar resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It indicates a read-only retrieval by using 'Get' and describes the returned contents (stages, categories, etc.), but does not mention permissions, error behavior, or any special side effects. This is acceptable for a simple fetch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's action, scope, and usage context. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter, the description is fairly complete. It lists the included related entities and gives usage context. It could mention the return structure in more detail, but the provided information is sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does not mention project_id or its role, relying on the tool name and schema. Since there is only one obvious parameter, the gap is minor, but the description still adds no explicit value beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a single project along with its stages, categories, importance levels, and boards. It distinguishes itself from list_projects by emphasizing the rolled-up structural overview, which is unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context, stating that the tool is the 'structural overview you need before creating work items.' This implies when to use it, though it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses that the tool aggregates all projects and returns computed metrics and flags, grouped via HACKNPLAN_GROUPS. However, it doesn't explicitly state it's read-only, mention data freshness, permissions, or any side effects. Since it's an overview tool, read-only is implied, but the description could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The key phrase 'ALL-PROJECTS birds-eye view' is front-loaded, and every word in the description earns its place. It efficiently communicates purpose, content, and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers the output content (completion %, open/closed counts, flags) and purpose. It could mention how the 'format' parameter affects the returned representation, but that's reasonably inferred. HACKNPLAN_GROUPS isn't explained, but it's likely external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'format' has a clear enum (markdown/json) and default, but the description never mentions it. With schema_description_coverage at 0%, the description should compensate by explaining when to choose which format, but it doesn't. The parameter is self-explanatory from the schema, but the description adds no value beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'ALL-PROJECTS birds-eye view' and clearly states it rolls up every project with completion %, open/closed counts, and flags. It distinguishes itself from siblings by claiming it's a cross-project dashboard with no native equivalent, setting it apart from project-specific tools like get_project_metrics or get_milestone_metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states ideal use cases: 'how's everything doing', 'what's on fire across all projects', 'portfolio status'. This gives clear context for when to invoke. It doesn't explicitly mention when not to use it or name alternatives, but the context and sibling tools imply it's for portfolio-level queries rather than project-specific ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It does reveal the important requirement that confirm must be set to true, which is a useful safety detail. However, it does not mention the destructive nature of the action, permissions, or the consequence of not setting confirm, leaving other behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the action and a key requirement without any extraneous information. It earns its place and is highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with no output schema and no annotations, the description covers the essential action and the confirm requirement, but it omits details about return values, error conditions, or what happens if confirm is false. This makes it minimally complete but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by explicitly stating that confirm=true is required, and the phrase 'from a work item' clarifies the relationship between work_item_id and dependency_id. This partially compensates for the 0% schema coverage, but the other parameters (project_id, work_item_id, dependency_id) are not individually described beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove'), the object ('a dependency'), and the context ('from a work item'), which makes the tool's purpose unambiguous and distinguishes it from sibling tools like add_dependency and list_dependencies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (removing a dependency) and adds a critical usage condition (confirm=true required). However, it does not explicitly mention alternatives or situations where this tool should not be used, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses markdown support and a 5000-character limit, which are behavioral traits. However, it does not mention permissions, side effects, or return values, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key constraints without any fluff. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add-operation tool, the description covers the core purpose and important constraints. It lacks explicit usage guidance and return value info, but the absence of an output schema reduces the need for describing return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions, but the description partially compensates by specifying that the comment supports markdown and has a max length, which applies to the 'text' parameter. The roles of project_id and work_item_id are implied via 'work item' but not explicitly defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' with a clear resource 'comment to a work item', and includes useful constraints (markdown supported, max 5000 chars). This distinguishes it from sibling tools like add_design_element_comment, which targets a different resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for work item comments, providing context for when to use it. However, it does not explicitly state when not to use it or name alternatives such as add_design_element_comment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the nesting behavior and rollup effect, but omits details about return values, error conditions, permissions, or side effects beyond creation. This is acceptable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence defines the purpose, and the second explains key parameters and the rollup behavior, making it well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description covers essential semantics: what constitutes a root vs. nested element and how progress rolls up. It lacks details on validation or response, but the core usage context is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description meaningfully explains type_id and parent_id, which are the least obvious parameters. However, project_id and name are not addressed, and the schema has no descriptions, so the description only partially compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a design element as a node in the design/feature tree, using a specific verb and resource. It distinguishes this from sibling tools like update_design_element and delete_design_element, and clarifies the tree-nesting concept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidance for parent_id (omit for root) and explains the purpose of linking work items to enable progress rollup. It does not explicitly exclude alternative tools, but the context for when to use create vs. update/delete is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses a key behavioral trait: closed milestones are hidden unless include_closed=true, which tells the agent an important default behavior. It does not mention auth, rate limits, or error handling, but for a read-only list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the primary purpose; the second adds a critical behavioral detail. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description sufficiently covers the core action and a key default behavior. It does not explain output format options or return fields, but the schema documents the format parameter, and no output schema exists to be supplemented. The description is complete enough for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate for undocumented parameters. It adds meaning to include_closed by explaining its effect on visibility. project_id is self-evident from the description, and format is already described in the schema. This partial compensation is adequate but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'a project's milestones', with clarifying 'release/epic groupings' to define what milestones are. This distinguishes it from sibling list tools such as list_stages, list_tags, and list_boards, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to list a project's milestones but does not explicitly state when to use it over alternatives like get_milestone_metrics for metrics or list_work_items for work items. It provides a parameter-related guideline (include_closed) but lacks clear use-case boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It reveals that only open items are returned by default, that include_closed toggles finished items, and that the tool relies on inline assignee data from the list endpoint. However, it omits details like pagination, sorting, or potential rate limits, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, and every sentence adds relevant information (purpose, default behavior, dependency). There is no redundant wording or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only list with three optional parameters and no output schema, so the description does not need to be extensive. It covers the core purpose, scoping, default filtering, and a key flag. It falls short of fully explaining the format parameter and potential edge cases, but for its simplicity it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It clarifies include_closed ('set include_closed=true to see finished ones') and hints at project scoping via 'optionally scoped to one project', but it does not explain the format parameter or the exact type/meaning of project_id. Two of three parameters are partially addressed, but format remains unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List work items assigned to the authenticated user (from /users/me)', with a specific verb and resource. It also names the use case ('what am I working on / standup view') and distinguishes it from broader list tools like list_work_items by emphasizing the personal scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool—as a personal standup view scoped to the authenticated user, optionally filtered by project. It does not explicitly name alternative tools or exclusion criteria, but the context strongly implies differentiation from other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 discloses key behaviors: task inheritance of fields, optional checklist creation, and the return value. However, it omits potential side effects like atomicity, failure modes, or permissions, which would enrich transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The opening phrase 'Break a feature down in ONE call' immediately conveys the core value. Every sentence adds substantive information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and no output schema, the description covers the essential workflow, inheritance rules, and return values. It does not explain prerequisites like project existence, but the schema's required fields imply the minimum. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the inheritance relationship between top-level fields (importance_level_id, default_category_id, board_id, milestone_id) and task-level overrides, and introduces sub_tasks as checklists. It does not cover every parameter like default_estimated_cost, but provides valuable context for the most complex interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool breaks a feature into a user story and child tasks in one call, which is a specific verb+resource. It distinguishes itself from siblings like create_work_item and add_subtask by being the 'fast path' for this combined operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'This is the fast path for 'turn this feature into a story with tasks'', giving clear context for when to use it. It implies alternatives (manual step-by-step creation) without naming them explicitly, but the sibling list offers the contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the action 'marks it done without deleting it' and is reversible, which are key behavioral traits beyond the tool name. It does not mention permissions or side effects on other entities, but for a simple state-change tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded, two-part sentence that conveys purpose, non-destructive behavior, and reversibility. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with no output schema and no annotations, the description is quite complete: it explains the effect ('marks it done'), the non-deletion guarantee, and the reversal path. It does not detail return values or prerequisites, but these are not critical for understanding how to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its two required parameters (project_id, milestone_id), and the tool description does not mention or explain them. The parameter names are self-explanatory, but the description adds no meaning beyond the schema property names, so it fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Close (release)' with a clear resource ('a milestone') and explicitly distinguishes itself from deletion ('without deleting it') and from the reverse operation ('reopen_milestone'). This fully differentiates it from sibling tools like delete_milestone and update_milestone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (to mark a milestone done while preserving it) and mentions the alternative 'reopen_milestone' for reversal. However, it does not explicitly state when not to use it (e.g., versus delete_milestone) or provide prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It reveals important behavior: the API always creates items in the default/first stage unless stage_id is provided, and stage_id moves the item after creation. However, it does not mention permissions, error conditions, or the return value, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that is concise and front-loaded with the purpose. Every sentence provides useful information, though it could benefit from bullet points or clearer separation of requirements versus optional fields. Still, it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters, no annotations, and no output schema, the description covers many important aspects: required fields, task vs story differences, hierarchy, dependencies, dates, and stage behavior. It is not exhaustive (missing some optional parameters and error/return information), but it is substantially complete for a create tool, especially compared to typical descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the semantics of many parameters: importance_level_id, category_id, parent_id, assigned_user_ids, dependency_ids, sub_tasks, due_date/start_date, and stage_id. It does not explain all parameters (e.g., tag_ids, board_id, is_story, estimated_cost), but it covers the most critical ones, adding significant value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a work item (task or user story), distinguishing it from update/delete operations. It also immediately clarifies the two types of work items and key properties like parent_id for nesting, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on required fields (title, importance_level_id) and where to fetch IDs from (get_project/list_*). It also explains when category_id is required and how parent_id establishes hierarchy, but it does not explicitly name alternatives like update_work_item or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds the date format constraint (ISO 8601) and enumerates allowed update operations, but does not mention side effects, permissions, error behavior, or idempotency. This leaves gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant information. Every phrase adds value, listing the main update scenarios and the date format in a compact way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no annotations, and no output schema, the description provides a solid overview but does not cover expected return values, error handling, or prerequisites (e.g., whether project_id and board_id must correspond). It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It does so by mapping several schema parameters (name, start_date, due_date, description, milestone_id) to the listed use cases. It does not explain project_id and board_id, but those are required and inferable from the tool name and 'board/sprint' context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a board/sprint and lists specific updateable attributes (rename, change start/due date, description, re-nest under milestone). This distinguishes it from sibling tools like update_project or update_milestone, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it obvious this tool is for boards/sprints, not for projects or milestones. However, it does not explicitly mention alternatives or provide exclusion criteria, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates key traits: archiving preserves data, does not delete, and is reversible. It does not mention permissions or side effects, but covers the essentials for a close operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and every part adds value. It is concise and well-structured with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter operation with no output schema, the description provides sufficient context: it explains the effect, preservation of data, and reversibility. Minor details about post-close status are not critical and do not significantly impact completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one required integer param (project_id) with no description, and the tool description does not mention it. However, the param's meaning is self-evident from the tool name and param name, so the lack of explicit explanation is a minor gap. Schema coverage is 0%, but the simplicity of the param mitigates the need.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Close (archive)') and resource ('a project'), and explicitly contrasts with deletion ('without deleting it'), distinguishing it from sibling tools like delete_project. The resource and behavior are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the tool archives a project rather than deleting it, and explicitly references reopen_project as the inverse operation. However, it does not explicitly state when to prefer this over alternatives beyond contrasting with deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behaviors: workspaceId auto-assignment to personal workspace, echoing back as 0, and the return of the new project. This adds value beyond the schema, though it does not cover potential side effects or permissions, which are less critical for a create tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using four short sentences. It is front-loaded with the core action, followed by essential behavioral details. Every sentence adds value without redundancy, making it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description adequately covers the return value and a key behavioral quirk. It does not explain hours_per_day or provide usage guidance versus siblings, but it is reasonably complete for a create operation with clear attribute names and defaults in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clarifies cost_metric by specifying the exact string values and capitalization, but does not explain name, description, or hours_per_day beyond their schema names. The workspaceId mention is about a response field, not a parameter, so it does not fully cover all parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a project' with a specific verb and resource. It distinguishes from sibling tools like create_work_item or create_milestone by naming the resource directly. The additional details about cost_metric and workspaceId reinforce the specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use, including the cost_metric format and workspaceId auto-assignment. It does not explicitly mention alternatives or when not to use the tool, but the context is sufficient for a create operation that is self-explanatory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states 'Destructive' and 'confirm=true required', which are crucial behavioral traits for a deletion operation. It could elaborate on consequences for associated work items, but the destructive warning and confirmation requirement are strong disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and safety warning. Every sentence adds value: the action, the destructive nature, the confirm requirement, and a practical use case. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with three parameters and no output schema, the description covers purpose, destructiveness, confirm requirement, and a suggested use case. It doesn't mention what happens to work items assigned to the category, but 'Destructive' hints at potential data impact. Overall, it is fairly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. 'confirm=true required' clarifies the boolean confirm parameter's necessity and role. The other parameters (project_id, category_id) are self-evident from their names and the schema, so the description adds sufficient meaning for the key non-obvious parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a work-item category', which is a specific verb and resource. It distinguishes this tool from siblings like delete_tag, delete_stage, and delete_work_item by specifying the target as a work-item category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete use case: 'Useful to remove the game-dev defaults — Audio, Narrative, etc.' This gives clear context for when this tool is appropriate. It doesn't explicitly mention alternatives, but the use case implies its specific role without needing exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly discloses destructive behavior, cascading deletion of the sub-tree, and the requirement for a confirmation flag. This goes beyond the basic action and provides critical safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: three short sentences, each adding essential information. It is front-loaded with the main action and follows with critical warnings, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description covers the key aspects: what is deleted (including sub-tree), that it is destructive, and the confirmation requirement. It does not detail return values or effects on other related data, but those are less critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for parameters. The description explains the role of 'confirm', but 'project_id' and 'element_id' are left to their names, which are reasonably self-explanatory. It compensates partially but not fully for the lack of schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('design element'), and further specifies the scope ('and its sub-tree'). This distinguishes it from sibling tools like update_design_element or get_design_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose of the tool is clear, but there is no explicit guidance on when to use it versus alternatives or when not to use it. The 'confirm=true required' note serves as a prerequisite, but the usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden of behavioral disclosure. It conveys that this is a read-only operation ('Get'), lists the metrics returned, and discloses an optional user_id scoping behavior. It doesn't mention permissions or edge cases, but for a simple read tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the main action and resource. Every word earns its place; it is concise and structured effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description covers the core purpose and optional scoping well. It doesn't detail the exact return structure of the metrics, but that is not essential for invoking the tool. Minor gaps like clarifying project_id's role prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explicitly explains user_id's purpose ('scope to one user') but does not explain project_id or board_id. However, their names are reasonably self-evident, and the description does clarify that board refers to a sprint. This is partial compensation, not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Get a board's (sprint's) metrics' and even lists the metric types (burndown / velocity / completion). This distinguishes it from sibling tools like get_project_metrics and get_milestone_metrics, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need board/sprint metrics, and optionally filtered by a user. It does not explicitly name alternatives or exclusions, but the context is clear enough given the sibling tool names. A higher score would require explicit 'use X instead for project metrics' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the roll-up aggregation behavior and the effect of include_children, which is valuable. However, it does not specify what metrics are included or any prerequisites or limitations, leaving some ambiguity about the exact return payload.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that get to the point. The description avoids redundancy and clearly front-loads the primary purpose before explaining the parameter nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's core behavior and the key parameter nuance for a simple read operation. However, it does not enumerate the specific metric fields returned or any error conditions, which would be helpful given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions (0% coverage), but the description explains the include_children parameter's effect and clarifies the aggregate nature of the result. project_id and element_id are self-evident from the tool's scope, and required fields are implied by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves metrics for a design element, with a specific explanation of how work is rolled up. This distinguishes it from sibling tools like get_project_metrics and get_milestone_metrics, which target different entities. The mention of include_children adds behavioral specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to prefer this tool over get_project_metrics or get_milestone_metrics. The usage is implied by the tool's name and the description's focus on design elements, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of disclosure. It adds value by specifying that the response includes sub-tasks and comments, not just the work item itself. It doesn't mention permissions, error handling, or output format, but for a simple retrieval tool this is minimally sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It is front-loaded with the verb and resource, then appends the specific included elements. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two well-named integer parameters and no output schema, the description covers the core purpose and key inclusions (sub-tasks and comments). It doesn't address ordering, pagination, or error behavior, but these are not essential for a basic get operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It does not explicitly define project_id and work_item_id, but the parameter names are self-explanatory within the context of 'get one work item'. This is adequate but not enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'one work item' and specifies the included sub-items (checklist and comments). This clearly distinguishes it from sibling tools like list_work_items, which likely returns multiple items, and other work item tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need a single work item with its checklist and comments. It provides clear context but does not explicitly name alternatives or exclusion criteria, which would push it to a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well by disclosing that the default board is 'Sprint 1' and that closed boards are hidden unless include_closed=true. This adds meaningful behavioral context beyond the schema. It does not mention auth requirements or output format details, but for a list operation these are less critical. It's not a tautology and adds genuine value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose. No filler or redundant content. Every word carries weight, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 3 parameters and no output schema, the description covers the essential context: purpose, default behavior, and visibility of closed boards. It does not explain return value structure, but that's expected without an output schema. Slight deduction for not providing any guidance on when to prefer this over other board-related tools, but overall it's sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'format' described. The description compensates by explaining the include_closed parameter (closed boards hidden unless true) and implying the project_id parameter (boards of a project). However, it does not add meaning for 'format' beyond what the schema already provides, and the 'Sprint 1' default is about boards, not a parameter. Overall, partial compensation for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing a project's boards (sprints/kanban boards). It distinguishes itself from sibling tools like create_board, update_board, close_board, and reopen_board by being the read-only listing operation. The mention of default 'Sprint 1' and include_closed behavior adds specificity beyond a generic 'List boards'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it to list boards for a specific project, with an optional include_closed flag. It does not explicitly name alternatives or state when not to use it, but the context strongly implies it is the go-to listing tool as opposed to creation/modification/deletion siblings. Slight deduction for not explicitly excluding other list tools like list_milestones or list_stages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses useful behavioral details: defaults for `from` (7 days ago) and `to` (now), and the ISO 8601 format. However, it does not mention return format, sorting, pagination, or potential limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, parameter behavior, and use cases. The description is front-loaded with the core purpose and contains no redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool, it covers purpose, parameters, defaults, and use cases. No output schema exists, but the 'activity/event feed' concept is clear. Some details like event types or sorting are missing, but the description is sufficiently complete for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains `from` and `to` with their defaults and ISO 8601 format. The required `project_id` is not explicitly described but is inferable from the tool's name and context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a project activity/event feed with the specific verb 'returns events' between date ranges. It differentiates itself as the 'what changed' / standup view, distinguishing it from simple list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: 'what happened this week', 'recent changes', daily standups.' This gives clear context on when to use the tool, though it doesn't explicitly state when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It reveals the tool's global scope, the bucketing logic (Overdue / This week / Next 2 weeks / This month / Later), and the live days-left countdown. It does not explicitly state read-only behavior or response structure, but the description gives substantial insight into the tool's operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the core purpose ('ALL-PROJECTS deadline countdown') and then packs in scope, bucketing details, and example use cases. There is no redundant or filler content; every element contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema or annotations, the description provides a strong mental model: scope (all projects, all due-date work items), grouping (time horizons), and purpose (deadline awareness). It does not detail the exact output format beyond the buckets, but for a simple overview tool the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'format', is fully described by the schema's enum (markdown/json) and default value, so the description's lack of param detail is not a major gap. However, since schema_description_coverage is 0%, the description adds no meaning beyond the schema and does not compensate for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'ALL-PROJECTS deadline countdown — every work item that has a due date, across every project'. It clearly defines the tool's scope and differentiates it from project-specific tools like get_project_metrics or portfolio_overview by emphasizing it covers all projects. The bucket definitions further clarify exactly what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: "Use for 'what's due soon', 'what's overdue', 'deadlines', 'what should I do this week'." This provides strong context, though it does not mention exclusions or explicitly contrast with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It discloses that type_id and name are required by the API and that passing current values preserves them, implying a partial update behavior. However, it does not mention return values, permission requirements, or side effects of re-parenting, leaving some uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and a concise list of operations, followed by essential usage guidance. Every sentence contributes meaning without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool with no annotations or output schema, the description covers core semantics, required fields, and a recommended pre-step. It lacks details on return values or error scenarios, but given the straightforward nature of the update, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by mapping operations to parameters: rename maps to name, edit documentation to description, re-parent to parent_id, and change type to type_id. It also clarifies the role of required fields. It doesn't explicitly explain project_id and element_id, but these are inferable from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update a design element' and enumerates specific operations (rename, edit documentation, re-parent, change type), making it clear what the tool does and distinguishing it from sibling tools like delete_design_element or get_design_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to call get_design_element first to read current values and explains that type_id and name must be passed with current values to preserve them. This provides clear context on prerequisite steps and how to avoid overwriting fields, though it doesn't explicitly list alternative tools for similar actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive nature and nuances: 'work items are un-grouped, not deleted' and 'confirm=true required.' This goes beyond a simple deletion notice and clearly explains the behavioral impact on work items.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by essential warnings and a requirement. No filler or redundant content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description covers the key aspects: the action, destructiveness, effect on associated work items, and the required confirmation. Combined with the schema's parameter definitions, it provides sufficient context for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the 'confirm' parameter's required value and its role, but does not describe 'project_id' or 'milestone_id'. Their names are self-explanatory, so partial compensation is provided, but not full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a milestone' with a specific verb and resource, clearly distinguishing the action from sibling tools like close_milestone, reopen_milestone, and update_milestone. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a precondition ('confirm=true required') and a cautionary note about destructiveness, but does not explicitly instruct when to use this tool versus alternatives like close_milestone. Some context is implied, but no exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly warns that the action is 'Destructive' and requires 'confirm=true', and states that it deletes 'everything in it', disclosing the cascading effect. This is strong behavioral disclosure for a delete operation, though it could also mention irreversibility or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. It front-loads the action, immediately states scope, and includes the essential safety requirement. Every word adds value, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete tool with two parameters and no output schema, the description covers the essential points: what is deleted, the destructive nature, and the confirmation requirement. It could be enhanced by explicitly stating that the action is irreversible or by noting any permissions needed, but it is largely complete for making an informed invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only types for project_id and confirm, with 0% description coverage. The description adds critical meaning by explaining that confirm must be set to true for the deletion to proceed. project_id is self-explanatory from the name and tool context, so the description sufficiently compensates where needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete an ENTIRE project and everything in it.' It identifies the specific resource (project) and scope (entire project including contents), which distinguishes it from sibling tools like delete_work_item or delete_design_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to delete a whole project and everything in it. It does not explicitly list alternatives or when-not to use it, but the context is unambiguous. The instruction to set confirm=true also implies a controlled usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it explicitly labels the operation 'Destructive', states the constraint on stage count/status, and discloses that confirm=true is mandatory. It does not mention side effects on work items in the stage or permanence beyond 'destructive', but the core behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the verb. Every sentence adds value: the first states the action, the second gives essential constraints and the confirmation requirement. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with no output schema, the description covers purpose, destructive nature, the business rule, and the confirm requirement. It is missing details on what happens to work items in the stage, which is a notable gap, but the description is still fairly complete for its complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds critical meaning for confirm by requiring it to be true, and the project/stage budget rule gives context for project_id and stage_id. The two IDs are self-explanatory from their names and the tool's purpose, so the description sufficiently compensates despite not explaining them individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a stage' – a specific verb and resource. It distinguishes this from sibling delete tools (delete_project, delete_work_item, etc.) by naming the resource explicitly. The additional context about the minimum 3 stages and one-per-status rule further clarifies the tool's specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it warns that the operation is destructive, explains a business rule constraint (project needs >=3 stages), and mandates confirm=true. This tells the agent when deletion is appropriate or blocked. It does not explicitly name alternatives, but the resource-specific name and context make the scope clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses query matching behavior (case-insensitive, title/description), optional facet filters, and the default status ('open'). It does not mention output format or pagination, but those are at least partially covered by the schema's default for 'limit' and the 'format' parameter description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: front-loaded with the core purpose, then compactly listing filters and status semantics. Every phrase earns its place, and there is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 8 parameters and no output schema, the description covers the main required context: search semantics, filters, status default, and a typical use case. It could additionally describe the return shape or the effect of 'limit', but it gives enough for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (13%), so the description compensates by explaining the semantics of query, importance, tag, stage, and status. The remaining parameters (project_id, limit, format) are either self-explanatory or already documented in the schema. This is strong added value, though not exhaustive for all eight parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('a project's work items'), and clearly distinguishes this from list/scan operations by calling it 'the name-based lookup that saves chaining list→scan→act.' It also states what matches (title or description), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: use this to resolve a task known by name into its id before update_work_item or similar actions. It also implies the alternative of chaining list→scan→act, but does not explicitly say when *not* to use this tool versus list_work_items or get_work_item, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the operation as returning user details, implying a read-only action, and adds context about confirming the API key. While it doesn't explicitly state 'no side effects,' the nature of a whoami call is inherently safe and well-understood.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence plus a short usage directive. It is front-loaded with the primary purpose and contains no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is complete. It specifies exactly what the return value contains (id, username, email, name) and when to use it. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The baseline for zero params is 4, and the description correctly omits parameter details since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Return the authenticated HacknPlan user (id, username, email, name).' This is unambiguous and distinct from all sibling tools, which are CRUD/management operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Use first to confirm the API key works' provides explicit when-to-use guidance, positioning this as a preliminary sanity check. It does not explicitly mention when not to use or alternatives, but the purpose is clear enough for a whoami tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that filtering is done server-side, that filters combine with AND logic, that results are paginated, and that text performs a free-text match. It doesn't specify output format details or error/ordering behavior, but it reveals the core behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, followed by compact parameter and usage details. No fluff; every clause adds informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 15 parameters and no output schema, the description covers the essential usage: filter semantics, pagination, and an alternative tool. It lacks return structure and ordering, but those gaps are partially mitigated by the absence of an output schema and the typical nature of a list operation. Overall, it is complete for practical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 7% (only the format parameter has a description). The description compensates by naming all filter parameters and adding meaning: AND-combination, status enum values, text free-text match, and pagination. While each filter isn't individually expanded, the description provides significant semantic context for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List/search a project's work items,' and immediately clarifies the server-side filtering capability. It explicitly differentiates from sibling find_work_items by recommending it for 'forgiving name-based search,' which makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states all filters are optional and AND-combined, enumerates them, explains the status enum values, notes pagination via limit/offset, and gives a clear alternative tool for a use case. This is explicit when-to-use guidance with exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals the partial-update semantics and warns that assigned_user_ids replaces the entire assignee set. It does not describe side effects or return values, but the core non-obvious behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the core action, lists specifics, and ends with a critical usage tip. Every phrase adds value without redundancy or fluff, making it concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 16 parameters and no output schema, the description fully explains the tool's capabilities and the partial-update model. It provides enough context for an agent to select and invoke the tool correctly, especially with the required project_id and work_item_id indicated in the schema. The missing requirement info is already in the schema, so the description's coverage is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It maps each parameter to its semantic action (e.g., importance_level_id to 're-prioritize', assigned_user_ids to 'reassign'), covering all 16 parameters implicitly. It also clarifies the replacement behavior for assigned_user_ids.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'partial update' on a work item, enumerating specific actions like moving stages, retitling, editing descriptions, and more. It distinguishes itself from siblings (create, delete, design element updates) by focusing on partial updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Provide only the fields you want to change,' giving clear guidance on how to invoke the tool. It covers implied use cases via the enumeration, but does not explicitly name alternatives for exclusion (e.g., use create_work_item for new items). Given the sibling list, the context is clear, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavioral traits. It goes beyond the schema by revealing that both color and icon are required despite schema defaults, and that omitting icon returns HTTP 500. This is critical, non-obvious behavior that directly impacts tool invocation, making the description highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with three sentences, each adding distinct value: purpose, status constraint, and critical field requirements with examples. It is front-loaded and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential usage quirks and constraints for this create operation in the absence of annotations and output schema. It lacks explicit mention of return value or any side effects, but given the schema explicitly lists required parameters (project_id, name), the description adequately supplements the structured data. A minor gap exists in not stating what the tool returns, but this is not critical for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero descriptions for parameters, so the description fully compensates. It explains the meaning of status (enum values), explicitly states that color and icon are both required despite schema defaults, and gives examples of valid icon names. This significantly enriches the parameter understanding beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a kanban stage, using the verb 'create' and the resource 'kanban stage'. This is unambiguous and distinguishes it from sibling tools like update_stage or delete_stage, as it specifically describes a creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage constraints (status must be one of the listed values, both color and icon are required) which inform how to use the tool. It does not explicitly mention alternatives or when-not to use it, but the purpose is clear enough that the tool's use case is evident. It could be improved by explicitly stating 'to update a stage, use update_stage' but the lack of that is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly labels the operation as destructive, discloses the cascading side effect on all work items, and requires confirm=true as a safety gate. This is significant, actionable behavior context that prevents accidental destructive calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: purpose, destructive warning with specifics, and confirmation requirement. Front-loaded, zero filler, and highly scannable. This is exemplary concise writing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with no output schema and no annotations, the description covers all critical aspects: what it deletes, the destructive consequence, and the required safety parameter. The tool is simple enough that no additional context (e.g., permissions or error conditions) is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds semantics for the confirm parameter by explaining it must be true, which is the only non-obvious parameter. The project_id and tag_id parameters are self-evident from the tool name and schema structure, so the description adequately supplements the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a tag.' It further clarifies the scope by noting 'removes it from all work items,' which distinguishes it from sibling tools like detach_tag (which only removes a tag from one work item) and update_tag. This unambiguous action-resource pairing is exactly what an agent needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by identifying the destructive global effect and stating the confirmation requirement ('confirm=true required'). However, it does not explicitly name alternative tools (e.g., detach_tag) or state when not to use it, so it falls short of explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for disclosing behavioral traits. It reveals a non-obvious and potentially confusing behavior (empty list for personal accounts despite a workspace existing in the UI) and clarifies that only Studio workspaces are included. This goes beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences. The first sentence front-loads the primary purpose, and the second adds a critical caveat in a clearly labeled note. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is fully adequate. It explains what the tool returns (Studio workspaces), its limitations (empty for personal accounts), and reassures that projects remain functional. This is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to explain. The baseline for 0 parameters is 4, and the description does not need to add parameter-specific details. It appropriately avoids discussing parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing HacknPlan workspaces visible to the API key. The verb 'list' and resource 'workspaces' are specific, and the caveat about Studio-only results distinguishes it from other listing tools like list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when this tool is appropriate: it lists only Studio workspaces, while personal accounts return an empty list. It also notes that projects still work independently, which helps the agent decide when to rely on this tool. However, it does not explicitly name an alternative for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mtuska/hacknplan-mcp'

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