Plane MCP Server

Server Quality Checklist

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

Latest release: v0.2.11
Disambiguation5/5
Each tool targets a distinct resource and action; even the many list_* variants (cycle/module/milestone/release/customer work items) are clearly differentiated by name and description. The handful of manage_* tools are each scoped to a unique association type, so there is no meaningful overlap.
Naming Consistency4/5
The vast majority follow a consistent verb_noun pattern (list_, create_, retrieve_, update_, delete_). Minor deviations exist: get_ is used for some reads (get_me, get_features, get_project_members) while retrieve_ is used for resource fetches, and read_work_item_attachment breaks the pattern, but the conventions are still predictable and readable.
Tool Count1/5
177 tools is an extreme mismatch for an MCP server surface; even large API client servers rarely warrant this many. Agents will struggle to select from such a huge menu, and the count far exceeds the recommended upper bound.
Completeness4/5
CRUD/lifecycle coverage is nearly complete for all major resources (projects, work items, cycles, modules, initiatives, labels, states, milestones, releases, customers, properties, types), including specialized sub-resources like comments, attachments, relations, and work logs. The only notable gaps are missing update/delete for pages and a few workspace-level operations.
Average 4/5 across 177 of 177 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 28 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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.
This repository includes a glama.json configuration file.
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

Behavior2/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 simply says 'create' and mentions a return value, but does not explain side effects, permissions, idempotency, or what happens on errors. This is insufficient for a mutation tool without 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is short, it includes a non-existent parameter ('workspace_slug'), which does not earn its place and undermines the structure. The argument list is misleading, and the return statement is the only useful addition. The description would benefit from removing the erroneous line and adding concrete parameter details.
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 a nested 'data' object with no schema definition and no explanation in the description, leaving the agent without critical information. No annotations, no parameter details, and no usage context make the description insufficient for a create operation with an opaque payload. The extra 'workspace_slug' further confuses the intended input.
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 description introduces a 'workspace_slug' parameter that does not exist in the input schema, which is misleading and will cause validation errors. It also describes 'data' only as 'a dictionary' without elaborating required fields or structure, failing to compensate for the schema's complete lack of property 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 states a specific action (create) on a specific resource (intake work item) within a project. It distinguishes itself from the sibling 'create_work_item' via the 'intake' qualifier in the name and description, though it doesn't explicitly contrast with that alternative.
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_work_item' or 'update_intake_work_item'. It lacks any context about prerequisites, scenarios, or exclusions, relying solely on the name to imply 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 present, so the description must disclose behavioral effects. It only states that a cycle is deleted by ID, but does not mention permanence, cascading removal of associated items, required permissions, or whether deletion is recoverable. This is too little for a destructive operation.
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 compact and uses a structured Args block, but it is excessively skeletal and the Args block includes an extra parameter (`workspace_slug`) not present in the schema, which undermines its structural accuracy. A longer, more informative description would be more appropriate given the destructive nature of the operation.
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?
With only two parameters, no annotations, and no output schema, the description still misses critical context: it does not state whether deletion is permanent, what happens to associated work items, how the workspace is identified, or what response to expect. The mismatch between the listed args and schema compounds the incompleteness.
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 descriptive coverage for its two properties, and the description merely restates the parameter names with generic type labels ('UUID of the project', 'UUID of the cycle'). It also introduces a `workspace_slug` parameter that is absent from the schema, creating confusion about required inputs.
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 operation ('Delete') and the resource ('a cycle') with an explicit ID-based identification. This distinguishes it from cycle-related tools like update_cycle, complete_cycle, and manage_cycle_archive, which represent different operations.
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 choose this tool over alternatives such as manage_cycle_archive (which might be a softer removal) or complete_cycle. There is no mention of prerequisites, side effects, or conditions under which deletion should be used.
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 behavioral disclosure. It only says 'transfer' without explaining whether work items are moved (removed from source) or copied, whether the operation is reversible, if any permissions are required, or what the return value indicates. This is a significant gap for a mutation operation.
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 concise: one purpose sentence plus a parameter list. It gets to the point quickly. The parameter list is a bit redundant with the schema, and the typo 'issues' slightly detracts, but overall it is well-sized and 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?
Without annotations or an output schema, this description is insufficient for a mutation tool. It doesn't explain the operation's side effects (e.g., source cycle state), whether it's destructive, how the result is returned, or error scenarios. The parameter mismatch further undermines completeness.
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 list each parameter with a brief explanation, but it includes 'workspace_slug', which is not present in the input schema. This discrepancy can mislead an agent into passing an invalid parameter. The explanations for the schema-defined parameters are minimal and don't clarify formats beyond what the schema gives.
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 tool's purpose: 'Transfer work items from one cycle to another.' This is a specific verb+resource. However, it uses 'issues' in the new_cycle_id description, introducing minor terminology inconsistency. It also doesn't explicitly distinguish from the sibling tool manage_cycle_work_items, though the meaning is clear enough.
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 manage_cycle_work_items for adding/removing work items from a cycle. It does not state any conditions, prerequisites, or exclusions. The only implied usage is 'transfer between cycles', which is minimal.
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 must carry the burden of behavioral disclosure. It mentions the return type but does not state that the operation is read-only, safe, or side-effect-free. It also introduces 'workspace_slug' which is not in the schema, adding confusion rather than clarifying behavior.
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 relatively short with Args and Returns sections, but it contains an extraneous parameter not in the schema. This redundant and incorrect information detracts from the structure, though the overall length is acceptable.
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, and an output schema exists, so return details are not essential. However, the description's inclusion of a non-existent parameter and lack of guidance on when to use this versus list_work_logs makes it incomplete and potentially misleading for an agent deciding how to invoke it.
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 add meaning for 'project_id' as 'UUID of the project', which is helpful. However, it also lists 'workspace_slug' as an argument despite the schema having only 'project_id', misleading the agent about required inputs and potentially causing parameter passing errors.
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 'Get work log summary for a project', which identifies the action and resource. However, it lists 'workspace_slug' as an argument even though the input schema only accepts 'project_id', creating slight ambiguity about the actual invocation 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?
The description implies usage for obtaining a summary of work logs for a project, but it does not explicitly contrast with sibling tools like list_work_logs or state when a summary is preferred over detailed logs. No when-not or alternative guidance is provided.
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 implications of the action. It only states 'Create a new module' and 'Returns Created Module object,' with no mention of side effects, permissions, idempotency, or handling of duplicates. This leaves important behavioral aspects unclear.
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 organized as a docstring with Args and Returns sections, making it easy to scan. It is reasonably concise given the number of parameters, though the parameter list is redundant with the schema and could be shortened.
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 10 parameters and no annotations, the description should provide more context about what a module is, its purpose, and any relationships to other entities. It does not explain required fields beyond the schema, nor does it clarify the discrepancy with workspace_slug. The description falls short of fully equipping the agent.
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 add textual meanings to parameters, which is helpful given the schema has no descriptions. However, it lists 'workspace_slug' as an argument, which is not present in the input schema and would be rejected by additionalProperties:false. Some descriptions are also tautological (e.g., 'Module name' for name). These errors undermine the semantic value provided.
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?
'Create a new module.' is a clear, specific verb+resource statement that immediately distinguishes this from other creation tools (e.g., create_project). The parameter list is secondary and does not obscure the primary 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?
The description provides no guidance on when to use this tool versus other create tools (e.g., create_project, create_cycle). It does not mention any prerequisites, such as needing a valid project_id, or when an update might be more appropriate. This is missing context for tool selection.
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 says 'delete' but gives no indication of permanence, cascading effects, required permissions, or any post-condition. The presence of workspace_slug in the arg list but not in the schema also adds confusion rather than transparency.
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 compact and front-loaded with the core statement. However, the inclusion of a non-existent parameter (workspace_slug) is a structural flaw that wastes the reader's attention. It is concise but not clean.
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 2-param delete operation without annotations or output schema, the description offers minimal context. It omits any mention of return values, error conditions, or side effects. The parameter mismatch further reduces completeness, making it insufficient for an agent to invoke with full confidence.
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 'UUID' type info for project_id and module_id, which is somewhat useful beyond the bare schema. However, it also lists workspace_slug, which does not appear in the input schema, creating a misleading parameter. With 0% schema coverage and this inconsistency, the description only partially compensates.
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 begins with 'Delete a module by ID', a specific verb-resource pair that exactly matches the tool's name and clearly distinguishes it from other delete tools targeting different resources. The scope is unambiguous despite the later arg list introducing an extra parameter.
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 gives no context, prerequisites, or exclusions. The description only states what it does, not when to choose it over other module operations like update_module or manage_module_archive.
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?
Annotations are absent, so the description carries the full burden of behavioral disclosure. It only states the basic operation and return type, without mentioning pagination, sorting, filtering behavior, or potential performance implications. This is a significant gap for a list operation.
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 concise and well-structured with Args and Returns sections. Each sentence contributes useful information, but it could be slightly more polished by avoiding redundancy with the schema (e.g., repeating parameter names). Overall, it is efficient.
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 an output schema, the description covers the essential purpose and Parameters. However, it omits usage guidelines and behavioral details (e.g., whether params support pagination or sorting). Given the presence of an output schema, return values are less critical, but the lack of guidance on when to use this tool and its limitations makes it only minimally 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 description coverage is 0%, so the description must compensate. It does add meaning by specifying 'project_id: UUID of the project' and 'params: Optional query parameters as a dictionary', which provides type and optionality information beyond the bare schema. However, it does not explain what query parameters are supported or how they affect results, leaving room for improvement.
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 tool's function: 'List all milestones in a project.' It uses a specific verb and resource with a project scope. However, it does not differentiate from sibling list tools such as list_milestone_work_items or list_cycles, so it does not fully meet the 5-level criterion for distinguishing from siblings.
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 like retrieve_milestone or list_milestone_work_items. The description only lists parameters and return types, with no mention of use cases, prerequisites, or 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?
No annotations are provided, and the description only gives the verb 'List' with no disclosure of pagination, ordering, filtering, permissions, or rate limits. The Returns line about WorkItemLink objects is minimal and does not compensate for the lack of behavioral detail.
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 appropriately sized, with a clear purpose statement followed by structured Args and Returns sections. Every sentence is necessary and there is no wasted text.
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?
Although an output schema exists, the description leaves the `params` parameter as an unexplained black box. Without annotations, the tool's behavioral profile is thin, and the description does not address potential filtering, pagination, or relationship to other link/relation tools, making it incomplete for an agent to confidently invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides one-line definitions for each parameter ('UUID of the project', 'UUID of the work item', 'Optional query parameters as a dictionary'), which adds basic meaning. However, the `params` parameter is vague and does not specify allowed filters or options, leaving a clear 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 'List links for a work item' with a specific verb and resource. However, it does not distinguish itself from the closely named sibling tool `list_work_item_relations`, which may be a similar operation, so it lacks explicit 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?
There is no guidance on when to use this tool versus alternatives like `list_work_item_relations` or `retrieve_work_item_link`. No context, prerequisites, or exclusions are provided, leaving the agent to infer usage from the 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?
With no annotations, the description carries the full burden of behavioral disclosure. 'Delete' implies destructive intent, but the description does not mention permanence, cascading effects (e.g., on estimate points), permission requirements, or any other side effects. It adds minimal behavioral context beyond the verb itself.
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 appropriately terse for a simple one-parameter tool: a single clear sentence plus an args list. No filler or redundant information, though the args section could be formatted more cleanly.
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 description covers the basic action and parameter but omits critical context for a delete operation: irreversibility, effects on associated data, potential errors, and what the response looks like. Given the lack of annotations and output schema, the description is incomplete for safe and confident 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 description identifies the single parameter and specifies it as a 'UUID of the project', which adds meaningful semantic value beyond the schema's bare 'string' type. However, it does not explain how to obtain the project_id or any constraints beyond the UUID format, leaving room for more detail.
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 ('Delete') and resource ('estimate for a project'), clearly distinguishing it from sibling tools like delete_project_estimate_point or delete_project. The purpose is immediately clear 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, such as delete_project_estimate_point for deleting individual estimate points. No context or exclusion criteria is provided, leaving the agent to infer appropriate 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 carries full burden. It only says 'Retrieve a project by ID' and 'Returns: Project object', which is minimal. More critically, it lists 'workspace_slug' as an argument that is not in the input schema, misleading the agent about required inputs. It does not disclose any edge-case behavior (e.g., not-found handling, access requirements).
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 short and uses a simple Args/Returns structure, which is efficient. However, every sentence should earn its place; the workspace_slug argument is inaccurate and unnecessary, so the description is not as clean as it could be.
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?
Although an output schema exists (so return format is covered), the description is incomplete due to the workspace_slug inconsistency. It also provides no context about when to use this vs. sibling retrieval tools, and the contradictory argument list creates a gap that makes the tool harder to invoke 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 coverage is 0%, so the description must compensate. It does clarify that project_id is a UUID, which is helpful, but it also introduces workspace_slug as an argument despite it not being in the schema. This actively misleads the agent and detracts from the otherwise minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a project by ID, distinguishing it from list_projects and other project-related operations. The verb 'retrieve' and resource 'project' are specific, and the 'by ID' qualifier makes 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: you use this when you have a project ID and need the full project object. However, there is no explicit guidance on when to prefer this over list_projects or other retrieval tools, nor 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 must fully disclose behavior. It states that it creates a cycle and returns the created object, but does not mention side effects, authorization requirements, or validation behavior. It fails to provide sufficient context beyond the obvious creation action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening statement, an Args list, and a Returns section. It is concise and front-loaded. The inclusion of an undocumented 'workspace_slug' parameter slightly detracts from accuracy, but the overall organization is clear.
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 has 9 parameters, 3 required, and an output schema, so the description doesn't need to detail return values. It covers all schema parameters (plus one extra) and states the return type. However, it lacks usage context, prerequisites, and contains a parameter/schema discrepancy, making it only moderately complete for a create 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?
The description provides human-readable explanations for all parameters listed in the schema, which is helpful given 0% schema_description_coverage. However, it introduces 'workspace_slug' which is not present in the input schema, creating a mismatch. The descriptions are basic definitions and do not clarify required vs optional or formats beyond what the schema already implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states "Create a new cycle," which is a specific verb-resource pair. It distinguishes this tool from siblings like update_cycle, delete_cycle, and list_cycles.
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?
There is no guidance on when to use this tool versus alternatives, no prerequisites mentioned (e.g., project existence, permissions), and no exclusions. The usage is only implied by the tool's 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, the description carries the full burden. It provides one useful behavioral nuance (use the issue field, not the intake work item ID) but does not disclose whether deletion is permanent, side effects, permission requirements, or error behavior. Additionally, it mentions workspace_slug as an argument, which is not present in the schema, creating inconsistency and reducing trust.
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 concise with a single action sentence followed by an args list. It is front-loaded with the purpose. The inclusion of workspace_slug is an error, but structurally it is efficient and not verbose.
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 description explains a key ID nuance but omits essential context for a delete operation: no mention of permanence, return value, error conditions, or the relationship between intake work items and work items. The workspace_slug mismatch further detracts from completeness. No output schema is provided, so the description should have covered more.
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 adds crucial meaning for work_item_id (use the issue field) and identifies project_id as a UUID, but it also lists workspace_slug which is not in the schema. This phantom parameter undermines the clarity and reliability of the parameter documentation.
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 an intake work item by work item ID' with a specific verb and resource. This distinguishes it from siblings like delete_work_item and delete_work_item_attachment. The additional note about using the issue field clarifies the target without obscuring the overall 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 the tool is used for deleting intake work items, which is enough to differentiate from other delete tools. However, it does not explicitly state when to use this versus alternatives like delete_work_item or provide exclusions or prerequisites. The parameter guidance about the issue field is a form of usage context but does not address tool selection.
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?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It does not disclose any side effects, such as whether deletion is permanent, cascades to associated data, or requires specific permissions. It only states the basic delete action.
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 very concise and front-loaded: 'Delete a project by ID.' followed by a short argument list. No wasted words. The only minor issue is the inclusion of workspace_slug, but overall it is 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?
For a delete operation with no annotations and no output schema, the description is incomplete. It does not mention whether the deletion is irreversible, what happens to related data, or any prerequisites. The extra workspace_slug argument also raises ambiguity about the actual interface.
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 some meaning by explaining that project_id is a UUID, which is not evident from the schema (which only says 'string'). However, it also introduces a workspace_slug argument that is not present in the input schema, causing confusion and detracting from the value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action and target: 'Delete a project by ID.' This uses a specific verb and resource, and it distinguishes the tool from sibling tools like create_project, update_project, and retrieve_project.
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. There is no mention of prerequisites, consequences, or exclusions (e.g., 'only delete projects without work items'). The description simply states the action and lists arguments.
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 states that the tool lists comments and returns a list of WorkItemComment objects, which implies a read-only operation. However, it does not disclose behaviors such as pagination, ordering, filtering via params, permissions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is formatted as a concise docstring with Args and Returns sections. Every line serves a purpose, and there is no extraneous content. The structure is clear and easy to scan, though the Args section partially duplicates schema names, but the schema lacks descriptions so it adds value.
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 operation with an output schema indicated, the description gives enough to get started: the return type and required parameters. However, it omits details about pagination, available query parameters, and usage context among the many sibling tools. The lack of annotations also leaves the operational behavior under-specified.
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 for its three parameters. The description contains an Args section that explains each parameter: project_id as UUID, work_item_id as UUID, and params as an optional dictionary. This adds some meaning beyond the schema, but the semantics of the params dictionary remain vague, not specifying allowed keys or how to structure them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List comments for a work item' with a specific verb and resource. It is distinct from sibling tools like retrieve_work_item_comment, as it implies a list operation. The included Args and Returns sections further clarify the function.
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 retrieve_work_item_comment or create_work_item_comment. It does not mention any exclusions, prerequisites, or conditions under which this tool is preferred.
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 full burden. It only states the return type and does not disclose whether the operation is read-only, any error behavior (e.g., not found), auth requirements, or side effects. The verb 'retrieve' implies a read, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with an Args/Returns layout, which is easy to scan and each line is concise. It focuses on parameters and return type, without unnecessary filler. Minor redundancy in 'Retrieve a work item by ID' followed by args could be tightened but is not wasteful.
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 output schema covers return values, but the description lacks key contextual information: when to use this tool vs siblings, how error cases are handled, and the purpose of order_by for a single item. Given the large sibling set and no annotations, this is incomplete for guiding proper selection and 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 provides brief explanations for all 7 parameters, but some are vague (e.g., 'order_by' for a single-item retrieve, and external_id/external_source are only described as filtering). The descriptions add basic meaning but not enough to fully understand all parameter semantics.
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 states a specific verb and resource ('Retrieve a work item by ID') and lists exact parameter roles. It is clear, but it does not explicitly distinguish itself from the sibling tool 'retrieve_work_item_by_identifier', even though the parameter names imply an internal UUID-based retrieval.
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 context is only implied: the tool retrieves a single work item given project_id and work_item_id. No explicit guidance is given about when to use this instead of list/search alternatives or retrieve_work_item_by_identifier. The parameter list provides some context but no when/when-not statements.
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 disclosing behavior. It only states 'Update' and 'Returns Updated Estimate object,' with no mention of partial-update semantics, permissions, or side effects. This is insufficient for a mutation tool with zero annotation coverage.
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 concise and well-structured with Args and Returns sections. Each line is informative, though the parameter descriptions are minimal and could be merged with schema details without losing clarity.
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 output schema exists, so return format is covered without description explanation. However, the description omits critical behavioral context like whether updates are partial or merge-based, error conditions, and when to prefer this tool over related estimate tools. Given 5 parameters and no annotations, it is 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 lists each parameter with brief semantic labels, clarifying that project_id is a UUID and external_id/external_source relate to external systems. However, these mostly restate the schema property names and do not explain that null values may leave fields unchanged. With 0% schema description coverage, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update the estimate for a project' with a specific verb and resource. This distinguishes it from sibling tools like create_project_estimate and delete_project_estimate, as well as update_project.
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 when-to-use guidance is provided. The description does not mention alternatives such as create_project_estimate or get_project_estimate, nor does it explain when updating an estimate is appropriate versus other project operations.
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?
Annotations are absent, so the description carries the full burden. It says 'Update a comment' but does not disclose whether it does a partial or full update, what happens if the comment does not exist, whether permissions are required, or the relationship between comment_html and comment_json. These are significant behavioral 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 well-structured with a clear action statement, a list of parameters, and a return value. It is concise and front-loaded, though the Args list largely mirrors the schema and could be trimmed without losing 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?
The description covers purpose, parameters, and return type, which is adequate but incomplete. It lacks usage guidance and behavioral details. Given the 8 parameters and absence of annotations, more contextual information is needed 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides a one-line explanation for each parameter, which helps compensate for the 0% schema description coverage. However, the explanations are shallow (e.g., 'external_source: External system source name') and do not clarify optionality, mutual exclusivity, or valid formats beyond the schema types.
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 and resource: 'Update a comment for a work item.' This is specific and distinguishes it from sibling tools like create_work_item_comment, delete_work_item_comment, and retrieve_work_item_comment.
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 is given on when to use this tool versus alternatives. It does not mention exclusions, such as using create_work_item_comment for new comments or delete_work_item_comment for removal. Usage is only implied by the tool name and description.
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 must disclose behavior on its own. It states the return type (Created WorkItemLink object) but does not mention side effects, permission requirements, idempotency, or that this specifically creates a URL link. This is insufficient 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 highly concise, front-loaded with the action, and uses a clean Args/Returns structure. Every sentence serves a purpose with no filler.
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 create operation with three parameters and an output object, the description covers the essentials. However, it could be more complete by explicitly noting that this creates a URL link (not a relationship) and clarifying any constraints or side effects. It is adequate but not comprehensive.
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?
Although schema_description_coverage is reported as 0%, the description adds semantic type hints (UUID for IDs, URL for url) that are missing from the schema's generic 'string' type. It does not go beyond the parameter names, but the added types provide some value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a link') and target ('for a work item'), with a specific resource type. It distinguishes from siblings like create_work_item_relation by focusing on URL links via the url parameter.
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 given on when to use this tool versus alternatives such as create_work_item_relation. There is no mention of prerequisites, exclusions, or typical use cases.
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 must carry the burden of behavioral disclosure. While 'delete' implies destructive action, it does not mention irreversibility, side effects, permissions, or error behavior. 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 concise, front-loaded with the primary action, and uses a clear structured Args block. No unnecessary 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 delete with two parameters, the description covers the action and inputs adequately. However, it omits behavioral details like permanence, dependent data handling, or response behavior, and lacks usage context. It is a minimum viable description but not comprehensive.
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 provides the only parameter meaning. It clarifies that project_id is the UUID of the project and milestone_id is the UUID of the milestone, but does not explain the relationship between them or why both are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a milestone by ID', which is a specific verb+resource. It distinguishes itself from sibling tools like create_milestone, update_milestone, retrieve_milestone, and list_milestones.
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 guidance on when to use this tool vs alternatives, no prerequisites, and no exclusions or warnings. It simply states the action and arguments.
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, but it only says 'Delete a state by ID' without mentioning irreversibility, cascading effects, permissions, or error conditions. It does not add meaningful behavioral 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 concise and front-loaded, stating the purpose in the first sentence. The Args block is short and adds the UUID type information, with no unnecessary 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-parameter delete operation, the description provides the essential behavior and parameters. However, the absence of any behavioral context (e.g., consequences of deletion) and no annotations or output schema leaves it only minimally 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 no descriptions (0% coverage), so the description's Args block adds some value by specifying that both parameters are UUIDs and indicating their roles. However, this is largely redundant with the parameter names and does not explain relationships or constraints.
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 a state') and the method ('by ID'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like create_state, retrieve_state, and update_state.
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 when a state can be safely deleted or if any prerequisites exist. The usage is only implied by the verb 'Delete'.
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 behavioral disclosure. It discloses the return structure (dependencies grouped by six directions, custom by label) and implies a read-only list operation, but it does not mention permissions, error cases, or whether all relations are returned without pagination. This is moderate disclosure given the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: a one-sentence purpose followed by Args and Returns sections. Every piece of information (parameter types and return groups) is useful, with no redundant filler.
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 list operation with an output schema, the description provides adequate context: it names the parameters, their role, and the return structure. However, it omits details like what the six directions are, what a 'definition label' refers to, and whether pagination or filtering is supported. This is sufficient for basic usage but leaves some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It identifies both parameters as UUIDs with brief purpose ('of the project', 'of the work item'), adding meaning beyond the schema's bare string type. However, it does not provide deeper detail such as value formats or examples, so it only partially compensates for the 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 the tool lists every relation for a work item, using a specific verb and resource. It distinguishes from sibling tools like list_work_item_links and list_work_item_relation_definitions by focusing on 'relations' and grouping them into dependencies and custom, though it doesn't explicitly name those alternatives.
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. The description explains what it does but does not mention when to choose it over list_work_item_links or list_work_item_relation_definitions, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 that the tool returns a list of WorkItemWorkLog objects; it does not mention whether the operation is read-only, whether authentication is required, if pagination applies, or any error conditions. This is insufficient for a tool with zero 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 concise and well-structured with clear Args and Returns sections. Every sentence earns its place, and there is no redundant or irrelevant content. It is appropriately sized for a simple list tool.
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 operation, the description covers the basics: what it lists, required parameters, and return type. However, it lacks details on filtering via params, potential empty results, or authorization needs. Given the output schema exists and the tool is straightforward, this is adequate but not 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 zero description coverage, so the description is the only source of parameter meaning. It correctly identifies project_id and work_item_id as UUIDs and notes that params is an optional dictionary. However, it does not enumerate what query parameters are accepted or provide any examples, leaving the semantics of 'params' vague.
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: 'List work logs for a work item.' This specifies the verb (list), resource (work logs), and scope (for a work item), distinguishing it from siblings like get_project_worklog_summary or create_work_log. The name and description align perfectly.
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_worklog_summary or list_work_items. There are no exclusions, prerequisites beyond the required IDs, or hints about when this is the appropriate choice. The description only implies usage by naming the required parameters.
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. It does disclose a key nuance (use the issue field, not the intake work item ID), but it fails to state whether the operation is read-only, requires special permissions, or what happens on failure. More seriously, it lists workspace_slug as an argument while the schema does not include it, misleading the agent about the tool's actual interface.
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 concise and well-structured with an Args and Returns format. The main purpose is front-loaded. However, the inclusion of workspace_slug is both erroneous and an unnecessary line, slightly reducing efficiency.
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 description is fairly complete for a simple retrieval: it names the return type (IntakeWorkItem) and the critical ID nuance. However, it lacks context on when to use this tool versus related work item retrieval tools and does not address the workspace_slug discrepancy, leaving a noticeable gap for an agent deciding how to invoke it.
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 meaning beyond the bare schema for project_id, work_item_id, and params (e.g., 'use the issue field...', 'expand, fields'). However, it also introduces workspace_slug, which is not a valid parameter in the schema, thereby providing misleading information. Schema coverage is 0%, so the description must compensate, but the error undermines its usefulness.
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: 'Retrieve an intake work item by work item ID.' The 'intake' qualifier distinguishes it from sibling retrieval tools like retrieve_work_item and retrieve_work_item_by_identifier. The return type is explicitly mentioned.
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 use for intake work items and provides guidance on which ID field to supply (the issue field from IntakeWorkItem response). However, it does not explicitly state when to choose this tool over alternatives like retrieve_work_item or list_intake_work_items, nor does it provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 does not mention permissions, partial vs full update semantics, error handling, or whether omitted fields are reset to null. The agent has no warnings about side effects or prerequisites.
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 front-loaded with the main action and then lists parameters in a structured format. It is reasonably concise for 9 parameters, though a few entries (e.g., 'name: Label name') could be trimmed without losing meaning.
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 9 parameters and no annotations, the description lacks critical behavioral context such as whether the update is partial or full, validation rules, and failure modes. The Returns line adds little since an output schema exists. This leaves significant gaps for an agent to safely invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by listing all 9 parameters with brief explanations, including helpful context like 'parent: UUID of the parent label (for nested labels)' and 'color: hex color code'. Although some entries are tautological, it provides clear meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a label by ID' with a specific verb (Update), resource (label), and identifier (ID). This distinguishes it from sibling tools like create_label, retrieve_label, and delete_label.
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. The description simply states the function without context or exclusions, leaving the agent to infer usage without explicit direction.
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 merely says 'Update a module by ID' and 'Returns Updated Module object,' without explaining update semantics, null-field behavior, permissions, or reversibility. For a mutation tool, this is a significant gap.
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 one-sentence purpose is front-loaded, and the parameter list is organized and readable. The return value is also stated. The only waste is the invalid workspace_slug entry and the omission of any usage guidance, but overall the structure is efficient.
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?
With 11 parameters and no annotations, the description must do more than list parameters. It omits usage context, partial-update behavior, and how null values are handled, which are critical for an update operation. The invalid workspace_slug also makes the description less reliable, despite the output schema being available.
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 useful semantics for many schema properties, such as ISO 8601 for dates, UUID expectations, and allowed status values. However, it incorrectly lists workspace_slug as an argument even though the input schema does not include it and has additionalProperties: false, which could mislead an agent into passing an invalid 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 opens with a clear, specific verb-plus-resource statement: 'Update a module by ID.' This distinguishes it from siblings like create_module, retrieve_module, and delete_module, which are obvious alternatives in the tool list.
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 siblings, nor any mention of when not to use it. The name and opening line imply it is for modifying an existing module, but no alternatives or exclusions are stated.
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 only lists parameters and says 'Updated State object' is returned. It fails to explain critical update semantics such as whether this is a partial update (only provided fields changed) or a full replacement, permission requirements, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary followed by a clean Args list. Each parameter gets a short, relevant description without unnecessary fluff. It is appropriately sized for the number of parameters.
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?
Even though an output schema exists, the description lacks essential context for an update tool. It does not state whether updating is partial in nature, whether certain fields are mutually exclusive, or how errors are handled. The parameter list is helpful, but the behavioral context remains incomplete.
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 description compensates for the schema's 0% description coverage by providing a brief explanation for each of the 11 parameters. It clarifies that color is a hex code, gives examples for group, and explains external_source and external_id. This adds meaningful context beyond the raw schema types.
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 ('Update a state by ID') and identifies the resource (a state) with required identifiers. It distinguishes itself from sibling tools like create_state, delete_state, and retrieve_state by focusing on the update 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?
No explicit guidance is given about when to use this tool versus alternatives. It does not mention that this is for modifying an existing state, nor does it contrast with create_state or other related tools. The only implied usage is derived from the name and the required IDs.
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 full behavioral disclosure burden. It mentions that an Updated WorkItemLink object is returned, but omits side effects, error conditions, auth requirements, and the nuance that url is nullable (per schema). Mutation is implied by 'update' but not elaborated.
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 compact and cleanly structured with Args and Returns sections. Every sentence adds value, and there is no redundant or extraneous text.
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 CRUD update, the description covers all parameters and specifies the return type, referencing an output schema. It lacks usage context and edge-case behavior, but the tool's simplicity makes this acceptable.
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 compensates by listing all four parameters with concise meanings (e.g., 'UUID of the project', 'Updated URL of the link'). However, it doesn't explain that url is optional/nullable or what happens when omitted.
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 ('Update a link') and the resource ('for a work item'), making it distinct from sibling create/delete/retrieve operations. The verb 'update' and resource 'link' are specific, though it doesn't explicitly differentiate from alternatives.
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 create_work_item_link or delete_work_item_link. The description lacks context about prerequisites, scenarios, or exclusions, leaving usage entirely implicit from the 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 the entire burden of behavioral disclosure. It only states the action and return type, but does not mention side effects (e.g., whether an existing link is replaced, whether the operation is idempotent), potential errors, or permission requirements. This is a significant gap for a mutation-like 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 brief and well-structured with an Args/Returns format. The main action sentence is front-loaded. However, it is slightly redundant with the schema (repeating parameter names), but it remains efficient and 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 link operation with three parameters and an output schema, the description covers the core information. However, it lacks important context such as idempotency, duplicate-link behavior, or required preconditions. Given the lack of annotations and the presence of sibling tools that manage links, a bit more detail would make it 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 only defines parameter names and types (string), with no descriptions. The description adds meaning by explaining each parameter's role and specifying they are UUIDs (e.g., 'UUID of the project', 'UUID of the work item', 'UUID of the page to link'). This directly compensates for the 0% schema description 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: 'Link a page to a work item.' It names the specific verb (link/attach) and the resources involved (page, work item), and the distinction from sibling tools like 'detach_page_from_work_item' is evident. The mention of return object ('WorkItemPage link object') further clarifies its 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 that this is the counterpart to 'detach_page_from_work_item', nor does it explain any prerequisites (e.g., existence of the page and work item, user permissions). The description simply states what it does without contextual usage direction.
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 only says 'Delete a label by ID' without mentioning the irreversible nature, potential cascade effects on associated work items, permission requirements, or any side effects. This is insufficient for a destructive 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 extremely concise, with a single action sentence and a clear parameter list. Every word serves a purpose with no unnecessary detail.
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?
This is a mutation tool with no annotations and no output schema. The description provides no information about return behavior, errors, idempotency, or consequences of deletion. For a destructive operation, this is incomplete.
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?
Although the schema has 0% description coverage, the description explicitly explains both parameters: project_id as 'UUID of the project' and label_id as 'UUID of the label'. This adds meaningful context beyond the raw schema, clarifying the role of each 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 label by ID' with the specific resource (label) and action (delete). It distinguishes itself from sibling tools like create_label, update_label, retrieve_label, and list_labels by indicating the destructive 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 simply states what the tool does but provides no guidance on when to use it versus alternatives, no prerequisites, and no exclusions. For example, it doesn't mention whether the label must exist or if deleting a label has implications for work items using it.
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 disclosing behavioral traits. It states the action is 'Delete' but gives no information about permanence, cascading effects on related entities (e.g., attachments, comments), required permissions, or whether the operation is reversible. This is a destructive operation, and the description is too sparse to prepare an agent for its consequences.
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: one sentence stating the operation followed by a clear arg list. It is front-loaded with the action and contains no filler or repeated information. Every word earns its place.
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?
This is a simple delete operation, but with no output schema and no annotations, the description should at least indicate what the tool returns (e.g., success confirmation, deleted object, or empty response). It also lacks information about error conditions (e.g., non-existent work_item_id). The 2-parameter schema is straightforward, but the description is insufficient for an agent to fully predict the tool's behavior and output.
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 merely lists project_id and work_item_id as strings with no descriptions. The description adds that they are UUIDs and specifies which ID refers to the project and which to the work item. This is valuable semantic information beyond the schema, though it doesn't elaborate on optionality (which is already defined by the schema's required list).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a work item') and identifies the resource being acted on. The 'by ID' qualifier adds necessary scoping, and the parameter list clarifies that both project and work item IDs are needed. This effectively distinguishes it from sibling delete tools (e.g., delete_work_item_attachment, delete_work_item_comment) that target different sub-resources.
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. While it's implied that you would use this to delete a work item, there is no mention of when not to use it (e.g., for deleting attachments or comments, use a different tool). The presence of many sibling delete tools makes this lack of differentiation a clear gap.
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, but it only restates the obvious 'Delete' action. It omits irreversibility, permission requirements, side effects on related data, and error behavior, which is a significant gap for a destructive operation.
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 compact and front-loaded: a one-line purpose statement followed by a clean Args block. Every line earns its place, with no redundant prose, though the brevity leaves behavioral details unaddressed.
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 three-parameter delete tool, the description covers the essential operation and parameter meanings. However, it lacks any behavioral context such as side effects, success/error responses, permission needs, and it never distinguishes links from the closely related 'relations' concept, making it only minimally viable.
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 Args block adds meaningful value by explaining each parameter's semantic role (UUID of project, work item, and link). This compensates for the bare string-only schema, though it stays minimal and does not add constraints or relationships beyond the basics.
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 'Delete a link for a work item' specifies a clear verb (Delete) and resource (link for a work item), making the operation unambiguous. It distinguishes this tool from siblings such as create_work_item_link, update_work_item_link, and remove_work_item_relation by naming the link as the target.
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 given on when to use this tool versus alternatives like remove_work_item_relation or delete_work_item_attachment. There are no prerequisites, exclusions, or contextual hints beyond what the tool name already implies.
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 discloses that the tool creates a comment and returns the created object, but it doesn't mention any permissions required, side effects, or constraints (e.g., whether comment_html or comment_json must be provided). For a mutation tool, this is a minimal level of 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 clean docstring with a one-sentence summary followed by an Args list and a Returns line. It is well-structured, front-loaded, and every line provides necessary information without fluff. It earns its place efficiently.
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 (7 parameters, 2 required), the description covers the basics but omits important context. Notably, it doesn't explain whether at least one of comment_html or comment_json is required, or if they are mutually exclusive. There is an output schema, so the Returns line is somewhat redundant, but the description still leaves key usage constraints unclear.
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 compensates by providing brief but meaningful descriptions for all 7 parameters. It clarifies that project_id and work_item_id are UUIDs, comment_html is HTML, comment_json is JSON, access can be INTERNAL or EXTERNAL, and external_source/external_id are external identifiers. This adds value beyond the bare type information in the schema, though some descriptions (e.g., external_source) are somewhat tautological.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a comment for a work item.' This clearly states the action (create) and the resource (comment for a work item), which distinguishes it from sibling tools like update_work_item_comment, delete_work_item_comment, and list_work_item_comments. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. It doesn't mention that it should be used for creating new comments as opposed to updating or retrieving existing ones, nor does it note any prerequisites. The usage is only implied by the tool's name and the generic 'create' action.
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 states that a work log is created and returns a WorkItemWorkLog object, but does not mention permissions, side effects, idempotency, or failure scenarios. This is minimal transparency 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 concise and well-structured, with a one-sentence purpose followed by a compact, clearly labeled Args and Returns section. Every line adds value, and there is no unnecessary 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?
The tool is relatively simple, and the description covers the action, all parameters, and the return type. However, it omits usage context, behavioral details, and any error or permission considerations. Given the presence of an output schema, the return is covered, but the lack of annotations and guidance leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'Args' section adds meaningful context beyond the schema by explaining each parameter's purpose—e.g., 'UUID of the project', 'Duration of work in minutes', and 'Description of the work performed'. This helps the agent correctly populate the parameters, even though the schema provides types and defaults.
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 work log for a work item' with a specific verb and resource. It is distinct from sibling tools like create_work_item, list_work_logs, update_work_log, and delete_work_log, 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 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, nor does it mention any prerequisites or exclusions. It only describes the action itself, leaving the agent to infer usage from the verb.
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 'Delete a comment' without explaining whether the delete is permanent, whether it cascades, what permissions are needed, or what happens if the comment does not exist. For a destructive operation, this lack of detail is a significant gap.
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: one sentence for the action plus a simple Args list. The verb is front-loaded, and there is no wasted wording. Every element contributes to understanding the tool's purpose and parameters.
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 (3 required string params, no output schema, no annotations), so the description covers the core usage. However, it omits any mention of return values, error behavior, or side effects (e.g., permanence). Given that no output schema exists, the description could have briefly noted what the agent should expect as a response, making it only minimally 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 input schema has no descriptions (0% coverage), so the description partially compensates by labeling each parameter as 'UUID of the project/work item/comment.' This adds basic format and purpose information beyond the raw schema, but it is minimal and largely restates what the parameter names suggest. It does not explain how to obtain these IDs or any relationships between them.
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 a comment for a work item.' The verb 'Delete' is specific, and the resource ('comment for a work item') is well-defined, distinguishing it from sibling tools like create_work_item_comment, update_work_item_comment, retrieve_work_item_comment, and list_work_item_comments.
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 use when deleting a comment, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. For example, it does not note that the comment must exist or that permissions are required. However, the operation is straightforward, so the intended usage is reasonably clear.
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 disclosing behavioral traits. It states that the operation deletes a work log but does not mention whether deletion is permanent, requires special permissions, or returns any confirmation. This is a significant gap for a destructive 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 concise and well-structured, with a clear one-sentence purpose followed by a bulleted list of parameters. Every word earns its place and there is no 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 delete operation with three parameters and no output schema, the description covers the essential action and parameters. However, it lacks behavioral context (permanence, permissions) and usage guidance, making it only minimally viable-adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema description coverage is 0%, the description adds meaning to all three parameters by stating they are UUIDs of the project, work item, and work log respectively. This goes beyond the bare schema property names and provides sufficient context for parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('a work log for a work item'), which distinguishes it from sibling tools like delete_work_item_comment or delete_work_item_link.
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 (e.g., update_work_log, list_work_logs), nor does it mention any prerequisites or conditions. The intended use case is only implied by the name and description.
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. It mentions return type but omits pagination behavior and includes a workspace_slug parameter not present in the schema, creating a misleading behavioral expectation.
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 brief and front-loaded with a clear summary, but the Args section includes an invalid parameter, slightly marring otherwise clean structure.
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 a simple list operation and an output schema exists, but the description omits pagination defaults and introduces a phantom parameter. It would benefit from clarifying the relationship to list_work_items.
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 some meaning for project_id and params (e.g., UUID, query dictionary examples), but it also lists workspace_slug, which the schema rejects via additionalProperties:false. This conflicting information undermines parameter clarity given 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 'List all intake work items in a project' with a specific verb, resource, and scope. It naturally differentiates from sibling list_work_items by specifying 'intake' items.
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 that this tool is for listing intake work items in a project, making its use case apparent. However, it does not explicitly reference alternatives or 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?
No annotations are provided, so the description carries the full burden. It states the return type but does not disclose behavior of the arbitrary 'params' dictionary, pagination behavior, or potential errors. The read-only nature is implied but not explicitly stated.
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 compact, well-structured with Args and Returns sections, and contains no filler. Every sentence contributes useful information.
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 and an output schema exists, so return values are covered. However, the 'params' dictionary is a black box, and the description does not specify supported query parameters or pagination, leaving a gap for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It clarifies project_id is a UUID and params are optional query parameters, but the dictionary contents are left undefined. This is minimal assistance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all labels in a project' with a specific verb and resource. It distinguishes from label-specific tools like create_label, retrieve_label, and list_release_labels by focusing on project-level label listing.
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 listing labels in a project but provides no explicit guidance on when to choose this tool over alternatives like list_release_labels. There are no stated exclusions or alternative conditions.
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 transparency. It explains the toggle behavior (True=archive, False=unarchive) but does not disclose side effects, permission requirements, reversibility, or response format. For a mutation tool, this is a notable gap.
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 and front-loaded. The first line states the action, and the arg list is clear and minimal. Every sentence contributes without any fluff or repetition.
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 toggle tool, the description covers the purpose and all parameters. However, with no output schema and no annotations, it omits any mention of return values, error conditions, or side effects. It is adequate but not fully complete for a mutation 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 is the only source of parameter meaning. All three parameters are mentioned, with the archive parameter clearly defined as 'True to archive, False to unarchive.' However, project_id and module_id are only described as 'UUID of the project/module,' which adds little beyond the property 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 opens with a specific verb and resource: 'Archive or unarchive a module.' This clearly states the tool's action and object, and distinguishes it from sibling tools like manage_project_archive, manage_cycle_archive, and manage_work_item_archive 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?
Usage is implied by the resource type (module), but there is no explicit guidance about when to use this tool versus alternatives like manage_project_archive or manage_cycle_archive. No preconditions or exclusions are mentioned, so the context is clear but not fully elaborated.
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 disclosing behavioral traits. It states that the tool updates a milestone and returns the updated object, but it does not disclose whether updates are partial or full, what happens to omitted fields, permission requirements, or any side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using separate lines for each parameter within an 'Args' block and a 'Returns' line. There is no redundant text or repetition; every sentence contributes useful information.
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 simple 6-parameter update operation and the presence of an output schema, the description covers parameter meanings and the return type reasonably well. However, it lacks usage guidelines and behavioral transparency regarding partial updates, making it only minimally complete for an agent to confidently invoke.
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 description compensates for the 0% schema coverage by providing a meaningful label for each parameter, such as 'UUID of the project' and 'Target date for the milestone (ISO 8601 format)'. It adds value beyond the raw schema types, though it does not clarify optionality or update 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 'Update a milestone by ID', which is a specific verb+resource combination. It distinguishes this tool from sibling tools like create_milestone, retrieve_milestone, delete_milestone, and manage_milestone_work_items by focusing on updating an existing milestone's core fields.
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. It does not mention exclusions, prerequisites, or relationships to sibling tools like manage_milestone_work_items. The intended usage is only implied by the tool name and action.
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 exist, so the description must disclose mutation side effects, scope behavior, and prerequisites. It mentions 'Omit for workspace scope' for project_id and describes the return object, but does not state whether the update is partial, whether the option must already exist, or any permission/reversibility 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?
The description is efficiently structured with a one-line purpose, an Args block, and a Returns line. Every parameter line carries essential information without redundancy, making it easy to scan.
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 9-parameter mutation with no annotations, the description covers purpose, parameters, and return type but omits usage context, prerequisite existence, and partial-update semantics. It is adequate but not fully complete for complex agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by annotating every parameter with a concise meaning, including UUID roles, the project scope omission behavior, and color format. This adds clear value beyond the bare input schema, though external_source/external_id could use slightly more detail.
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 resource ('an option on a work item property'), clearly distinguishing it from sibling tools like create_work_item_property_option, retrieve_work_item_property_option, and delete_work_item_property_option. The tool name aligns with the description, making 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit 'when to use' guidance or alternatives are mentioned. The description only states the action and parameters, leaving the agent to infer when to choose update over create/retrieve/delete siblings from the 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?
No annotations are provided, so the description must carry the full burden. It lists parameters and return type but does not disclose key behaviors such as whether updates are partial (e.g., omitted fields preserved), what happens if the definition_id does not exist, or permission 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?
The description is well-structured with a purpose statement, Args, and Returns. It is concise and front-loaded, with no unnecessary prose.
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 description covers purpose, all parameters, and return type, and an output schema is indicated. However, it omits critical update semantics such as partial update behavior, error conditions, and prerequisite conditions, leaving an agent with gaps in how to safely invoke the 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 0%, so the Args section must compensate. It provides limited added meaning, e.g., 'definition_id: UUID of the relation definition to update' is useful, but most others are tautological re-statements like 'Updated outward label' without deeper constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing workspace relation definition' with a specific verb and resource. It is distinct from sibling tools like 'create_work_item_relation_definition' and 'delete_work_item_relation_definition'.
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 word 'Update' and 'existing', but there is no explicit guidance on when to use this tool versus alternatives, nor any mention of prerequisites or 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?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Create a new milestone' and returns a 'Created Milestone object,' with no mention of side effects, required permissions, validation rules, or project existence requirements. This is insufficient 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 clean docstring with an Args list and Returns line. Every line provides necessary information without redundancy, and the structure is easy to scan. It is appropriately sized for the tool's simplicity.
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 an output schema present, the description does not need to elaborate on return values. It covers all parameters, including required vs optional (implicitly via schema), and notes the ISO format for target_date. However, it lacks broader context such as when a milestone might be invalid or how it relates to projects, but this is not critical for a straightforward create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to all five parameters in the Args section, e.g., 'project_id: UUID of the project' and 'target_date: Target date for the milestone (ISO 8601 format).' Since schema description coverage is 0%, this fully compensates by explaining each parameter's purpose and format, though some descriptions are terse (e.g., 'external_source: External system source 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 opens with 'Create a new milestone,' which is a specific verb+resource construction. It clearly distinguishes the tool from sibling CRUD tools like update_milestone, delete_milestone, list_milestones, and retrieve_milestone by the verb 'create.'
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. It does not mention prerequisites, exclusions, or scenarios where another tool would be appropriate. Sibling tools such as create_work_item or create_cycle are undifferentiated.
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 does not mention that deletion is permanent, whether related data is cascaded, or what happens to associated work items or release tags. It also lacks permission requirements or response format. The verb 'delete' implies destructiveness, but the description goes no further.
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—two sentences total—and front-loads the key action. Every word earns its place, with the parameter definition structured clearly under 'Args.' No unnecessary elaboration 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 destructive tool with no output schema and no annotations, the description is incomplete. It does not explain what the deletion does to related entities, whether it is reversible, or what success/failure looks like. Given the tool's simplicity, the description is minimal but leaves important operational questions unanswered.
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 description adds meaningful context for the single parameter, stating 'release_id: UUID of the release.' This goes beyond the schema's bare type definition (string) by clarifying that it is a UUID and identifying the release. The description compensates for the lack of schema-level documentation.
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 a release by ID.' It uses a specific verb (delete) and resource (release), distinguishing it from sibling tools like retrieve_release or update_release. The ID parameter is explicitly mentioned, leaving no ambiguity about the tool's function.
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 by stating what the tool does, but it offers no explicit guidance on when to use it versus alternatives. There are no stated exclusions or mentions of related tools like archive_release or soft-delete options. However, the purpose is clear enough that the implied usage is acceptable for a straightforward delete operation.
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 disclosure burden. While it states the tool makes an estimate active, it doesn't mention whether an existing active estimate is overwritten, any required states (e.g., draft), or whether the operation is reversible. The return value is noted, but 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose, then lists args and returns in a structured way. The Args/Returns block is somewhat redundant with the schema but adds semantic labels.
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 two-parameter link operation with an output schema present, the description covers the core behavior and return type. However, it omits details about overwriting existing active estimates or any constraints, leaving gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains both parameters as UUIDs and adds meaning by clarifying project_id is the target project and estimate_id is the estimate to activate. This goes beyond the bare schema, which only provides type 'string'.
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 ('link') and names the resource ('estimate to a project'), and clarifies the immediate effect: 'making it the active estimate system.' This clearly distinguishes it from sibling estimate tools that create, update, or delete estimates.
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—setting the active estimate for a project—but doesn't explicitly contrast this with alternatives like create_project_estimate or update_project_estimate, nor does it mention any prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 that it lists all states, and that params can be passed as query parameters, but it does not disclose pagination behavior, sorting, filtering capabilities, or whether the result includes archived/inactive states. For a simple read operation, this is minimally adequate but leaves behavioral details unspecified.
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 well-structured, using a clear Args/Returns format. Every line adds value: it names both parameters, their types, and the return type. There is zero 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?
The tool is simple: a list operation with two parameters. The description explains the parameters and return type. An output schema exists (not shown in the input), so return values are presumably detailed there. The description is complete enough for an agent to invoke the tool correctly, though it could mention that 'all states' includes all workflow states or whether it is scoped to a specific context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explicitly names both parameters and provides brief semantics: project_id is a UUID of the project, params is 'Optional query parameters as a dictionary'. This adds some meaning beyond the raw schema (which only gives types), but it does not explain the allowed keys or values for params. The description is helpful but not comprehensive.
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 operation: 'List all states in a project.' It identifies the resource (states) and the scope (project). It distinguishes from sibling list tools like list_cycles or list_work_items by naming 'states'. However, it does not explicitly define what a 'state' is (e.g., workflow state), which could be ambiguous in a project management context.
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: you need a project_id to list states, and it mentions optional query parameters. But there is no explicit guidance on when to use this tool versus alternatives, no exclusions, and no mention of prerequisites. Since there is no other 'list_states' sibling, the intended use is fairly clear, but this dimension lacks explicit direction.
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. It states the operation is 'Retrieve' and mentions the return type, but does not disclose any behavioral traits such as read-only guarantees, error responses, not-found behavior, or authorization requirements. This is a minimal read operation, but the description lacks explicit transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single sentence for the purpose, followed by clearly labeled Args and Returns sections. Every part earns its place, with no redundant phrasing or unnecessary detail.
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, the description covers the essential aspects: what it does, the parameters needed, and the return value. Given that an output schema exists (per context signals), the Returns text is supplementary. It lacks error-handling or edge-case details, but these are not critical for a straightforward fetch operation.
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 property descriptions (0% coverage), but the Args section in the description adds meaningful semantics: it specifies that both parameters are UUIDs and explains their roles ('of the customer', 'of the customer request'). This goes beyond the schema's bare type strings, though it does not detail constraints like format patterns or validation rules.
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 ('Retrieve') and resource ('customer request'), clearly distinguishing it from sibling tools like create_customer_request, update_customer_request, and delete_customer_request. The 'by ID' clarifies the scope, though the exact IDs are detailed in the Args section.
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 list_customer_requests or retrieve_customer. The description implies usage via 'Retrieve by ID' but does not explicitly state when to choose it or exclude other retrieval methods.
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 indicates a read operation ('Retrieve') and states the return type ('Cycle object'), but does not disclose error behavior, permission requirements, or any side effects. This is adequate for a simple retrieval tool but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an args/returns format. However, the inclusion of workspace_slug, which is not in the schema, introduces unnecessary clutter. Otherwise, every sentence earns its place.
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?
Although an output schema exists, the description is incomplete due to the workspace_slug mismatch with the input schema. It does not explain whether workspace_slug is required, optional, or extraneous, which could mislead the agent. For a simple retrieval tool, the description should clarify the parameter discrepancy and any workspace scoping.
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 has 0% description coverage, requiring the description to compensate. However, the description lists 'workspace_slug' as a parameter while the schema only includes project_id and cycle_id, and additionalProperties is false. This inconsistency confuses rather than clarifies. The descriptions for project_id and cycle_id are minimal ('UUID of...'), providing only slightly more than the schema's string type.
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 'Retrieve a cycle by ID' with a specific verb and resource, which distinguishes it from sibling tools like create_cycle, update_cycle, delete_cycle, and list_cycles. The parameter names further clarify the 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 implies usage when you have a cycle ID and need the full cycle object. It does not explicitly mention alternatives like list_cycles, but the context is clear given the tool name and purpose. No exclusions or prerequisites are stated, 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 must fully explain behavioral traits. It only says 'Update a cycle by ID' and returns the updated object, but does not disclose mutation effects, partial versus full replacement, permission requirements, or error scenarios.
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 clean docstring with a concise one-line purpose, an Args list, and a Returns line. It is generally well-structured, though the extra 'workspace_slug' parameter adds slight noise and inconsistency.
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 description covers all schema parameters and states the return value, but for a mutation with 10 parameters and no annotations, it lacks important context about behavior (e.g., partial vs. full update, auth needs, error conditions) and how it fits into the broader cycle workflow.
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 description adds concrete semantics for each schema parameter (e.g., 'UUID of the project', 'Cycle start date (ISO 8601 format)'), which goes beyond the bare types in the schema. However, it includes 'workspace_slug' which is not present in the schema, potentially misleading 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 opens with 'Update a cycle by ID' – a specific verb and resource, clearly distinguishing it from siblings like create_cycle, retrieve_cycle, delete_cycle, and complete_cycle.
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 one-line purpose implies usage when updating an existing cycle, but there is no explicit guidance on when not to use it, prerequisites, or alternatives. Guidance is minimal and implied rather than 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?
With no annotations, the description carries the full burden of behavioral disclosure. It does offer some useful context: it states the return type ('Updated WorkItem object') and explains the description_stripped behavior (wrapped into HTML, ignored if description_html is set). However, it fails to disclose critical update semantics such as whether unspecified fields are reset or preserved, whether the operation is a partial merge or full replacement, or any permission requirements. The partial transparency earns a middle score.
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 appropriately structured with a one-line purpose, a clean Args list, and a Returns line. The list is long (20 parameters) but necessary given the lack of schema descriptions. Every parameter has a brief, to-the-point annotation, and the note about description_stripped is concise. It is not verbose despite its length.
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 20 parameters, no annotations, and an output schema that likely describes the return value, the description covers all parameter meanings and states the return type. However, it omits key behavioral context such as how partial updates are handled, whether fields are nullable (though schema shows many nullable), and what fields are mutually exclusive (e.g., description_html vs description_stripped). The lack of usage guidance further reduces completeness, making it adequate but not thorough.
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, and it does. Each parameter is listed with a concise semantic annotation, including explicit enum values for priority, date format for start_date/target_date, and the nuanced explanation of description_stripped behavior. While some entries are tautological (e.g., 'name: Work item name'), the overall coverage is strong and adds real meaning 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 opens with 'Update a work item by ID,' which is a specific verb+resource statement. It clearly distinguishes this tool from create, delete, and retrieve work item operations, as well as from more specialized updates like update_work_item_comment or update_work_item_property. The required work_item_id parameter makes the scope 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for modifying existing work items, nor does it compare against create_work_item, update_work_item_property, or other related update tools. There are no explicit when-to-use or when-not-to-use instructions, 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?
With no annotations, the description carries the full burden for behavioral disclosure. It states the action and return type but does not reveal side effects, partial-update semantics, idempotency, permission requirements, or error behavior. Some conditional parameter context is provided, but key mutation traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence purpose, followed by a well-organized Args list. It contains no filler or redundant content; each line adds necessary information, making the length appropriate for the tool's complexity.
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 description thoroughly covers parameters and key conditional requirements, but lacks broader context: it does not state whether fields are optional for partial updates, whether changing property_type is restricted, or what the Updated WorkItemProperty object contains beyond its name. For a 15-param mutation tool, it is functional but not fully 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%, and the description fully compensates by documenting all 15 parameters with types, allowed values, and conditional requirements. For example, it specifies the enum for property_type, the required settings structures for TEXT/DATETIME, and when relation_type is required. This is exemplary parameter documentation.
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 work item property by ID,' which clearly states the verb and resource. It distinguishes this tool from siblings like update_work_item (which updates work items, not properties) and create/delete/retrieve_work_item_property. There is no ambiguity about what this 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 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_work_item_property or manage_work_item_type_properties. The only usage hints are parameter-level conditions (e.g., 'required when project_id is provided'), which do not address tool selection.
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 fails to disclose whether this is a partial update or a full replacement, what permissions are required, or what happens to existing fields like project_ids when updated. The 'Returns' section mentions the return value but does not cover side effects or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an initial action sentence followed by an 'Args' list and a 'Returns' line. It is concise but includes necessary parameter details. However, the parameter descriptions are somewhat verbose, and not all terms (e.g., 'external_source') are self-explanatory, so brevity could be improved without losing clarity.
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 presence of an output schema covers return values, and the parameter descriptions are complete. However, the description doesn't provide guidance on when to use this tool versus alternatives, nor does it address important behavioral aspects like partial updates or permission requirements. This leaves the tool under-specified for an agent to use confidently.
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 zero description coverage, so the description's parameter explanations are essential. It provides meaningful semantics for each argument, such as 'Omit for workspace scope' for project_id and 'List of project IDs this type applies to' for project_ids. This adds value beyond the bare schema types.
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: 'Update a work item type by ID.' This specifies a unique verb and resource, distinguishing it from sibling tools like create, retrieve, and delete work item types. The addition of 'by ID' further clarifies the 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?
The description implies usage for updating existing work item types, but it doesn't explicitly state alternatives or exclusions. The mention of 'Omit for workspace scope' offers some context about project scoping, but it doesn't compare with other tools such as 'create_work_item_type' or 'manage_work_item_type_properties'.
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 full burden for behavioral disclosure. It only says 'Create a new state' and lists parameters, but does not clarify side effects, permissions, uniqueness constraints, default behavior, or error conditions. This is insufficient 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 concise, well-structured docstring with a clear opening statement followed by a parameter list. No unnecessary words or repetition; every line contributes to understanding the tool.
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 has 10 parameters, no annotations, and an output schema. The description documents all parameters and return value, but lacks usage context, prerequisites, and behavioral details. Given the complexity, it is adequate but not comprehensive, especially since the agent might need to know when creation is appropriate versus updating an existing state.
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 lists all 10 parameters with brief explanations, including useful context for 'group' (e.g., backlog, unstarted) and 'color' (hex code). However, some explanations are tautological (e.g., 'description: State description'), which prevents a perfect score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new state.' with a specific verb and resource. It distinguishes from sibling tools like list_states, retrieve_state, update_state, and delete_state 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 description implies usage through the verb 'create' but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are mentioned, leaving the agent to infer from the tool name and sibling list.
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?
The description discloses one behavioral trait: it raises a ToolError when the initiatives feature is disabled, and notes that the initiative is then a work item. However, it does not mention whether deletion is permanent, involves cascading effects, or requires special permissions. With no annotations, this leaves significant behavioral gaps for a destructive 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 extremely concise: a single clear sentence plus a compact Args/Raises structure. Every line adds value, and the error information is presented without fluff. It is well-structured and front-loaded.
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 (one parameter, no output schema), the description covers the call signature and a key error case. However, it omits what happens on success (e.g., returns nothing, confirmation), and does not address irreversibility or side effects, which are important for a delete operation. Thus 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 schema only defines initiative_id as a string, but the description adds critical semantics: it is a UUID and identifies the initiative to be deleted. This provides necessary meaning beyond the raw type, fully covering the single parameter despite 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 'Delete an initiative by ID' with a specific verb (delete) and resource (initiative), distinguishing it from sibling tools like create/retrieve/update_initiative. It also specifies the parameter type (UUID), removing ambiguity.
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. While 'delete' implies a clear action, the description does not mention exclusions, prerequisites, or cases where other tools (e.g., delete_work_item) might be appropriate. The only conditional guidance is about the disabled feature error, but it does not clarify alternative 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 carry the full burden of behavioral disclosure. It states only that the tool deletes a single estimate point, but does not mention irreversibility, required permissions, cascading effects, or any other behavioral traits. For a destructive operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line summary followed by an Args block with clear parameter explanations. Every sentence provides necessary information, and no redundant content exists.
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 delete operation with three parameters, the description adequately explains what the tool does and what each parameter means. However, it lacks usage guidance and behavioral transparency (e.g., irreversibility, permissions), and no output schema or return behavior is described. It meets the minimum viable level but no more.
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 only lists parameters as strings with no descriptions, while the description explains each parameter: project_id is UUID of the project, estimate_id is UUID of the estimate, and estimate_point_id is UUID of the estimate point to delete. This adds meaningful context and 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 verb 'Delete' and the specific resource 'a single estimate point', which distinguishes it from sibling tools like delete_project_estimate (deleting a whole estimate) and update_project_estimate_point. The one-line summary is direct 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when deleting one estimate point, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are given, leaving the agent to infer from the name. This meets the 'implied usage' level, but not clear guidance.
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 does not disclose any behavioral traits beyond the verb 'delete' – no mention of permissions, irreversibility, side effects, or response behavior. This leaves the agent to infer from the 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 extremely concise, consisting of a single sentence plus a parameter annotation. It front-loads the purpose and then provides the parameter detail. No extraneous 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?
Given the simplicity of the tool (one parameter, no output schema), the description covers the essential action and parameter semantics. It does not discuss edge cases like not-found behavior or permanence, but for a straightforward delete, this is largely sufficient.
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 only defines tag_id as a required string with no description. The description compensates by specifying 'UUID of the release tag', giving the agent the format and semantic meaning of the parameter. This is exactly the kind of compensation needed for 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 action (delete) and resource (release tag) with the identifying mechanism (by ID). This distinguishes it from sibling tools like delete_release or delete_release_label.
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, nor any prerequisites or contexts. It does not mislead, but it offers no usage direction.
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 states the primary action but fails to mention irreversibility, permissions, cascading effects (e.g., on associated work items), or error behavior. For a destructive operation, this is a significant gap.
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, front-loaded with the primary action, and uses a clear Args section for parameters. Every sentence adds value—no filler or redundancy.
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 operation with no annotations and no output schema, the description is incomplete. It lacks information on reversibility, required permissions, potential side effects on related data, and typical error scenarios. The parameter scoping is helpful but doesn't compensate for the missing behavioral context.
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?
Although schema descriptions are absent, the description explicitly explains both parameters: work_item_type_id as the UUID of the work item type, and project_id as the UUID of the project with clear guidance to omit for workspace scope. This adds meaning beyond the raw 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 'Delete a work item type by ID' uses a specific verb and resource, and the added arg details clarify the scope (workspace vs project). It distinguishes well from sibling deletion tools like delete_work_item or delete_work_item_attachment.
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 as a delete operation and provides scoping guidance via 'Omit for workspace scope.' However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or consequences.
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 discloses that the tool removes a link (not the page itself), but it does not mention permissions, reversibility, side effects, or return behavior, leaving significant ambiguity for a mutation 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 front-loaded with the action, followed by a clean, concise parameter list. Every sentence earns its place with no redundancy or irrelevant detail.
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 detach operation, the description covers the basic action and parameters, but it lacks detail on expected behavior after removal (e.g., whether the page remains) and any return values or error conditions. Given no output schema or annotations, this is a moderate gap.
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 no descriptions (0% coverage), but the description adds meaningful context for all three parameters, explicitly clarifying that work_item_page_id is the link ID, not the page ID. This maps each parameter to its purpose beyond the raw 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 first sentence 'Remove a page link from a work item' clearly states the specific action and resource. It also distinguishes from siblings like attach_page_to_work_item by focusing on the opposite operation.
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 removing a page link from a work item, but it does not explicitly state when to use it versus alternatives or provide any exclusions. No alternative tools are mentioned, so guidance is minimal.
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 fully disclose behavior. 'List' implies a read-only operation, but the description does not explicitly state read-only, pagination, permissions, or side effects. It mentions the return type but not behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: main action first, then args, then returns. Every sentence serves a purpose with no redundant 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?
For a simple list tool, the description covers purpose, args, and return type. However, it lacks usage alternatives, behavioral notes, and potential edge cases (e.g., pagination, ordering). Given the sibling tools, more comparison context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter as 'UUID of the project' and 'UUID of the work item'. This adds meaningful context beyond the parameter names, though it could specify the relationship more precisely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all pages linked to a work item' with a specific verb and resource. It distinguishes from sibling tools like list_pages (lists all pages) and page attach/detach 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?
The implied usage is when needing pages for a specific work item, but it does not explicitly mention when not to use this tool or compare with alternatives like list_pages. The context is clear but lacks explicit 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 mutation action and the single-call behavior, but does not disclose essential traits such as whether the operation replaces existing cycle membership, how duplicates are handled, permissions required, or reversibility. For a mutation tool, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action, followed by a key constraint and a terse parameter list. Every sentence contributes useful information without redundancy, making it appropriately sized for an AI agent.
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 has no output schema and no annotations, so the description must supply return-value and side-effect expectations. It does not mention what the response contains or whether the operation is additive/subtractive to existing membership. While the basic operation is clear, completeness is limited for an agent to predict outcomes fully.
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 does so with an Args section explaining each parameter by role and type, and explicitly notes the constraint that at least one of add_ids or remove_ids is required. This adds meaningful meaning beyond the bare schema, though it could be more detailed about expected item formats or validation.
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: 'Add or remove work items on a cycle in a single call.' This specific verb+resource distinguishes it from siblings like list_cycle_work_items (read-only) and transfer_cycle_work_items (moving items between cycles).
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 through its core statement and adds a prerequisite ('At least one of add_ids or remove_ids must be provided'). However, it does not explicitly mention when to use this tool versus alternatives like transfer_cycle_work_items, nor does it offer exclusions. The usage context is clear but not fully differentiated.
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 disclosing behavioral traits. It only states 'Retrieve a label by ID' without mentioning potential errors, permissions, side effects, or behavior when the label does not exist. The description adds minimal behavioral context beyond the operation itself.
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 and well-structured, with a one-line summary followed by a clear Args/Returns section. Every sentence adds value, and there is no superfluous 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?
The tool is simple, has an output schema to cover return values, and the description explains the parameters. However, with no annotations and minimal behavioral disclosure, there are gaps such as error handling and prerequisites. It is minimally adequate but not fully complete for an agent to anticipate all outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explicitly explaining both parameters in an Args section: 'project_id: UUID of the project' and 'label_id: UUID of the label'. This adds semantic meaning and type information beyond the bare schema types of 'string'.
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 'Retrieve a label by ID.' using the specific verb 'retrieve' and names the resource 'label'. It distinguishes from sibling tools like list_labels, create_label, update_label, and delete_label by focusing on fetching a single label by its identifier.
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 fetching a specific label by ID, but does not explicitly mention alternatives like list_labels for browsing labels or limitations such as requiring an existing label. It provides clear context but lacks explicit when-not-to-use or alternative guidance.
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 only discloses that it returns a WorkItemLink object and takes UUID parameters. It does not mention error behavior, required permissions, or that this is a harmless read operation, leaving the agent to infer safety and failure modes.
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 compact, with a one-line purpose and structured Args/Returns sections. It avoids unnecessary wording while covering the essential information.
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 retrieval tool, the description covers the operation, inputs, and return type, and an output schema exists. However, it lacks usage guidance and behavioral details such as error cases, making it only minimally 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 description provides semantic context for all three parameters beyond the schema's bare string types, explaining that project_id, work_item_id, and link_id are UUIDs of their respective entities. This meaningfully compensates for the 0% schema description 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 'Retrieve a specific link for a work item' with a specific verb and resource, and includes the link_id parameter to clarify it targets a single item. This distinguishes it from sibling tools like list_work_item_links, which retrieves multiple links.
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 when a specific link is needed by requiring link_id, but it does not explicitly contrast with list_work_item_links or mention when not to use it. This is minimal but at least conveys the single-item scope.
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 side effects. It does reveal the key destructive consequence: every customer's values for the property are also deleted. However, it does not mention irreversibility, required permissions, or other potential impacts.
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 short sentences plus an Args line, with every word earning its place. The main action is front-loaded and the parameter documentation is compact and clear.
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 delete tool, it covers the purpose, the affected data, and the parameter meaning. An explicit irreversibility warning would improve completeness, but the cascade warning provides enough context 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?
The schema only indicates property_id is a required string, while the description adds that it is a UUID of the customer property, providing semantic meaning. With 0% schema description coverage, this extra clarity is valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Delete a customer property, and every customer's values for it,' using a specific verb and resource. The cascade detail distinguishes it from sibling delete tools like delete_customer or delete_work_item_property.
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 on when to choose this tool over alternatives or what prerequisites might be needed. It simply states the action without context, exclusions, or comparisons to related 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 carries the full burden. It discloses the ToolError for the disabled feature and mentions the pagination-related params (per_page, cursor), but it does not clarify whether 'all' requires iterative pagination or what the response shape is beyond 'List of Initiative objects' (though an output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear Args, Returns, and Raises sections. Every sentence adds value, and the error explanation is brief but useful. There is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set (one optional dict) and the presence of an output schema, the description covers purpose, parameters, return type, and an error condition. It could mention pagination behavior more explicitly, but the examples of per_page/cursor hint at it, making it sufficiently 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 input schema has no descriptions (0% coverage), so the description's 'Optional query parameters as a dictionary (e.g., per_page, cursor)' adds needed semantics. However, it only gives two examples and does not enumerate possible keys, leaving the full parameter space vague.
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 'List all initiatives in a workspace' with a clear verb and resource. It distinguishes from siblings like retrieve_initiative (single item) and list_initiative_projects (different resource), and the scope is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context (list all initiatives in a workspace) and even notes the disabled-feature error, but it does not explicitly mention when to use this tool versus alternatives like list_projects or search_work_items. Usage is implied rather than directly contrasted with siblings.
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 full responsibility. It does not explicitly state whether the operation is read-only, the required auth permissions, or any pagination/filtering behavior. The only behavioral detail (return type) is redundant with the output 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?
The description is concise and well-structured: a one-sentence purpose, then Args and Returns sections. Each sentence serves a distinct purpose without fluff, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a basic call with required IDs, and the output schema covers return values. The optional params remain a black box, but that is a common pattern. For a straightforward list operation, the provided context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by clarifying semantic meaning: project_id and milestone_id are identified as UUIDs, and params is described as an optional query-parameters dictionary. This goes beyond the schema's raw string/object types, though it does not enumerate valid query params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List work items in a milestone' with a specific verb ('List') and resource ('work items in a milestone'). The name and description distinguish it from sibling tools like list_cycle_work_items or list_module_work_items by explicitly naming the milestone 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 tool name and argument descriptions: use when you have a project_id and milestone_id and want the work items in that milestone. However, no explicit guidance is given on when to prefer this over alternatives like list_work_items, list_cycle_work_items, or manage_milestone_work_items.
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 returns a List of WorkItemPropertyOption objects, which is useful, but it does not mention read-only nature, authentication requirements, pagination, or error behavior. For a list operation this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an Args/Returns format. It front-loads the main purpose and every sentence provides necessary information without any 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?
For a simple list tool with an output schema, the description provides enough to invoke it correctly for the core use case. The main gap is the vague 'params' parameter and lack of detail on pagination or result ordering, but the output schema covers return shape.
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 explains property_id (UUID of the work item property) and project_id (UUID of the project, with omit-for-workspace-scope guidance), which adds meaning beyond the schema. However, 'params' is only described as 'Optional query parameters' without details on what filters or options are available, leaving a 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 uses a specific verb and resource ('List options for a work item property') that clearly states what the tool does. It distinguishes from sibling tools like list_work_item_properties (which lists properties, not options) and retrieve_work_item_property_option (which retrieves a single option).
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 through its name and first sentence, and it provides scoping guidance ('Omit for workspace scope'). However, it does not explicitly state when not to use it or mention alternative tools, so the guidance is implied rather than 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?
With no annotations provided, the description carries the full burden. It states the operation is a retrieval (read-only) and returns 'The Customer', but it does not disclose error behavior (e.g., what happens if not found), authentication requirements, or other side effects. It is adequate for a simple read but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with 'Args' and 'Returns' sections. Every sentence earns its place, and there is no redundant or vague wording.
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 single-parameter retrieval with an output schema present, the description adequately covers the core behavior, parameter, and return value. It could be improved by mentioning error conditions or when to use it, but those are secondary for a basic CRUD read 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?
The schema provides only 'type: string' with no description. The description adds 'UUID of the customer', clarifying the expected format and role of the parameter. While this is helpful, it is minimal and could also be inferred from the parameter name and tool purpose. With 0% schema coverage, the description partially compensates but not fully.
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 ('Retrieve') and resource ('customer') with the scope 'by ID', making it unambiguous. It clearly distinguishes from sibling tools like list_customers, create_customer, update_customer, and delete_customer.
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: you use this tool when you have a customer ID and need the customer object. However, it does not explicitly contrast with alternatives like list_customers or mention when not to use it, leaving room for ambiguity in more complex workflows.
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 disclosing behavior. 'Retrieve' clearly signals a non-mutating read operation, and 'Returns: Module object' specifies the outcome. It does not detail error cases or auth, but for a simple read operation this is reasonably transparent.
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 concise and well-structured with a purpose statement followed by Args and Returns sections. It wastes no words, but the inclusion of the extraneous 'workspace_slug' parameter is a minor structural flaw.
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 retrieval tool with an output schema, the description covers the core purpose, parameters, and return type. However, the workspace_slug inconsistency is a significant gap that could lead to incorrect invocations, and it lacks guidance on when to use this tool versus alternatives.
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 human-readable meanings for parameters (e.g., 'UUID of the project'), which is valuable given the input schema has no descriptions. However, it lists 'workspace_slug' which is not present in the input schema, creating potential confusion for 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 'Retrieve a module by ID' with a specific verb and resource, clearly indicating this is a single-resource read operation. It distinguishes from sibling tools like list_modules and create_module by emphasizing retrieval by ID.
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 when a specific module ID and project ID are known, but it does not explicitly state when to prefer this over list_modules or provide exclusions/alternatives. The 'by ID' phrasing gives some contextual guidance but lacks explicit direction.
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 says 'Returns: The Release' but does not mention error cases (e.g., not found), permissions, or whether the operation is read-only. For a retrieval tool, this is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, an args list, and a returns line. There is no redundant or filler text, and every sentence 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?
Given the simplicity of the tool (one required parameter) and the presence of an output schema, the description is largely complete. It explains the input and the return type. However, it lacks information about error handling or edge cases, so it falls just short of full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must compensate. It adds semantic value by specifying that release_id is a UUID, which is more informative than the schema's generic 'string' type. The single parameter is clearly documented in the Args section.
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 'Retrieve' with a specific resource 'release by ID', clearly distinguishing it from sibling tools like list_releases or retrieve_release_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 usage context is implied: use this when you have a release ID and need a single release. However, it does not explicitly contrast with alternatives (e.g., list_releases) or state when not to use it, leaving some room for an agent to infer.
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 adds no behavioral context beyond the obvious 'retrieve' operation. It does not disclose permissions, error behavior, side effects, or any constraints. The 'Returns: The ReleaseTag' line is helpful but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single purpose sentence, a one-line arg explanation, and a one-line return note. Every element earns its place with zero waste 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 retrieve-by-ID tool with an output schema, the description is mostly complete. It lacks explicit error handling or not-found behavior, but given the tool's simplicity and the presence of an output schema, it covers the essentials well.
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. The Args section explicitly explains tag_id as 'UUID of the release tag', adding semantic meaning beyond the schema's plain string type. This is sufficient for the single 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 'Retrieve a release tag by ID' – a specific verb (retrieve) with a specific resource (release tag) and the identifier method (by ID). This distinguishes it from sibling tools like list_release_tags, create_release_tag, update_release_tag, and delete_release_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 usage is implied (use when you have a tag_id to fetch a single tag), but there is no explicit guidance on when to use this over list_release_tags or other alternatives. No exclusions or alternative tool references 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?
With no annotations, the description carries the burden of behavioral disclosure. 'Retrieve' implicitly indicates a read-only operation, and it states the return type, but it does not mention potential errors, permission requirements, or absence of side effects. This is adequate for a simple read operation but lacks richer context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an Args/Returns format. Every line provides necessary information—the action, each parameter's purpose, and the return type—without any redundant wording.
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 presence of an output schema, the description covers the core aspects: what it does, all required parameters, and the return type. It does not discuss error handling or permission prerequisites, but for a straightforward retrieve operation this is mostly sufficient. A brief note distinguishing it from list_work_item_activities would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context beyond the schema by specifying that each parameter is a UUID for its respective resource. While the schema only lists property names and types as strings, the description clarifies the exact semantic role and format, which is valuable for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a specific activity for a work item, using the verb 'retrieve' and specifying the resource. It distinguishes itself from the sibling 'list_work_item_activities' by focusing on a single activity, and the required activity_id parameter reinforces this.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 like list_work_item_activities. The word 'specific' implies it is for fetching by ID, but there is no direct comparison or exclusion, leaving the agent without clear decision criteria.
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?
There are no annotations, so the description carries the full burden. The verb 'Retrieve' implies read-only, and the Args section adds endpoint-scoping behavior. However, it does not explicitly state no-side-effects, error handling, or authorization requirements, 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 compact and well-structured: a one-line purpose, an Args list covering all parameters, and a Returns line. No redundant content; every sentence contributes.
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, the description covers the essential invocation details and return type, especially with an output schema available. It lacks explicit usage guidance and behavioral disclaimers, but is largely complete. The gap in usage guidelines prevents a top score.
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, but the Args section compensates by explaining each parameter's meaning and optionality. It clarifies that project_id can be omitted for workspace scope and work_item_type_id can be omitted for project-level endpoint, adding genuine value beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve a work item property by ID' with a specific verb and resource. It clearly distinguishes from sibling retrieval tools by specifying the object type and single-item lookup.
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 mention when to choose this tool over alternatives like list_work_item_properties or retrieve_work_item_property_option. It only provides parameter-level scoping guidance (e.g., omit project_id for workspace scope), which is not tool-selection guidance. 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?
No annotations are provided, so the description bears the full burden of disclosing behavioral traits. It mentions that the tool returns a WorkItemType object and explains the project_id scope, but it does not mention error behavior, permissions, read-only status, or any other side effects. This is a significant omission for a tool with no annotation backups.
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 plus a well-structured Args/Returns block. It is front-loaded with the purpose and contains no filler. Every sentence and argument earns its place, making it highly concise and easy to parse.
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 an output schema present, the description covers purpose, parameters, and the return type sufficiently. It lacks usage guidance and error semantics, but given the low complexity and the presence of an output schema, it is largely complete for its intended function.
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. The description compensates by clarifying that work_item_type_id is a UUID and that project_id is a UUID for project scope, with omission meaning workspace scope. This adds meaningful semantic detail beyond the raw schema, though it could further clarify what 'workspace scope' implies.
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 'Retrieve a work item type by ID', using a specific verb and resource, and clearly identifies the primary lookup key. This distinguishes it from sibling tools like list_work_item_types or update_work_item_type, which have different actions 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a work item type ID is known, and the note 'Omit for workspace scope' provides context for the optional project_id. However, it does not explicitly mention when to prefer this tool over alternatives such as resolve_work_item_type or list_work_item_types.
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 behavior. It only says 'Update a project by ID' and 'Returns: Updated Project object'. It does not mention side effects, permissions, whether omitted fields are left unchanged or reset, or any irreversible consequences. This is insufficient for a mutation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a clear one-line purpose and then lists parameters in a structured Args block. Each parameter gets one line with no filler. Given the large parameter count, this is appropriately sized and organized, though it could include a brief usage note without bloating.
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 complex (24 parameters, no schema descriptions, no annotations). The description covers all parameters and the return value, but lacks guidance on when to use this vs update_project_features, what happens with null vs omitted fields, and any prerequisites. It is adequate for parameter lookup but not fully complete for confident 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%, and there are 24 parameters, so the description carries the full burden. It provides short explanations for each parameter (e.g., 'network: Project visibility (0=secret, 2=public)', 'archive_in: Days until auto-archive'), adding meaning beyond the bare schema. However, some descriptions are tautological (e.g., 'name: Project name') and lack depth on formats, defaults, or relationships.
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 opening phrase 'Update a project by ID' clearly specifies the action (update) and the resource (project) with a required identifier. It distinguishes this from siblings like create_project, retrieve_project, and update_project_features by focusing on general project fields rather than features.
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 this is for updating an existing project by ID, which provides clear context for when to use it. However, it does not explicitly mention when not to use it or mention alternative tools such as update_project_features for feature-specific updates, so it lacks explicit 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?
With no annotations, the description carries the burden. It explains each parameter toggles a feature and indicates the return object, but does not clarify that null means 'leave unchanged', nor does it disclose any permissions or side effects. The workspace_slug parameter appears in the description but is absent from the schema, which adds confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, Args block, and Returns line. Each parameter is on its own line, making it scannable. It is slightly repetitive with 'Enable/disable' repeated six times but remains efficient.
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 and an output schema, the description covers the main purpose and parameter semantics, but misses critical context like partial update behavior (null = unchanged) and the workspace_slug/schema mismatch. The return type is stated, but without the output schema details, this is adequate but not 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 description coverage is 0%, so the description must compensate. It provides a meaning for each boolean parameter ('Enable/disable ...'), which adds value beyond the bare schema. However, it lists workspace_slug which is not in the schema, and it doesn't explain null semantics, marking a slight deduction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update features of a project' with a specific verb and resource, and enumerates the feature toggles (modules, cycles, views, etc.). It is distinct from sibling tools like get_features (read) and update_workspace_features (workspace 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?
The description implies project-level feature updates but does not explicitly mention when to prefer this over update_workspace_features or how it relates to get_features. No when-not or alternative guidance is 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?
With no annotations, the description carries the burden of behavioral disclosure. It clearly states the mutation (create) and notes the return value ('Returns: Created Label object'), but lacks details on side effects, validation rules, uniqueness, or permission requirements. This is adequate but not thorough.
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 structured as a clear docstring with a title, args list, and returns line. It is concise, with no extraneous information, and every sentence adds value. The parameter list is organized and easy to parse.
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 8-parameter complexity and lack of annotations, the description covers all parameters and states the return type. It does not mention when to use, edge cases, or constraints like required permissions, but these are secondary for a simple create operation. Overall, it is reasonably 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?
The description provides meaningful context for every parameter beyond the schema's type-only definitions. For example, it explains 'project_id: UUID of the project', 'color: Label color (hex color code)', and 'parent: UUID of the parent label (for nested labels)'. This fully compensates for the 0% schema description 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 'Create a new label' uses a specific verb and resource, clearly distinguishing it from sibling operations like retrieve_label, update_label, and delete_label. The action is unambiguous and correctly named.
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_label or delete_label. There is no mention of prerequisites, intended use cases, or exclusions, leaving the agent without context for tool selection.
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 return value ('Created Project object') and explains parameters like archive_in and close_in, implying auto-archive/close behavior. However, it omits permission requirements, uniqueness constraints, and the workspace_slug discrepancy with the schema, making it adequate but not comprehensive.
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 front-loaded with 'Create a new project' and uses a consistent, scannable list format for parameters and return value. Every line is purposeful, though the workspace_slug inconsistency is a structural flaw.
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 high parameter count (19) and zero schema descriptions, the description effectively defines each parameter and the return object. It lacks broader context like workspace identification or permissions, but for a create operation with no annotations, it provides sufficient semantic coverage.
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 compensates for 0% schema coverage by defining each parameter in plain language, adding value with examples like identifier: 'MP' for 'My Project' and meanings like archive_in: 'Days until auto-archive'. However, it lists 'workspace_slug' which is not in the input schema, creating a potential mismatch that could mislead invocation. Some descriptions are tautological ('name: Project name') but overall coverage is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new project' with a specific verb and resource. This distinguishes it from sibling tools like list_projects, update_project, and delete_project.
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 use for creating a project, and sibling names like update_project and delete_project clarify the alternatives. However, it does not explicitly state when not to use it or provide direct 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?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only says 'Delete' without mentioning permanence, cascading effects, permission requirements, or error handling. For a destructive operation, this is a notable gap.
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, with a clear primary sentence and a single-line argument explanation. Every word is purposeful, no filler or 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 single-parameter delete tool, the description gives the essential purpose and parameter meaning. However, it lacks contextual detail about consequences (e.g., whether the deletion is permanent or cascades to related items) which is important for a destructive action. Notable gaps given no annotations or 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 description adds crucial meaning beyond the raw schema by stating the parameter is a 'UUID of the relation definition to delete'. Since the schema provides no description, this supplementary information explains the parameter's purpose and format, effectively compensating 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 action ('Delete') and the resource ('workspace relation definition'). It distinguishes itself from related sibling tools like 'delete_work_item_link' and 'create_work_item_relation_definition' by explicitly naming the resource type.
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 a clear context: deleting a workspace relation definition. It implies the tool's specific use case without explicitly stating alternatives, but the name and sibling list make it evident. There is no exclusion like 'use delete_work_item_link for links', but the context is unambiguous enough.
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 present, the description carries the full burden of behavioral disclosure. It does mention the return type (Updated Initiative object) and a specific error condition (feature disabled), which adds transparency. However, it omits important behavioral details such as whether this is a partial update (unspecified fields left unchanged), required permissions, or any side effects beyond the update. The description provides some context but not complete transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Description, Args, Returns, Raises) and each parameter gets a single concise line. It is front-loaded with the main purpose, then lists parameters efficiently. There is no fluff or redundant repetition; every sentence 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?
The description covers purpose, all parameters, return type, and a notable error condition. Since an output schema exists, detailed return formatting is not required. The main gap is the lack of explicit statement about partial-update semantics (whether omitted optional fields are ignored or set to null) and any prerequisites like permissions. Given the tool has 8 parameters and no annotations, this omission prevents a perfect score but overall it is quite 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 for the schema's lack of parameter documentation. It provides a one-line explanation for each of the 8 parameters, including format hints (ISO 8601 for dates, UUID for IDs and lead, HTML for description_html) and an explicit list of valid state values. This is essential value that the schema does not provide, and it fully covers all 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 states 'Update an initiative by ID' which is a specific verb ('Update') and resource ('initiative'), clearly distinguishing it from sibling update tools for projects, work items, cycles, etc. The purpose is unambiguous and immediately understood.
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 like update_work_item or update_project. The Raises note about the initiatives feature being disabled is more of an error condition than usage context. It does not state when not to use the tool or mention alternative tools for similar tasks.
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 behavioral disclosure. It states that the tool updates a work log and returns an Updated WorkItemWorkLog object, which adds value. However, it lacks detail on side effects, such as what happens if optional fields are omitted, permission requirements, or error 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 concise and well-structured. It begins with a one-line purpose, then lists parameters with brief explanations, and ends with the return type. There is no unnecessary detail or repetition.
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 primary action, all parameters, and the return value, making it reasonably complete for an update tool. However, it lacks usage guidelines and deeper behavioral context (e.g., partial update semantics), which prevents a perfect score. The output schema exists, so the description need not detail the return fields.
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 no parameter descriptions (coverage 0%), but the description's Args section compensates fully. It explains each parameter's meaning (e.g., 'UUID of the project', 'Duration of work in minutes') and provides type context that the schema's generic string/integer types do not convey. This gives agents a clear understanding of what to pass.
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: 'Update a work log for a work item.' This uses a specific verb and resource, and it distinguishes from sibling tools like 'create_work_log' and 'delete_work_log' by naming the update action.
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 'create_work_log' or 'delete_work_log'. There are no prerequisites, no mention of when to update, and no exclusions. The description only states what the tool does, not when it should be chosen.
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 purpose and returns but does not disclose whether updates are partial or full, what the null default means, permission requirements, or side effects. For a mutation tool with no safety annotations, this is a significant transparency gap.
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 front-loaded with a clear purpose sentence, followed by a simple list of parameters and a return description. No extraneous content; every line serves a functional 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 and presence of an output schema, the description covers the core purpose and parameters. However, it omits critical details about partial updates and the implication of null defaults, which are essential for correct invocation of a multi-option update tool. Lacks guidance on how the 'current workspace' is determined or whether features have dependencies.
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, but the description explicitly explains all six parameters as 'Enable/disable ... feature', adding meaning beyond the schema's bare boolean/null types. However, it does not clarify that null means 'leave unchanged' or that only provided parameters are updated, which would push it to a 5.
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 ('Update features of the current workspace') and specifies the resource as 'workspace features' in the tool name. It lists the exact feature toggles, distinguishing it from the sibling 'update_project_features' by the 'current workspace' 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 by targeting 'current workspace', but it does not explicitly mention alternatives or when not to use this tool despite having a sibling 'update_project_features'. No exclusions are stated, so it falls short of a 5 but earns a 4 for clear implied scope.
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 available, the description carries the full burden. It explains core behavior like directionality via relation_definition_label and the creation of relation entries, but it does not disclose potential side effects, idempotency, or failure modes. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with intro, prerequisite, branching instructions, and an Args list. It is slightly long but each sentence serves a purpose, making it appropriate for the tool's 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?
The description covers all parameters, return type, and the critical prerequisite of calling list_work_item_relation_definitions. While it does not mention error conditions or edge cases, the presence of an output schema and the explicit conditioning make it sufficiently complete for this complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section fully explains every parameter, including the conditional logic for relation_type vs relation_definition_id and the role of relation_definition_label. This compensates completely 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Relate') and clearly identifies the resource ('a work item') and targets. It distinguishes itself from sibling tools like create_work_item_link by referencing relation definitions and directionality, though it does not explicitly name that alternative.
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 explicit usage guidance: 'Always call list_work_item_relation_definitions first' and details how to handle built-in vs custom relation definitions. It lacks an explicit 'when not to use' or named alternatives, but the prerequisite and branching logic offer clear context.
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?
The description discloses the key side effect of unlinking work items, which adds behavioral context beyond the schema. However, it does not mention irreversibility, permissions, failure conditions, or the scope of unlinking in detail. Since annotations are absent, the description carries the burden and provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the core action, and includes a clear Args section. Every sentence earns its place with no unnecessary verbiage.
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 and two parameters, the description covers the primary action, the side effect, and parameter meanings. It does not address error cases or prerequisites, but the tool's low complexity makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining that both parameters are UUIDs and specifying their roles: customer_id identifies the customer, request_id identifies the customer request. This adds meaning beyond the bare schema even though it does not dive into relationships or validation.
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 a customer request') and the resource being affected, plus the side effect of unlinking work items. This is specific and distinguishes it from sibling tools like delete_customer or delete_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?
The usage is implied by the tool's name and description, but there is no explicit guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. It is clear that this tool is for deleting customer requests, but no alternative is named.
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 explains scope resolution but omits critical destructive traits: whether deletion is permanent, if it cascades to values or options, or if special permissions are required. A delete tool needs to state such consequences, and this description is too sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a one-line summary followed by a compact Args list. Every sentence provides necessary information, and the scoping instructions are concise. No fluff or repetition.
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's parameters and scope logic are well-covered, satisfying the core complexity. However, for a destructive delete operation with no output schema, the description should indicate what response to expect (e.g., success/failure) or whether the deletion is irreversible. This absence leaves the agent guessing about the operation's outcome, making completeness partial.
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 no per-parameter descriptions (0% coverage), but the description compensates fully. Each parameter is explained with type (UUID) and scoping rules (e.g., 'Omit for workspace scope'). The conditional guidance for project_id and work_item_type_id adds semantic depth beyond the schema, making parameter usage clear.
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 'Delete a work item property by ID,' clearly stating the verb, resource, and identification method. This distinguishes it from sibling tools like delete_work_item_property_option and delete_work_item_property_value, which target different resource 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 scoping guidance by explaining when to omit project_id (workspace scope) and work_item_type_id (project-level endpoint), giving the agent clear conditional usage context. However, it does not explicitly compare alternatives or state when not to use this tool, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the return includes the active estimate system and its fields (id, name, type), and notes the ID's cross-tool relevance. However, it omits edge-case behavior such as what happens when no estimate exists or if the project is invalid.
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, front-loaded with the primary purpose, and well-structured with explicit Args and Returns sections. Every sentence adds value, and the formatting aids quick parsing.
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 read-only tool with one parameter and an output schema, the description is mostly complete: it covers purpose, return fields, and cross-tool usage. It lacks explicit error/edge-case handling, but given the low complexity and available output schema, the missing details are not critical.
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 documents project_id as 'UUID of the project,' adding type specificity beyond the schema's generic 'string'. Yet it provides no example or additional context about where to find the ID, so it only partially bridges the coverage 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 states precisely that the tool retrieves the estimate configuration for a project, using the specific verb-resource pair 'Get' + 'estimate configuration'. It further clarifies that it returns the active estimate system and its ID, distinguishing it from sibling tools like list_project_estimate_points or get_project_worklog_summary.
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 that the returned ID is required to call list_project_estimate_points, implying a specific use case. However, it does not explicitly name alternatives or provide when-not-to-use guidance, but the purpose is distinct enough.
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 states the return type ('List of WorkItemActivity objects') and the optional 'params' dictionary, but does not mention pagination, permissions, or any side effects. For a read-only list operation, this is acceptable but not richly detailed.
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 compact docstring with clearly labeled Args and Returns sections. Every sentence adds value and there is no fluff or redundant 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 simple list tool with an output schema, the description covers purpose, parameters, and return type adequately. It lacks explicit usage guidance and deeper parameter details, but the presence of the output schema reduces the need to explain return structures in depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter: 'UUID of the project', 'UUID of the work item', and 'Optional query parameters as a dictionary'. This adds real meaning beyond the schema's bare 'string' and 'object' types, though it could specify allowed query parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List activities for a work item' with a specific verb and resource. It distinguishes itself from the sibling 'retrieve_work_item_activity' by indicating a list operation rather than a single retrieval.
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 description and tool name: if a list of activities for a work item is needed, this tool is appropriate. However, there is no explicit guidance on when to use this vs. alternatives like 'retrieve_work_item_activity', nor any exclusions or prerequisites 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?
Without annotations, the description carries the burden of behavioral disclosure. It states that the tool returns metadata and lists the fields, which is helpful. However, it does not disclose potential pagination, ordering, error conditions, or required permissions. It is adequate but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose. The Args and Returns sections are logically structured and contain no redundant information. Every sentence serves a purpose, making it highly 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?
For a straightforward list operation, the description is largely complete. It specifies the return fields and points to the download tool for further action. Since an output schema exists, return value details are covered elsewhere. It could mention pagination or scaling behavior, but that is not critical for basic usage.
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 explains project_id and work_item_id as UUIDs and clarifies which project and work item they refer to. This adds a bit beyond the raw schema, but the explanations are terse and mostly restate the parameter names. It does not explain how to find these IDs or any relationships.
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 lists all attachments for a work item, using a specific verb and resource. It also differentiates itself from the sibling tool get_work_item_attachment_download_url by explicitly pointing to that tool for downloadable links, avoiding confusion.
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 list attachment metadata) and explicitly directs users to get_work_item_attachment_download_url for download links. It does not mention other alternatives like read_work_item_attachment, but the main alternative is covered, making usage guidance strong though not exhaustive.
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 exist, so the description must fully disclose behavior. It only states the basic add/remove action and the parameter constraint. It omits important behavioral details such as error handling, idempotency, behavior when overlapping add/remove IDs are supplied, permissions, or whether the operation is atomic beyond 'in a single call.'
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 short and front-loaded with the primary action. The Args list is cleanly structured, and every sentence 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 4-parameter mutation tool with no annotations and no output schema, the description covers the operation, the prerequisite constraint, and all parameter meanings. It lacks return value details and error scenarios, but is otherwise sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no parameter descriptions, but the Args section explains each parameter with UUID semantics and clarifies the relationship between add_ids and remove_ids via the 'at least one' constraint. This adds meaningful value, though it doesn't address edge cases like empty arrays.
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 'Add or remove work items on a milestone in a single call.' This uses a specific verb+resource combination and uniquely identifies the tool's function, distinguishing it from siblings like list_milestone_work_items and manage_cycle_work_items.
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?
Clear context is given: the tool is for adding/removing work items on a milestone, and the 'At least one of add_ids or remove_ids must be provided' rule guides usage. However, it does not explicitly mention alternatives or exclusions (e.g., when to use list_milestone_work_items).
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 convey the tool's behavior. It states that it returns a Milestone object, which implies a read-only operation, but it does not disclose error behavior (e.g., 404 if not found) or any permissions required. The behavioral disclosure is minimal but sufficient for a simple retrieval where the outcome is predictable.
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 compact, with a one-line summary and clearly separated Args/Returns sections. Every sentence contributes information without redundancy, making it easy 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 straightforward retrieve-by-ID operation with an output schema present, the description fully explains the required inputs and the return type. It doesn't need to elaborate on behavior beyond the return value, although mentioning not-found errors could add robustness.
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 only string types with no descriptions (0% coverage), so the description's Args section adds critical meaning by labeling project_id as 'UUID of the project' and milestone_id as 'UUID of the milestone.' This clarifies the format and reference, compensating for the schema's lack of 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 opens with 'Retrieve a milestone by ID,' a specific verb+resource combination that clearly identifies the tool's function. This distinguishes it from sibling tools like list_milestones (which lists all) and create/update/delete 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?
The phrase 'by ID' implies this tool is for fetching a single milestone when both project_id and milestone_id are known, but it does not explicitly state when to prefer it over list_milestones or provide exclusions. No alternative tools are named, so the usage context is only implied rather than explicitly contrasted.
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 transparency burden. It discloses the return shape (Role with name, slug, namespace) but does not address error cases, permissions, or lack of side effects. This is adequate for a simple read operation but not richly 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 concise: one operative sentence followed by well-structured Args/Returns. No fluff, and it leads with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with a single parameter and an output schema, the description is complete: it covers the purpose, the parameter, and the return shape. No additional context is needed.
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 description explains that role_id is a UUID of the role, adding meaning beyond the schema's bare string type. With only one parameter and 0% schema description coverage, this fully compensates for the missing schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve a role definition by ID,' providing a specific verb and resource. This clearly distinguishes it from list_roles and other retrieve tools by indicating that it fetches a single role by its identifier.
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 list_roles or other alternatives. The only implied requirement is having a role_id, but no exclusions or alternative suggestions 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 burden. It states that a WorkItemComment object is returned, which is useful, but does not explicitly mention that the operation is read-only, or describe error behavior such as 404 when the comment does not exist. The verb 'retrieve' implies non-mutation, but minimal disclosure beyond that.
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 appropriately small and front-loaded. The first sentence states the purpose, followed by concise Args and Returns sections. No filler or redundant information. Every sentence 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?
Given the tool's simplicity (3 required parameters, no nested objects, no annotations, and presence of an output schema), the description covers the essential information. It specifies the input parameters and the return type. It does not address potential errors or edge cases, but for a simple retrieval tool, this is largely 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 input schema provides only parameter names and types without descriptions (0% coverage). The description compensates by listing each parameter with a brief definition: 'UUID of the project', 'UUID of the work item', 'UUID of the comment'. This adds meaning beyond the schema, though it does not provide details on how to obtain these UUIDs.
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: 'Retrieve a specific comment for a work item.' This is a specific verb+resource combination that distinguishes it from siblings like list_work_item_comments (which lists) and create/update/delete comment tools. 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?
No explicit guidance is given on when to use this tool versus alternatives. The name and description imply it for retrieving a single comment by IDs, but there is no mention of list_work_item_comments as the alternative for fetching multiple comments. Usage is implied, not explicitly stated.
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 behavioral burden. It discloses that the tool mutates an estimate point and gives a value length constraint, but it does not explain whether omitted fields are left unchanged or cleared, what permissions are required, or what errors may occur. Some behavioral context is present, but significant gaps remain.
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 tight docstring with a one-line summary followed by a labeled Args list and a Returns line. Every line is informative and the structure is easy to parse. No unnecessary words or repetition, making it an efficient tool description.
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 description covers all parameters and the return value, and an output schema exists. However, given no annotations and 8 parameters, it lacks explicit update semantics (e.g., partial vs full replacement behavior) and any usage guidance relative to sibling tools. The description is adequate for basic use but leaves notable gaps for full contextual understanding.
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%, and the description fully compensates by explaining all 8 parameters. It adds meaningful detail beyond the raw schema, such as clarifying that project_id/estimate_id/estimate_point_id are UUIDs, that value is a display string with max 20 chars and examples ('XL', '13'), and that key is an integer sort key. This turns raw property names into actionable 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 opens with 'Update a single estimate point', which is a specific verb+resource statement. It clearly distinguishes this from sibling tools like create_project_estimate_points and delete_project_estimate_point, as well as from update_project_estimate which targets the estimate rather than the point.
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 verb 'update' and the singular 'estimate point' resource, but the description does not explicitly compare to alternatives such as create or delete estimate points, nor does it state when to prefer this over update_project_estimate. It provides no when-to-use or when-not-to-use guidance beyond the basic purpose.
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 transparency burden. It discloses that last_used defaults to True and affects whether the estimate becomes active, and it states the return type. However, it does not mention side effects on existing estimates, permission requirements, 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 uses a clear Args/Returns structure with one parameter per line, including contextual examples. It is concise—no filler sentences—and every line adds value by explaining a parameter or the return 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?
All parameters and the return value are covered, and the output schema handles return details. The description lacks domain context about what an 'estimate' is in this system and the implications of setting last_used, but it is otherwise complete for a create operation with a well-defined schema.
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%, but the Args block explains all 7 parameters with examples, type values, and defaults. For instance, type is described as 'categories', 'points', or 'time', and name includes examples like 'Story Points'. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Create a new estimate for a project,' which is a specific verb+resource combination. It clearly distinguishes this from sibling tools like update_project_estimate, get_project_estimate, and delete_project_estimate by focusing on creation.
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 is implied by the verb 'Create' and the resource 'estimate.' No explicit alternatives or exclusions are provided, such as when to use link_estimate_to_project instead. It's clear but lacks guidance on choosing between related 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 burden. It mentions scope behavior (workspace vs project) and returns the created object, but does not disclose permissions, idempotency, or consequences of duplicate creation. It's adequate but not rich in behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose line, an Args list with one-line explanations, and a Returns line. No unnecessary words; every element 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?
With an output schema present, return value details are covered, and all parameters are described. The description lacks some broader context (e.g., uniqueness constraints on name, relationship to existing options), but is complete enough 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?
Schema description coverage is 0%, but the description lists all 8 parameters with meaningful explanations, including UUID types, an example hex color, and scope guidance for project_id. This fully compensates for the lack of schema documentation.
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 an option on a work item property' with a specific verb and resource. It distinguishes from sibling tools like update/delete/list/retrieve work_item_property_option, and from create_work_item_property.
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 vs alternatives' guidance is given. However, the parameter note 'project_id: UUID of the project. Omit for workspace scope' provides some usage context. The tool's purpose implies when to use it, but alternatives are not 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Delete an attachment from a work item,' which repeats the name and implies destruction but does not mention permanence, required permissions, side effects, or error behavior. For a destructive action, more transparency is expected.
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 efficient: one purpose sentence, one practical hint, and a clean Args list. No redundant information or filler. The structure makes it easy to scan and extract key instructions.
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 operation with three required parameters and no output schema, the description is sufficient: it identifies the exact action, all parameters, and how to get the attachment_id. It lacks any mention of return values or irreversibility, but these are not critical for invoking the tool correctly, given the simplicity and the purpose statement.
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 has 0% description coverage, but the description's Args section explicitly explains each parameter: project_id as UUID of the project, work_item_id as UUID of the work item, and attachment_id as UUID of the attachment to delete. It also provides the crucial tip to use list_work_item_attachments to fetch the attachment_id, fully compensating for the schema's lack of 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 opens with 'Delete an attachment from a work item,' which clearly states the action and resource. It distinguishes itself from sibling tools by naming the exact delete operation, and the only other attachment-related tools are read/list/download/upload, leaving no ambiguity about the intent.
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 specifying the action and adding a practical prerequisite: 'Use list_work_item_attachments to get the attachment_id.' This tells the agent how to obtain a required ID, which is helpful usage guidance. However, it doesn't explicitly state when not to use this tool or name alternatives, so it misses the full 'when vs when-not' 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?
No annotations are provided, so the description carries the burden. 'Get' implies read-only and the return type 'UserLite' is disclosed, but no authentication context or side effects (likely none) are mentioned. Minimal but adequate for a simple zero-parameter read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, one for the action and one for the return type. Every word earns its place; no fluff or repetition.
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 tool with an output schema, the description is complete. It states the action, the target ('current user'), and the return type ('UserLite'), which is sufficient for an agent to select and invoke it.
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?
There are zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get current user information'. This clearly distinguishes it from sibling tools like get_workspace_members or get_features, and the scope 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 implies usage when the current user's information is needed, but gives no explicit 'when to use' or alternatives. However, there are no overlapping sibling tools, so the purpose is self-evident.
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 states the outcome (types become available in the project) and the input constraint (workspace-level types), but omits critical details like idempotency (what happens if a type is already linked), error handling, return values, or required permissions. For a mutating operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary sentence, a clarifying elaboration, usage guidance, and a clean Args list. Every sentence earns its place, and no filler or redundant information is present.
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 description covers the core purpose, parameters, and an alternative tool, making it usable for selection and invocation. However, without annotations or an output schema, it should ideally disclose behavioral aspects such as whether re-importing is harmless, how failures are reported, and what the operation returns. These omissions leave it at a minimum viable 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?
The schema provides no descriptions (0% coverage), but the Args section adds meaning by defining project_id as 'UUID of the project' and work_item_type_ids as 'List of workspace-level work item type UUIDs.' This effectively compensates for the schema's lack of detail, though it could be slightly more explicit about the semantics of the list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Bulk-link workspace-level work item types to a project') and elaborates that it imports them so they become available for use. It distinguishes itself from the sibling resolve_work_item_type by noting that a single named type is better handled there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends resolve_work_item_type for the common case of getting one named type usable in a project, providing a clear alternative. The 'bulk-link' phrasing and workspace-level IDs imply this tool is for multiple types or already-known IDs, giving practical context.
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 discloses a notable behavior: 'Returns all of them, unpaginated,' which is a key performance/usage trait. It also explains the filtering behavior of the parameters. However, it does not mention error handling, authentication requirements, or confirm that it is a read-only operation (though 'List' implies it).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a one-sentence summary, followed by an Args section and a Returns line. There is no wasted text. Each sentence serves a purpose, and the structure is easy to parse.
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 that an output schema exists, the description does not need to elaborate on return structure. It covers the main aspects: what it lists, the parameters, and the unpaginated behavior. It lacks explicit guidance on when to choose this tool over similar list/search tools, which is a minor gap, but for a simple listing tool with explained parameters, it is fairly 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?
The input schema has 0% description coverage, so the description must compensate. It fully explains all three parameters: customer_id ('UUID of the customer'), customer_request_id ('Only work items linked through this request of the customer'), and search ('Filter by work item name, sequence ID, or project identifier'). This adds significant meaning beyond the bare schema types.
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: 'List the work items linked to a customer.' It uses a specific verb ('List') and resource ('work items linked to a customer'), and adds the scoping detail 'linked to a customer' to distinguish from generic list_work_items. It also mentions 'unpaginated' to set expectations, which further clarifies its unique 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 gives clear context about what the tool does and what filters are available, but it does not explicitly state when to use this tool versus alternatives like list_work_items or search_work_items. There is no 'when not to use' or mention of alternative tools, so the guidance is only implied.
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 full burden. It discloses the return format ('Paginated envelope with results, total_count, next_cursor, prev_cursor') and optional filtering, which is useful. However, it does not explicitly state that this is a read-only operation or mention any side effects, rate limits, or required permissions, leaving some ambiguity for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with 'Args' and 'Returns' sections, making it easy to scan. Every line provides functional information and there is no filler. Though slightly long, the density is appropriate for a tool with 8 parameters and pagination 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?
Given the complexity of 8 parameters, pagination, and optional PQL filtering, the description covers all parameters and clearly states the return envelope. The presence of an output schema and the reference to get_pql_reference for complex queries adds completeness. It lacks only explicit edge-case guidance, but overall it is sufficient for safe 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 only 13%, but the description compensates by describing all 8 parameters in the Args section, including types, defaults, and formatting rules (e.g., order_by prefix `-` for descending, per_page range 1-100, cursor from next_cursor). While expand and fields are somewhat vague ('related fields', 'sparse fieldset'), the extra context significantly aids 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 starts with 'List work items in a cycle with optional PQL filtering,' which names the specific verb, resource, and scope. The tool name and description clearly distinguish it from siblings like list_work_items and list_module_work_items by explicitly scoping to a cycle.
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 this to list work items within a specific cycle, with optional PQL filtering, and 'Omit to list all items in the cycle' clarifies the default behavior. It doesn't explicitly discuss alternatives, but the scope is unambiguous enough for an agent to decide when to use it, especially given the params require project_id and cycle_id.
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 explains the project vs. workspace scoping and mentions pagination parameters (per_page, cursor), which is useful. However, it does not explicitly state read-only behavior, auth requirements, or potential error conditions, though 'list' implies 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear opening statement, Args section, and Returns section. It is not overly verbose, but the opening sentence is slightly redundant with the second sentence, which could be merged for even tighter prose.
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 (list with optional project scope), the description is fairly complete. It covers both parameters, returns description, and distinguishes project vs. workspace behavior. With an output schema present, it does not need to detail Page object fields. Minor gaps like error cases or alternative tools are not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description compensates well. It explains that project_id scopes to project pages or workspace pages when omitted, and describes params as an optional dictionary with examples (per_page, cursor). It adds meaning beyond the raw schema, though it could enumerate more possible query 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 lists pages and differentiates between project-level and workspace-level pages based on presence of project_id. This is a specific verb+resource with clear scope, distinguishing it from siblings like list_work_item_pages.
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 context on when to use the tool (list pages with optional project scope) and explicitly describes the conditional behavior. However, it does not mention alternatives for listing pages attached to work items, such as list_work_item_pages, so there are no exclusions but no explicit alternative guidance.
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 states the operation (link/unlink) and returns the resulting linked projects, but it does not mention error handling, idempotency, what happens if some project_ids are invalid, or whether the operation is atomic. The reversible nature is implied via 'remove' but not fully 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?
The description is brief, front-loaded with the core purpose, and structured into Args and Returns. Every sentence adds value without redundancy, making it easy to parse.
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 presence of an output schema, the description covers the essential information: purpose, parameters, and return value. It could include edge-case behavior, but for a link/unlink operation, it is largely sufficient. The one clear alternative is mentioned, providing good contextual guidance.
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 input schema has 0% description coverage, but the description compensates fully by explaining each parameter: initiative_id as UUID, action with 'add' and 'remove' semantics, and project_ids as project UUIDs. It also clarifies the return value, which adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Link or unlink projects of an initiative' which is a specific verb+resource statement. It clearly differentiates from sibling tools like 'list_initiative_projects' by noting that the latter is for reading, 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?
The description explicitly directs users to 'Use list_initiative_projects to read' when they need read access, providing a clear alternative. It does not cover broader when-not scenarios, but for the primary distinction between reading and modifying, it 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, the description carries the transparency burden. The verb 'Retrieve' implies a read-only operation, and the 'Omit for workspace scope' note adds behavioral nuance. It also states the return type. Still, it does not disclose error behavior, permission requirements, or explicitly confirm non-mutation, which are useful for a tool with no annotation safety hints.
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 compact, front-loaded with the main action, and structured with clear Args and Returns sections. Every line contributes meaningful information without redundancy 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 retrieval operation, and the description covers its purpose, all parameters, and the return object. The presence of an output schema reduces the need to detail return fields. However, it omits any mention of error cases (e.g., not found, invalid IDs) or prerequisites, keeping it from being fully 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?
The input schema only provides generic string types with 0% schema coverage, but the description fully compensates by defining property_id as the UUID of the work item property, option_id as the UUID of the option, and project_id with the workspace-scope distinction. This is exactly the semantic richness 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 opens with 'Retrieve a single option from a work item property,' using a specific verb and clear resource. It distinguishes itself from siblings like list_work_item_property_options, retrieve_work_item_property, and get_work_item_property_value by indicating it fetches exactly one property option, not a list or a property value.
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 context from 'single option' versus the sibling list tool, and the 'Omit for workspace scope' note explains a key variant. However, it does not explicitly state when to use this tool over alternatives or provide any exclusion criteria, so guidance is only implied.
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 must convey safety and mutation context. It states that a page is created and returns a Page object, but does not disclose permissions, side effects, or error conditions. This is adequate for a straightforward create operation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured with a one-sentence summary, an Args list, and a Returns section. Every sentence adds value, with no redundant content. It is easy to scan and digest.
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 11 parameters and no annotations, the description covers all parameters and states the return object, making it reasonably complete. It also clarifies the critical scoping decision. Minor gaps exist around allowed integer values for access, color format, and internal structure of dictionary parameters like view_props, but these are not critical for basic 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?
With schema_description_coverage at 0%, the description's Args section is the sole parameter documentation. It provides meaningful semantics for all 11 parameters, including the key behavior of project_id ('Omit to create a workspace page'), format hints for archived_at (ISO 8601) and description_html (HTML), and type for access (integer). Some descriptions are tautological (e.g., 'Page name'), but overall it compensates well for the missing schema documentation.
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 'Create a page.' and immediately clarifies the two scope variants (project page vs workspace-level page) based on project_id. This is a specific verb+resource with clear differentiation from sibling tools, none of which create pages.
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 on when to use the tool: creating a page, with explicit guidance on using project_id for project pages or omitting it for workspace pages. It does not explicitly exclude alternatives, but no sibling tool offers page creation, so this 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, the description carries full burden. It properly states this is a create operation and notes the 'name' is unique, but it does not disclose potential error conditions (e.g., duplicate name), permissions required, or reversibility. However, as a create-only operation, the primary behavior is clear.
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 organized with a clear opening statement, a brief concept explanation, and bullet-like Args/Returns sections. It is slightly verbose but each part adds value, especially the conceptual clarification of relation definitions.
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 (5 parameters, no schema descriptions), the description covers purpose, all parameters, and the return type. It lacks some usage prerequisites and error scenarios, but is largely complete for a straightforward create operation, especially since an output schema exists.
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 Args section in the description provides meaningful explanations for all 5 parameters. It clarifies 'outward' and 'inward' from source/target perspectives, defines 'is_active', and specifies 'color' as a hex code. This fully compensates for the schema lacking 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 first sentence clearly states 'Create a new workspace relation definition' with a specific verb and resource. It distinguishes itself from sibling tools like update_work_item_relation_definition, delete_work_item_relation_definition, and list_work_item_relation_definitions by describing the concept of a relation definition with outward and inward labels.
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 about what a relation definition is and what it does, which implicitly guides when to use this tool. It does not explicitly mention alternatives or when not to use, but the conceptual explanation and parameter descriptions help differentiate it from other relation-related tools like create_work_item_relation.
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 exist, so the description carries the full burden. It usefully discloses that multi-value properties will have ALL values deleted, which is a non-obvious behavioral trait beyond what the tool name suggests. However, it does not address reversibility, permissions, or what happens when no value exists, leaving some 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?
Two sentences plus a three-line args list. The purpose is front-loaded, the multi-value edge case is a single sentence, and the parameter documentation is compact. No 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?
Three simple params, no annotations, and no output schema. The description covers purpose, the multi-value behavior, and all parameter roles, which is adequate for a straightforward deletion tool. It does not describe success/failure responses, but given the tool's simplicity, this is a minor gap.
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%, and the description compensates by listing each argument with a clarifying role ('UUID of the project,' 'UUID of the work item,' 'UUID of the work item property'). This adds meaning beyond the bare string type in the schema, though it mostly expands on what the parameter names already suggest.
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 ('Delete') with a clear resource ('the value(s) of a custom property on a work item'), and correctly distinguishes itself from sibling tools like delete_work_item_property (which removes the property definition itself) and set_work_item_property_value (which sets values). The multi-value clarification further sharpens the 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?
The description implies when to use the tool (to remove property values from a work item) but provides no explicit guidance on when NOT to use it or which alternative to choose. With many sibling tools like set_work_item_property_value, delete_work_item_property, and get_work_item_property_value, explicit differentiation would be valuable.
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 of behavioral disclosure. It adds useful context by explaining the return behavior (single item vs. list for multi-value properties) and clarifying it applies to custom properties. However, it does not address error cases, permissions, or confirm the operation is read-only beyond the implied 'get' semantics.
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 tightly structured docstring: a purpose sentence, a cross-reference, an Args list, and a Returns list. Every line serves a purpose with no filler, making it highly scannable and 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?
For a simple read tool with three UUID parameters and an output schema present, the description covers the essential prerequisite (property_id lookup) and the dual return shape. It could be more complete by addressing edge cases or explicitly contrasting with retrieving the entire work item, but overall it is sufficient for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only string type names with 0% description coverage. The description's Args section compensates by labeling each parameter as a UUID and its role (project, work item, property), and it hints that property_id comes from list_work_item_properties. This adds meaningful semantic context 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?
Description uses a specific verb ('Get') and resource ('value(s) of a custom property on a work item'), making its purpose unmistakable. It clearly distinguishes from siblings like list_work_item_properties (which lists property definitions) and set_work_item_property_value (which writes values). The inclusion of return shape variance reinforces the tool's 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 explicitly instructs to use list_work_item_properties to find the property_id, establishing a clear prerequisite and usage context. However, it does not contrast with alternative value-manipulation tools (e.g., set_work_item_property_value) or state when not to use it, so it lacks explicit 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?
With no annotations, the description carries the burden. It discloses that the tool returns a list of Project objects and that it accepts optional pagination params, giving useful context. However, it does not mention any side effects, authorization requirements, or edge cases (e.g., behavior for invalid initiative_id, whether linkage is direct or recursive). The read-only nature is implied by 'List,' but not explicitly stated.
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 compact and well-structured with an Args/Returns format. Every sentence adds value, no fluff or repetition. It directly conveys the core behavior and parameters in a digestible manner.
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 simple, and the description covers the essential aspects: purpose, required and optional parameters, and return type. Given the output schema exists, further detail on return values is unnecessary. The description is sufficient for an agent to invoke the tool correctly, though it could mention behaviors like pagination defaults or error conditions for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It describes initiative_id as 'UUID of the initiative' and params as 'Optional query parameters (e.g., per_page, cursor)', adding concrete meaning beyond the raw schema types. This is helpful for an agent to know what to pass.
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: 'List projects linked to an initiative.' The verb 'List' and the specific resource 'projects linked to an initiative' distinguish it from sibling tools like list_projects (which lists all projects) and list_initiatives (which lists initiatives).
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 the context of use: when you have an initiative_id and want its associated projects. It doesn't explicitly mention alternatives or exclusions, but the specificity provides enough guidance. Sibling tools like manage_initiative_projects suggest related operations, but no further direction is 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 of behavioral disclosure. It adds valuable context about the output id's role in subsequent property lookups and clarifies workspace-level vs. project-level behavior. While it does not explicitly state read-only or pagination behavior, 'List' inherently implies a read operation, and the relational context provided exceeds minimal expectations.
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 every sentence adds value. The first sentence establishes the operation and scope; the second provides critical downstream integration details. There is 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 simple list operation with an output schema, the description covers the essential usage and integration context. The main gap is the unexplained 'params' parameter, but this is a minor issue given the tool's simplicity and the explicit guidance on project_id. Overall, it is complete enough for correct selection and 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 parameter descriptions, so the description must compensate. It does explain 'project_id' ('Omit project_id for workspace-level types'), giving meaningful semantics. However, the 'params' parameter is not mentioned at all, leaving its purpose and format ambiguous. The partial coverage justifies a mid-range score.
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 ('work item types'), and distinguishes this from related tools by explaining the scope ('Omit project_id for workspace-level types') and connecting the output to list_work_item_properties. This makes the tool's purpose unambiguous and differentiates it from create/retrieve/update/delete siblings.
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 concrete usage context: it explains when to include project_id vs. omit it, and states that the returned id is needed by list_work_item_properties for PQL cf[] filters. It implies the tool is a precursor to property lookups. It does not explicitly exclude alternative tools, but the guidance is clear enough for common use cases.
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 state restriction and visibility effect, which is useful, but omits other behavioral aspects such as permissions, reversibility of unarchive, error conditions, or return values. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by conditions and argument details. Every sentence contributes value without 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 toggle operation, it covers the main purpose, prerequisite state, and listing effect. However, with no output schema and no annotations, it lacks details on success/error responses, permission requirements, and any side effects on related items. These gaps make it only minimally 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 explain all parameters. It does so clearly: 'project_id: UUID of the project', 'work_item_id: UUID of the work item', and 'archive: True to archive the work item, False to unarchive it.' This adds essential meaning beyond the raw schema types.
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 'Archive or unarchive a work item' with a specific verb and resource. It distinguishes itself from siblings like 'list_archived_work_items' and 'manage_cycle_archive' by focusing on toggling archive state for a single 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Only work items in a completed or cancelled state can be archived' and explains the consequence 'Archived work items no longer appear in active work item lists.' It lacks explicit alternatives or when-not-to-use, but the conditions for use are clear.
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 a key behavioral nuance: built-in dependencies and custom relations are removed independently, and it clarifies the meaning of is_dependency. However, it does not mention permissions, idempotency, potential side effects, or error behavior, leaving some uncertainty for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an initial summary, a behavioral note, and a clear args list. It is slightly verbose but every sentence adds value, and the formatting makes it easy to scan. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of two relation types and a boolean parameter that changes behavior, the description covers the critical decision points and references list_work_item_relations for prerequisite context. It does not mention return values, but for a removal operation this is less critical, and the description is otherwise complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining each parameter, including the exact meaning of is_dependency (True for built-in dependency, False for custom relation) and the roles of work_item_id and related_work_item_id. This is essential for correct invocation.
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 begins with 'Remove ONE relation between two work items', which is a specific verb and resource. It distinguishes between built-in dependencies and custom relations, and the term 'relation' differentiates it from sibling tools like delete_work_item_link. The scope is clear 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?
The description provides explicit guidance on when to use the tool: it tells the agent to reference list_work_item_relations to determine the correct is_dependency value, and explains when to set True vs False. It does not directly name alternative tools or state when not to use this tool, but the context is sufficient for an agent to select it appropriately.
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. It discloses that the returned CustomerProperty includes options for OPTION type, which is non-obvious and useful. It does not mention error behavior or permissions, but for a simple read operation 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 compact and well-structured with Args and Returns sections. Every sentence provides value 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?
The tool is simple (1 parameter, no nested objects, output schema present). The description covers purpose, parameter, and return behavior including the OPTION type nuance. Minor missing details like not-found handling are acceptable given the output schema and 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 schema only lists property_id as a string with 0% description coverage. The description adds semantic value by explaining 'property_id: UUID of the customer property', clarifying both the type and role beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Retrieve a customer property by ID', specifying the resource and scope. It distinguishes from sibling tools like list_customer_properties (list many) and delete_customer_property (delete).
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 when you have a specific property_id and need details, but it does not explicitly state when to prefer this over alternatives like list_customer_properties, nor does it mention edge cases or exclusions. The guidance is minimal.
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 operation is a retrieve and mentions it returns a State object, which is minimal but sufficient for a simple read. It doesn't disclose error behavior, prerequisites, or any side effects, but for a non-destructive getter this level of transparency is adequate but not outstanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. The Args section is neatly formatted and adds necessary parameter details. Every sentence contributes value, and there is 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?
This is a simple retrieval tool with two parameters, and the description covers the core purpose and parameter meanings. An output schema exists, so the return type doesn't need elaboration. It lacks details on error handling or when not to use, but for its simplicity the information is largely 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 description coverage is 0%, so the description compensates by explaining both parameters: 'UUID of the project' and 'UUID of the state'. This adds meaning beyond the bare type strings in the schema. It doesn't include examples or constraints, but it provides the necessary semantic 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 retrieves a state by ID, using a specific verb and resource. It distinguishes itself from siblings like list_states, create_state, and delete_state by indicating a single-state fetch 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?
It implies when to use the tool: when you have a specific state ID and project ID and want the corresponding state object. It doesn't explicitly name alternatives but clearly implies single-item retrieval, setting it apart from list_states. Since exclusions aren't stated, it falls just 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.
Behavior3/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 transparency burden. It discloses key behavior: partial update semantics ('Only the fields you pass are changed') and the return value (the updated ReleaseTag). However, it does not clarify null-handling behavior (e.g., whether passing null clears a field), error conditions, or potential side effects, leaving some ambiguity for a behavioral safety assessment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose, a clear Args list, and a Returns line. Every sentence contributes value, and the format is easy to scan. No redundancy 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?
For a simple CRUD update tool, the description covers the essential aspects: what it updates, which fields are updatable, and what is returned. Given that an output schema exists, return values do not need further explanation. The only notable gap is the ambiguous handling of null values for optional fields, which could affect usage in partial-update edge cases.
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 does so effectively with an Args section explaining each parameter: tag_id (UUID), version (with example), description (notes), commit_hash (Git commit source), and git_tag (corresponding tag name). This adds semantic meaning beyond the bare schema types, though it could be more explicit about null behavior and valid formats.
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: 'Update a release tag by ID.' It clearly distinguishes this from sibling tools like create_release_tag, retrieve_release_tag, and delete_release_tag by focusing on the update operation. The partial-update clarification ('Only the fields you pass are changed') further sharpens the 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 makes clear this tool is for updating an existing release tag by ID. It implies a partial-update usage pattern, but does not explicitly state when not to use it or contrast with alternatives like update_release. The context is unambiguous enough for a developer to know when to invoke it, but it lacks explicit 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 full burden. It clearly discloses the side effect (sets end_date to today) and provides helpful domain context about how completion works in Plane. It does not mention permissions, reversibility, or idempotency, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a clear opening sentence, a relevant explanatory paragraph, and a tight Args/Returns listing. No wasted words, and every sentence provides necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two simple parameters and an output schema present, the description covers the action, domain context, parameters, and return value. It is complete enough 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.
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 compensates by listing both parameters with type hints and brief purpose (e.g., 'UUID of the project' and 'UUID of the cycle to complete'). This adds meaning beyond the raw schema, though it could be more explicit about the relationship between the two 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's purpose: to complete/close a cycle by setting its end date to today. It also explains the domain-specific mechanism (no explicit 'complete' action; a cycle is complete when end_date is in the past), which distinguishes it from generic update_cycle operations.
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 (to close/complete a cycle) but does not explicitly contrast it with alternatives like update_cycle. It provides useful context but lacks explicit 'when-to-use' or '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?
Description provides the return value and uniqueness constraint, but with no annotations, it does not disclose permissions, failure modes, or side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear and direct summary, then organized Args/Returns sections. Every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter create tool with output schema, the description adequately covers parameter semantics and return type, but could be enhanced with error handling or permission notes given the absence of annotations.
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 has no descriptions (0% coverage), but the description explains each parameter (version, description, commit_hash, git_tag) with practical examples and definitions, fully compensating for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a release tag (version marker)', specifying the action and resource. It distinguishes from sibling tools like create_release and tag management tools by focusing on tag creation.
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 indicates the tool's purpose and includes a constraint (version must be unique), but does not explicitly reference alternatives or when-not-to-use, leaving usage guidance implied.
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. It states the action (delete) and the scope behavior (project_id omitted for workspace), but does not disclose whether deletion is permanent, how errors are handled, or whether special permissions are required. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a terse Args list. It is front-loaded with the core purpose, and every line adds value. There is no padding or repetition of schema types.
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 3-parameter delete tool with no output schema, the description covers the operation and parameter semantics well. It does not mention return values or error handling, but that is arguably less critical for a delete operation. Overall, a competent agent could successfully invoke this tool based on the description alone.
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 has zero descriptions (coverage 0%), so the description is the only source of parameter meaning. It explains each parameter with UUID references and clarifies the optional scope behavior for project_id. This fully compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Delete an option from a work item property.' This clearly distinguishes it from the many sibling delete tools (e.g., delete_work_item_property, delete_work_item_link) and from CRUD operations on entire properties.
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 is contextually clear: it deletes an option from a property. It also provides a concrete usage hint for the optional project_id: 'Omit for workspace scope.' It does not explicitly name alternatives or exclusions, but the purpose is specific enough that ambiguity is low.
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 pagination behavior (cursor semantics, per_page range and default), order_by syntax (prefix '-' for descending), and the return envelope (results, total_count, next_cursor, next_page_results). This adds meaningful behavioral context beyond the bare schema, though it does not discuss permissions or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary followed by clearly labeled Args and Returns sections. Every sentence adds value; no fluff or redundancy. The pagination details are concise yet complete.
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 paginated list tool with three parameters and no annotations, the description is quite complete: it covers purpose, all parameters, and return structure. It omits details like whether archived projects are included or workspace identification relying on context, but these are not critical for basic usage. The output schema may also cover some return details.
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%, but the description fully compensates by explaining each parameter: cursor (prior response's next_cursor, omit for first page), per_page (1-100, default 100), and order_by (sort field, prefix '-' for descending). It also clarifies the return envelope, providing essential semantics for effective use.
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 'List projects in a workspace (paginated)', which clearly states the verb (List), resource (projects), scope (workspace), and a key characteristic (paginated). This unambiguously distinguishes it from siblings like retrieve_project (single project) and create_project.
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 enumerating projects in a workspace, but it does not explicitly contrast with retrieve_project or any other alternative. There is no 'when to use this vs. that' guidance, though the first line makes the primary use case obvious. This is implied usage, not explicit 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, the description carries the full burden. It discloses an important side effect (auto-setting end_date to today) and states the return value, but it does not describe unarchive behavior in detail, error cases, or idempotency. This is partially transparent but has notable 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 concise, front-loaded with the purpose, and structured logically into summary, behavioral note, args, and returns. Every sentence adds value; 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 3-parameter toggle tool, the description covers the core behavior and key side effect. The existence of an output schema means return details need not be repeated. It is reasonably complete but could mention edge cases like unarchive on archived cycles or failure conditions.
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 input schema has 0% description coverage, so the description fully compensates. The Args section explicitly explains each parameter: project_id as UUID of the project, cycle_id as UUID of the cycle, and archive as a boolean with True/False semantics. This adds meaningful meaning beyond the raw 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 opens with 'Archive or unarchive a cycle,' which is a specific verb+resource statement. It clearly distinguishes this tool from sibling archive tools for other entities (e.g., manage_work_item_archive, manage_cycle_archive being cycle-specific).
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: Plane requires the cycle end_date to be in the past before archiving, and the tool auto-sets end_date to today if needed when archive=True. This tells the agent when the tool can be used even for active cycles. However, it does not explicitly mention 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.
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 states the primary effect (add/remove) and the precondition, but omits details like idempotency, failure modes, permission requirements, or what happens if the module/work item does not exist. This is basic mutation disclosure but lacks deeper side-effect 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 well-structured: purpose is front-loaded in a single sentence, followed by a necessary constraint, then an explicit parameter list. Every sentence adds value, and the format makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 4 parameters and no output schema or annotations, the description covers the input semantics and a key rule. It does not describe the return value or error conditions, but given the simplicity of the operation, the description is largely complete for a competent agent.
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 coverage is 0%, but the description compensates fully with an Args list that gives semantic meaning to each parameter (e.g., 'UUID of the project', 'UUIDs of work items to add to the module'). It also adds a critical constraint about the relationship between add_ids and remove_ids, which is beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb (add/remove) and resource (work items on a module), and explicitly notes the 'single call' capability. This distinguishes it from sibling tools like list_module_work_items (read-only) and manage_cycle_work_items (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 provides clear context for when to use the tool (adding/removing work items on a module) and embeds an important usage constraint ('At least one of add_ids or remove_ids must be provided'). However, it does not explicitly mention alternatives or when not to use it, such as comparing with list_module_work_items for reading.
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 operation and its return value ('The release's attached labels after the operation'), but does not disclose potential failure modes, idempotency, or behavior when detaching non-attached labels. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary, a helpful pointer to the read tool, then structured Args and Returns sections. Every sentence contributes valuable information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is largely complete. It covers all parameters, the action semantics, and the return value, while also distinguishing from the read sibling tool. It could be slightly more comprehensive about edge cases, but overall satisfies the needs for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are explicitly described in the description with types and semantics: release_id as UUID, action with enumerated values, and label_ids as UUIDs of palette labels. This fully compensates for the 0% schema description coverage, adding meaning beyond the raw schema fields.
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 'Attach or detach existing palette labels on a release,' a specific verb and resource combination that clearly states the tool's function. It distinguishes itself from siblings like list_release_labels, create_release_label, and delete_release_label by focusing on the attachment/detachment operation on existing labels.
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 directs users to 'Use list_release_labels with release_id to read,' providing an alternative for read operations and implying this tool is for modifications. It clearly explains the two actions (attach/detach), though it doesn't explicitly mention that creating new labels should be done via create_release_label.
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 two important behaviors: removal before addition if both are given, and silent skipping of already-attached labels. But it omits permissions, error handling, and idempotency beyond the stated cases, which is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a front-loaded purpose statement, then operational rules, parameter list, and return value. Every sentence adds value 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 focused label-management tool, the description covers the key behavioral aspects, argument combinations, and return type. It does not discuss edge cases like invalid UUIDs or workspace permissions, but given the simple parameter set and presence of an output schema, it is reasonably 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?
The schema has zero parameter descriptions (0% coverage), so the description's Args section fully compensates by explaining each parameter's purpose and type. It also clarifies the add/remove relationship, exceeding what the schema alone 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 states a specific action: 'Add or remove a single label on a work item without replacing the full list.' This clearly distinguishes it from sibling tools like update_work_item (which likely replaces the entire label list) and label CRUD 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?
It provides clear usage context via 'without replacing the full list' and explains the allowed argument combinations (add_label_id, remove_label_id, or both) and their ordering. However, it does not explicitly name alternative tools for replacing the full list, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It clearly discloses the return type ('Initiative object'), the error condition ('ToolError: if the initiatives feature is disabled'), and explains the disabled-state behavior. This goes beyond a simple retrieve statement, though it does not explicitly state side-effect safety or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear Args, Returns, and Raises sections. The summary line is immediately actionable, and every sentence adds value without redundancy or filler.
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 single-parameter retrieval tool, the description is complete: it states what the tool does, what it returns, and the primary failure mode. Since an output schema exists, the description does not need to elaborate on return fields. The disabled-feature fallback behavior is a valuable contextual addition.
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 and only states the parameter type as 'string.' The description adds meaningful semantics by specifying 'initiative_id: UUID of the initiative,' clarifying the expected format and purpose. This compensates well for the schema's lack of descriptive detail, though it does not mention how to obtain the ID.
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 'Retrieve an initiative by ID,' which is a specific verb and resource. It clearly distinguishes from sibling tools like list_initiatives, create_initiative, update_initiative, and delete_initiative by indicating a single-object retrieval by identifier.
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 Raises section implies when this tool cannot be used (when the initiatives feature is disabled) and suggests the error provides next steps, but it does not explicitly name alternatives like retrieve_work_item or explain when to choose list_initiatives over this tool. Usage context is implied rather than explicitly 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?
Without annotations, the description carries the full burden and does well by disclosing upsert behavior ('creates the value if it does not exist, updates it if it does') and the destructive replacement for multi-value properties. It also details expected value types, but omits permission requirements or error handling, which prevents a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening statement, a behavioral note, a bulleted list of value types, an Args list, and a Returns note. It is appropriately sized for a tool with six parameters and a nuanced value-type mapping, with 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?
Given the tool's complexity (6 parameters, no annotations, 0% schema description coverage), the description covers all essential aspects: purpose, behavior, parameter semantics, and return types. It lacks only secondary context like permission requirements or error conditions, which keeps it from being fully 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 fully compensates. The 'Args' section explains each parameter, and the value type mapping by property type is essential because the schema only lists raw JSON types. This provides crucial semantic detail for correctly formatting 'value' for different property types.
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 'Set (create or update) the value of a custom property on a work item,' clearly identifying the verb and resource. It also differentiates from sibling tools by emphasizing the value-setting action (versus get/delete property value) and clarifying it acts as an upsert.
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 through its upsert explanation and replacement behavior for multi-value properties, but it does not explicitly state when to use this tool versus alternatives like update_work_item_property or set_customer_property_values. There is no explicit when-not or alternative naming, so it falls short of clear 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, the description carries the burden. It discloses the partial-update behavior ('Only the fields you pass are changed') and the return value. However, it does not mention error conditions, preconditions (e.g., label must exist), or permissions, which would be useful 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 compact and well-structured: a one-sentence summary, a bulleted Args list, and a Returns line. There is no redundancy or fluff; every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple four-parameter update with no enums or nested objects, the description covers the essential action, partial-update semantics, and return type. It could elaborate on failure modes, but given the simplicity and existence of an output schema, it is nearly 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 fully compensates by documenting all four parameters: label_id as UUID, name as label name, color as hex example, and sort_order as palette position. This adds meaningful semantics beyond the raw 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 starts with 'Update a release label in the palette,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like create_release_label, delete_release_label, and manage_release_labels.
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 clearly states that only the fields passed are changed, implying partial updates, but it does not explicitly mention when to use this tool versus create_or_delete, nor does it name alternatives. The context is clear enough for an 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the transparency burden. It explains the point dictionary fields and gives an example, but does not disclose important behavioral aspects like whether keys must be unique, whether points are appended or replace existing ones, or what happens on validation failure. This leaves gaps in understanding the tool's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, followed by point specification, an illustrative example, argument documentation, and return type. Each section is concise and serves a purpose, avoiding fluff while providing necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input schema comprehensively, including the nested point structure and an example. Since an output schema is present, the description need not explain return values, but it still mentions the return type. The context is complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description fully compensates by detailing each parameter: project_id and estimate_id as UUIDs, and points as a list with valid fields (value required, max 20 chars, key int, etc.). The example further clarifies the expected structure, making the semantics clear.
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 estimate points for a project estimate,' which specifies a distinct verb and resource. It naturally distinguishes itself from siblings like create_project_estimate (which creates the estimate itself) and update_project_estimate_point (which modifies existing points).
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: it requires project_id, estimate_id, and a list of point definitions. It implies this is for adding points to an existing estimate. However, it does not explicitly state when to use this tool versus alternatives, such as when to use create_project_estimate or update_project_estimate_point.
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 does provide valuable transparency about the 'description_stripped' parameter, noting that it is a convenience field that gets wrapped into HTML and is ignored if 'description_html' is set. It also states the return type ('Created WorkItem object'). However, it does not disclose potential side effects, permission requirements, rate limits, or behavior on invalid input, which could be relevant for a create 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 well-structured with a clear header, a comprehensive list of arguments, and a returns section. Each parameter is described in a single line with concise but meaningful explanation. Given that there are 19 parameters, the length is appropriate and every line provides useful information without fluff. It is front-loaded with the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all required and optional parameters with sufficient detail, including types, formats, and special behaviors. It also indicates the return type in the 'Returns' line, and since an output schema exists, detailed return structure is not required. The description is comprehensive for a create operation with this many input parameters, leaving no critical gaps.
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 description adds significant semantic meaning to all 19 parameters beyond the bare schema types. For example, it states that project_id is a 'UUID', assignees is a 'List of user IDs', priority is 'urgent, high, medium, low, none', start_date and target_date use 'ISO 8601 format', and description_stripped has a special processing rule. This is especially valuable given the schema has 0% description 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 starts with 'Create a new work item', which clearly states the verb (create) and resource (work item). This distinguishes it from sibling tools like update_work_item, delete_work_item, and retrieve_work_item. The required params (project_id, name) further reinforce the 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 clearly indicates this tool is for creating new work items, with a straightforward context. It does not explicitly name alternative tools for other operations, but the action is unambiguous. It also lists required parameters, implying that this tool should be used when creating a work item with those required fields. No exclusions or alternative recommendations are given, but the context is clear enough.
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 explains scope-dependent creation behavior, conditional required fields, and the return of a created object. However, it omits potential edge cases like providing work_item_type_id without project_id, error handling, or permission requirements, which are relevant for a create operation with complex scoping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with summary, scope resolution, args, and returns sections. It is longer than minimal, but given the need to document 15 parameters without schema descriptions, each section earns its place. The front-loaded summary immediately states the core action.
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 complex 15-parameter tool with no annotations and no schema descriptions, the description covers parameter semantics, scoping logic, and return value. The only notable gap is not addressing the invalid combination of work_item_type_id without project_id, and lacking error-condition guidance. Overall, it is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero description coverage, yet the description lists all 15 parameters with types, constraints, and conditional logic (e.g., 'relation_type required when property_type=RELATION', 'settings required for TEXT/DATETIME', 'options for OPTION'). It adds rich semantics beyond the bare schema types, including detailed format examples for settings and scope resolution rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new work item property' with a specific verb and resource. The scope resolution section further clarifies the three possible scopes, distinguishing this create operation from update/delete/list siblings.
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 on when to use different parameter combinations (project_id, work_item_type_id, neither) and provides conditional requirements (relation_type for RELATION, settings for TEXT/DATETIME). It does not explicitly mention using update_work_item_property for existing properties, but the tool name and 'Create a new' imply when this tool applies, making the usage clear without explicit 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?
With no annotations, the description carries the burden. It does disclose basic behavior: creating a type, workspace vs project scope via project_id, and returning the created object. However, it does not address duplicate handling, name uniqueness, required permissions, or error cases. The alternative note implies duplication is a concern but does not state whether create_work_item_type itself guards against it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a helpful alternative note, a compact Args list, and a Returns line. There is no filler or redundant information; every sentence serves a purpose. It is concise yet covers all 7 parameters.
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 purpose, parameter semantics, scope nuances, and return type, and includes sibling guidance. It lacks edge cases like duplicate names, error conditions, and permissions, but the output schema exists and the core usage decisions are well addressed. For a moderately complex create tool, it is substantially 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?
Since schema descriptions are absent (0% coverage), the Args section compensates by explaining each parameter. It clarifies the key distinction between project_id (workspace-level type) and project_ids (list of applicable projects), and adds context for external_source/external_id. Some descriptions are tautological (e.g., 'description: Work item type description'), but overall the semantic value is substantially higher than 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 opens with 'Create a new work item type,' a specific verb+resource statement that is unambiguous. It also distinguishes itself from the sibling resolve_work_item_type by recommending that alternative for project-usable types, clearly differentiating its role among the CRUD siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'To get a usable type for a project (e.g. "Epic"), prefer resolve_work_item_type, which finds-or-creates at the correct scope and never duplicates.' This provides a clear when-not-to-use directive and suggests an alternative. Parameter notes further clarify workspace vs project scope, giving context for choosing the appropriate call.
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 full burden and does well: it explains filter semantics (case-insensitive contains, exact role_slug, AND combination), order_by prefix behavior, paginated envelope structure, and self-hosted specific behavior (all members in one page). This goes beyond typical list-tool descriptions, though minor aspects like authentication or workspace context are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a one-sentence purpose, a filters paragraph, and labeled 'Args:' and 'Returns:' sections. It is front-loaded with the core function, and every sentence provides distinct value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the output schema, the description enriches understanding by covering all parameters, return fields (including role, role_slug, is_active, is_bot), pagination envelope, and the self-hosted single-page behavior. It is comprehensive for a listing tool, with only minor ambiguity about how 'current workspace' is resolved.
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 has 0% coverage for parameter descriptions, but the tool description explicitly covers every parameter: first_name/last_name/email/display_name as case-insensitive contains, role_slug as exact, is_active and is_bot with implied boolean filtering, and order_by with prefix '-' for descending. This adds substantial meaning 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 opens with 'List members of the current workspace (filterable)', using a specific verb+resource that clearly distinguishes it from sibling tools like get_project_members. The mention of filters further clarifies its 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 'current workspace' phrasing provides clear context, but the description does not explicitly state when to use this tool versus alternatives like get_project_members. No exclusions or alternative references are given, leaving the when-to-use guidance to be inferred 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.
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 pagination behavior (cursor, per_page default and range, output envelope with next_cursor and prev_cursor), sorting syntax, and expand/field selection. It does not mention side effects, but as a list operation this is inherently non-destructive. The return structure is well 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?
The description is efficiently structured with a one-line purpose, a clear Args list, and a Returns line. Every sentence adds information; there is no fluff or repetition. The front-loaded purpose statement is immediately useful.
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 has 8 parameters, no annotations, and an output schema that is not shown, the description covers all parameters and the paginated return envelope. It is sufficiently complete for making a correct call, though it could have gone one step further by explicitly contrasting with list_work_items or other list variants. Overall, the complexity is handled well.
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 13%, so the description must compensate. It adds meaningful parameter semantics: project_id and module_id are identified as UUIDs, order_by syntax is specified, per_page has a range and default, cursor is tied to a previous response's next_cursor, and expand/fields are explained. The pql parameter is covered in greater detail in the schema, but the description still gives a concise summary and a pointer to 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 begins with a specific, unambiguous verb and resource: 'List work items in a module.' This clearly distinguishes it from sibling tools like list_work_items, list_cycle_work_items, and list_milestone_work_items by scoping to a module. The optional PQL filtering is an additional useful qualifier.
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 establishes the tool's context: it lists work items within a specific module, identified by project_id and module_id. It also explains how to optionally filter via PQL and that omitting PQL lists all items. However, it does not explicitly name alternatives or provide when-not-to-use guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It explains the pagination envelope and the 'page again while next_page_results is true' pattern, which is valuable runtime behavior. It does not explicitly mention read-only semantics or auth, but 'list' strongly implies non-mutation.
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 front-loaded with the core purpose, then organized into Args and Returns sections. Every line is informative and 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool, the description thoroughly covers pagination mechanics and the return envelope. It lacks optional details like sorting or filtering, but these are not indicated by the schema or context, so the description is sufficiently 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 coverage is 0%, but the description fully explains cursor ('Prior response's next_cursor; omit for first page') and per_page ('default 20'). This provides essential meaning beyond the bare schema types and defaults.
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 'List releases in the workspace (paginated)', giving a specific verb and resource. It clearly distinguishes itself from sibling tools like retrieve_release (single release) and create_release by focusing on the list operation.
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 alternatives or when-not-to-use conditions are given. The pagination instructions (cursor, per_page, next_page_results) provide clear context for how to iterate, but the choice of this tool over retrieve_release is only implied by the name.
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. It discloses the distinction between built_in_dependencies and custom_definitions, explains that custom_definitions are managed by sibling CRUD tools, and outlines group semantics. It does not mention read-only behavior explicitly, but 'List' implies it and this is not a mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a lead sentence stating purpose, a usage directive, then Args and Returns sections. Every sentence adds value, and the key usage point is 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?
Given the tool's moderate complexity, no annotations, and presence of an output schema, the description is complete. It covers the two parameter filters, the two output groups, and the relationship to create/update/delete operations. Minor omissions like whether filters affect built-in dependencies are implied by the wording.
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%, so the description must compensate. It does: 'is_default: Filter custom definitions to default/non-default only' and 'is_active: Filter custom definitions to active/inactive only' adds meaning beyond the raw schema. It doesn't specify what happens when both filters are combined, but the core semantics are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every relation type usable with create_work_item_relation', naming a specific verb, resource, and purpose. It also distinguishes from sibling tools like list_work_item_relations by focusing on relation types, not actual relations.
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?
Explicit guidance is given: 'Match the user's wording against an entry here before creating a relation.' This tells the agent when to use the tool. It also references create/update/delete_work_item_relation_definition as managers of custom definitions, differentiating from those siblings, though it doesn't explicitly state when not to use the 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, the description carries the burden. It indicates a read operation via 'retrieve' and explains the conditional behavior and return type, but it does not disclose error handling, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an opening purpose statement followed by Args and Returns sections. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple 2-parameter retrieval tool with an output schema present, the description covers all necessary aspects: scope selection, parameters, and return type. It is complete for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully compensates by explaining the meaning of both parameters, their types (UUID), and the conditional omission of project_id for workspace pages.
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 ('Retrieve a page by ID') and specifies the scope distinction between project and workspace pages, which differentiates it from sibling tools like list_pages and other retrieve_* 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?
It provides clear usage context by explaining when project_id should be given vs omitted, effectively guiding agent behavior. However, it does not explicitly mention alternatives or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It explains the identifier format, valid sparse fields, the project vs project_id distinction, and the return type. It also provides a concrete tip about using list_projects for UUID resolution. It omits error handling or permission details, but for a retrieve-only operation 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, format explanation, field guidance, and an Args section. The valid fields list is long but necessary for usability. Each section serves a purpose, though it could be marginally tightened without losing 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 the output schema exists and the sibling tool list is large, the description covers essential retrieval context, identifier constraints, field semantics, and a key alternative for project UUID resolution. It does not discuss error cases or edge conditions, but overall it is sufficiently complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates. It lists all six parameters in the Args section with concise explanations, including the exact format for work_item_identifier and a comprehensive list of valid fields values. This goes well beyond the schema and gives agents the needed 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 retrieves a work item by its full identifier (project prefix + sequence number), with a specific format (PROJECT-N). It distinguishes itself from the related list_projects tool by noting it should be used when resolving a project UUID from a short identifier. The verb+resource+format makes 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 explicit guidance on when to use list_projects as an alternative for resolving project UUIDs, and it clearly defines the required identifier format. However, it does not explicitly contrast with retrieve_work_item or search_work_items, leaving some ambiguity about which retrieval tool to prefer when a UUID is already available.
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, this description carries the full burden and does well, disclosing that values are replaced, only specified properties change, and outlining the value format for each property type. It lacks details on permissions or error behavior but is substantially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, followed by behavioral notes and an args section. It is slightly long but every sentence earns its place, providing necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main complexities of this tool, including partial updates, value type coercion, and array handling for non-multi properties. It is complete for a setter tool, though it omits details about response behavior or edge cases like empty lists, but overall it is sufficient given its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds extensive meaning beyond the bare schema by explaining customer_id as a UUID and detailing the values mapping structure with examples. It also provides per-type value formats and the single-item list rule, which are essential for correct invocation.
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: 'Set a customer's custom property values, replacing any current ones.' It identifies the specific resource (customer's custom property values) and differentiates from sibling tools like set_work_item_property_value and get_customer_property_values.
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 explaining that 'Only the properties named are touched; the rest keep their values,' which guides the user on partial updates. It does not explicitly name alternatives but implies when to use this tool versus others, covering the main 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 provided, the description carries the full burden of behavioral disclosure. It discloses the partial update behavior ('Only the fields you pass are changed'), a key side-effect trait, and notes an important limitation (work item links cannot be changed). It also states the return type. However, it does not clarify whether explicitly passing null clears a field or is treated as 'not provided,' which is a meaningful behavioral 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 compact and well-structured: a one-sentence function statement, a brief behavioral note, a redirect to an alternative tool, an Args list, and a Returns line. Every sentence adds value, and the information is front-loaded. No unnecessary jargon or repetition.
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 core operation, partial update behavior, the only explicit exclusion (work item links), all parameters, and the return type. Given the presence of an output schema, the return value is sufficiently described. The main completeness gap is the ambiguity around null parameter handling and potential format constraints (e.g., link URL validation, HTML restrictions), which are not mentioned.
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?
Since the schema description coverage is 0%, the description compensates by listing each parameter with a concise semantic annotation: customer_id (UUID of the customer), request_id (UUID of the customer request), name (Request name), description_html (HTML description), link (URL associated with the request). These add meaning beyond the raw schema property names. However, it does not explain the null default behavior or whether fields can be explicitly reset to null, which would be useful.
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: 'Update a customer request' with a specific verb and resource. It further clarifies the scope with 'Only the fields you pass are changed,' distinguishing it from full-replacement update operations. The sibling context includes other customer request tools (create, retrieve, delete, list), so this unequivocally identifies the update 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 names an alternative for a specific excluded case: 'Work item links cannot be changed here — use manage_customer_work_items with this request_id as customer_request_id.' This is clear guidance on when not to use this tool and which sibling to use instead. However, it does not provide broad scenarios for when to use this tool versus other customer request operations, though that is reasonably 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?
No annotations are provided, so the description carries the burden. It discloses key behaviors: name uniqueness, default status, the distinction between release_date and target_date (one displayed in UI, one not), and that the returned Release contains a nested description object. It could add permission or error details, but it gives solid behavioral context beyond a bare mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, an Args block, and a Returns block. Each parameter gets a concise, useful explanation; there is no fluff or repetition beyond minor redundancy in the release_date line. It earns its length.
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 complexity (10 parameters, no annotations, no schema descriptions), the description is nearly complete: it covers every parameter, the return shape, and the uniqueness constraint. It could mention failure modes or permissions, but the output schema exists to cover return structure, and the essentials for correct invocation are present.
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 has zero description coverage, but the description explains all 10 parameters in plain language, including semantic distinctions (release_date vs target_date), expected formats (YYYY-MM-DD), and examples (external_source 'github'). This fully compensates 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?
Description opens with a specific verb+resource: 'Create a release in the workspace.' This unambiguously differentiates from sibling tools like update_release, delete_release, and list_releases. The added constraint 'Name must be unique in the workspace' further clarifies the tool's purpose and preconditions.
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 it (to create a new release) and provides within-tool guidance such as 'Prefer release_date unless you specifically need this field' and the default for status. However, it does not explicitly name alternative tools like update_release or state when not to use this tool, 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.
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 the uniqueness constraint ('Name must be unique'), clarifies that it only defines the label and does not attach it to a release, and specifies the return value. This adds meaningful behavioral context beyond a simple 'create' action, though it does not address error handling 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 concise and well-structured: a one-line purpose, a uniqueness constraint, a clarifying note about attaching, and a clean Args/Returns format. Every sentence adds value, and it is front-loaded with the main purpose.
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 create tool with 3 parameters and a documented return, the description provides sufficient information. It also subtly distinguishes from related release label tools. It does not cover error conditions or permissions, but given the tool's simplicity and existing annotations absence, it is reasonably 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?
The schema has no descriptions (0% coverage), so the description fully compensates by explaining each parameter: name is the label name (unique), color is a hex color with example, and sort_order is the position in the palette. This gives the agent clear semantic understanding that the schema lacks.
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 action: 'Create a release label in the workspace palette.' It specifies the verb 'create', the resource 'release label', and the scope 'workspace palette', which distinguishes it from sibling tools like create_label or manage_release_labels.
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 noting that this defines a label and that attaching it to a release is done via manage_release_labels. This implies the use case (creating a label) and the follow-up action, but does not explicitly mention alternatives like create_label or 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.
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 discloses a non-obvious behavior (silent success on no match) and the constraint that external references require both fields. However, it does not mention permissions, irreversibility, or what happens if both ID and external reference are supplied.
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?
Brief and well-structured: a one-line summary, a usage paragraph, and a clean Args list. Every sentence adds value and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity delete tool with no output schema, the description covers the key operational aspects: addressing modes and silent success. Minor gaps remain on conflict handling (both ID and external refs) and permissions, but overall it is nearly 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?
The schema has zero description coverage, so the description fully compensates. It defines each parameter: customer_id as UUID, external_source as the originating system, external_id as the customer's ID in that system, and explains their combined usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a customer', which clearly states the action and resource. It further specifies two addressing modes (by ID or external reference), distinguishing it from sibling tools like delete_customer_property.
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?
Explicitly tells the user to pass either customer_id or both external_source and external_id, and warns that external-reference deletes succeed silently when nothing matches. This is clear usage context, though it does not explicitly name alternatives or when-not-to-use cases.
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 and does well: it discloses that the changelog is created empty on first access (a subtle side effect), always returns one result, and that the body is a nested object. This goes beyond a simple 'get' and informs the agent of potential 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 concise, well-structured with Args/Returns sections, and front-loads the core purpose. Every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval tool, the description covers behavior, parameter semantics, and return shape. An output schema exists, so further detail isn't necessary. The description fully equips an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains release_id as 'UUID of the release', adding semantic meaning beyond the plain string type. While minimal, it fully covers the single parameter's purpose.
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 action ('Get a release's changelog') and clarifies the unique behavior ('Each release has a single changelog, created empty on first access, so this always returns one'). This clearly differentiates it from siblings like update_release_changelog.
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 applicable (retrieving a changelog, always returns one) but does not explicitly mention alternatives or exclusions. The behavior of returning a single changelog implies its use case, but no sibling comparison is 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 discloses that the URL is time-limited (~1 hour), requires no Plane authentication on the URL itself, and works in browsers or HTTP clients. It also describes the return structure. This is strong transparency, though it could note that API authentication is still required to obtain the URL or add error handling details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-organized, and front-loaded with the primary purpose. It uses a clean structure with introductory sentence, usage note, Args, and Returns sections. No superfluous language — every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple URL fetcher with 3 parameters and no formal output schema, the description fully covers the necessary context: what it does, the prerequisite step, parameter meanings, return shape, and key behavioral details (time limit, no auth on URL). It is complete enough for an agent to invoke correctly without additional documentation.
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 no descriptions (0% coverage), so the description's Args section is essential. It lists all three parameters with clear semantic comments ('UUID of the project', 'UUID of the work item', 'UUID of the attachment'). This adds meaning beyond bare schema names, though it could further explain how to obtain each (e.g., via list_work_items), which is done only implicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a presigned download URL for a work item attachment' — a specific verb, resource, and output. It distinguishes this tool from siblings like read_work_item_attachment (which likely returns content) and upload_work_item_attachment_from_url by emphasizing it provides a URL for direct download.
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 instructs 'Use list_work_item_attachments first to get attachment IDs and names,' providing a clear prerequisite. It also explains the URL's behavior (browser or HTTP client, no Plane auth required). It does not explicitly mention when not to use this tool or compare with alternatives, but the context is sufficient 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?
No annotations are provided, so the description carries the full burden. It explains the archived flag behavior, pagination cursor format, per_page range, order_by descending prefix, and the return envelope. It does not explicitly state auth or rate limits, but for a read-only list tool, the provided behavioral details are substantial and clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, a bulleted Args list, and a Returns line. Every sentence provides necessary information without waste. It is appropriately sized for a 5-parameter tool.
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 an output schema exists, the description does not need to detail module fields. It covers all parameters, explains pagination, and the return envelope. The only minor gap is that order_by does not enumerate valid field names, but overall it is complete enough for effective use.
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. It thoroughly explains each parameter: project_id as UUID, archived to toggle active vs archived, cursor with format '{per_page}:{page}:{offset}', per_page allowed range, and order_by with '-' prefix for descending. This fully compensates for the lack of schema-level 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 states 'List modules in a project' with a specific verb and resource. It clearly distinguishes from sibling tools like list_projects and list_module_work_items by focusing on modules within a project.
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: list active or archived modules in a project. It does not explicitly mention alternatives or exclusions, but the usage is evident from the one-liner and parameter details. It could have explicitly distinguished from retrieve_module, but 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.
Behavior4/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 transparently explains the fallback scope resolution (workspace → project-flat → workspace), the result structure (id, display_name, property_type, options), and the PQL workflow. It does not mention pagination, rate limits, or auth requirements, but for a list operation the described behavior is unusually detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, but somewhat long at approximately 300 words. It contains useful sections for scope resolution, result fields, and PQL workflow, each earning its place. However, it is more verbose than strictly necessary for a list operation, and the PQL workflow could be considered tangential to the tool's core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three optional params, multiple scope behaviors, an output schema, and a sibling context), the description is remarkably complete. It covers all parameter combinations, provides the output fields, and even includes a practical workflow for composing PQL filters. The presence of an output schema reduces the need to elaborate return values, yet the description still adds valuable context on using the results.
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%, and the description fully compensates by explaining the effect of each parameter combination (no args, work_item_type_id only, project_id only, both). It also clarifies what each returned field means for downstream PQL usage, adding substantial meaning beyond the bare schema definitions.
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 'List custom work item properties,' a specific verb+resource combination that clearly distinguishes this tool from siblings like retrieve_work_item_property (single retrieval) and list_work_item_property_options (options for a property). It immediately conveys the tool's purpose 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit scope resolution rules based on argument combinations and even recommends an efficient approach for PQL filtering ('prefer calling with NO args'). It gives clear context on when to use the tool and how to choose parameters, though it does not explicitly compare against alternative sibling tools like retrieve_work_item_property or list_work_item_property_options.
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 of behavioral disclosure. It explains the effect of link/unlink, the scoping behavior of customer_request_id, and a critical edge case (omitting it on unlink drops all links), plus the return value. It does not mention permissions or error behavior, but the provided details are substantial 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 concise and well-structured, with a clear one-sentence purpose followed by an Args section and a Returns section. Every sentence earns its place; there is no redundant information 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 simple but the description covers purpose, parameters, scoping, edge case, and return value, making it largely complete. It does not address prerequisites like permissions or potential failure modes, but given the tool's simplicity and the presence of an output schema, the missing details are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It does exactly that: customer_id is typed as UUID, action is explained with its enum values, work_item_ids is described as a list, and customer_request_id gets a detailed explanation of its scoping semantics. This adds far more meaning than 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 opens with 'Link or unlink work items on a customer,' a specific verb and resource combination that clearly states the tool's function. It also distinguishes itself from the sibling read tool by explicitly directing users to list_customer_work_items for reading, which eliminates ambiguity.
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 tells users to use list_customer_work_items for reading and when to use 'link' vs 'unlink' via the action parameter. It does not explicitly state when not to use this tool or mention alternative tools for other operations, but the reading alternative is sufficient for distinguishing core use cases.
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 reveals important traits: removal is applied before addition when both are provided, and already-assigned users are silently skipped. This adds meaningful context beyond the basic operation. However, it omits potential error conditions, permission requirements, or side effects, so a perfect score is not warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized and compact. The main behavior is stated in one sentence, followed by operational details and a clear Args/Returns structure. Every sentence adds value, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the description is complete: it explains the core behavior, parameter semantics, order of operations, silent skipping, and return type (Updated WorkItem object). The presence of an output schema further reduces the need to describe return structure in detail. No critical context is missing.
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. The 'Args:' section clearly defines each parameter (project_id, work_item_id, add_user_id, remove_user_id) and their roles. It also explains the interplay between add and remove parameters. This is solid compensation, though it could go further by addressing edge cases like passing neither add nor remove.
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: 'Add or remove a single assignee on a work item without replacing the full list.' It identifies the specific verb (add/remove), the resource (work item assignee), and the key scope (single assignment, not full list replacement), which distinguishes it from broader update 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 gives clear context for use, emphasizing 'without replacing the full list' to differentiate from batch assignment operations. It also explains the usage pattern ('Provide add_user_id, remove_user_id, or both') and the order of operations. However, it does not explicitly name alternative tools or state when not to use this tool, 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.
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 a strong job: it states this is a mutation, requires at least one of the arrays, explicitly says detach does not delete the property, and specifies the return value. It lacks edge-case details (e.g., behavior when both lists are provided or duplicate IDs), but these gaps do not undermine core transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core operation, followed by essential constraints and a compact Args/Returns breakdown. Every sentence earns its place, and the detach clarification prevents a major misuse without adding bloat.
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 all essential aspects for this moderately complex tool: action, required and optional inputs, preconditions, behavioral nuance, and return type. Minor edge-case behavior (e.g., simultaneous attach and detach ordering, invalid IDs) is not addressed, but these are not likely to block correct selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description fully compensates by documenting all four parameters, including their UUID types and the semantic difference between attach_ids and detach_ids. It also adds the critical constraint that at least one of the two optional arrays must be provided, which is not inferable from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Attach or detach properties on a work item type.' This clearly distinguishes it from sibling tools like manage_work_item_label or manage_work_item_assignee, and the 'in a single call' phrasing communicates its combined nature.
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 conveys when to use the tool: whenever property associations on a work item type need to be added or removed. It also provides a key precondition ('At least one of attach_ids or detach_ids must be provided') and clarifies that detach is not deletion, indirectly steering users away from delete tools. It does not explicitly name alternatives, but the guidance is sufficient.
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 discloses important behavior: partial updates are applied only to passed fields, stage and contract_status are stored free-form but Plane renders only specific values, and domain is explicitly NOT a web domain. It also states the return value. It does not mention error/edge-case behavior, but the disclosed traits are substantive.
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 front-loaded with the action and partial-update note, then uses a clean, consistent Args list. Each parameter gets a compact line with relevant detail, and the Returns line is clear. There is no fluff or redundant repetition of schema type 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 13-parameter update tool with no annotations, this description covers parameter semantics, update behavior, rendering constraints, and return value, making it largely complete. The only minor gap is the vague 'Logo properties' description for logo_props and the absence of explicit prerequisite/error information, but overall it is well above the minimum viable level.
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?
With schema description coverage at 0%, the description fully compensates by documenting all 13 parameters with meanings, examples, and allowed renderable values for stage and contract_status. It even clarifies the potentially confusing domain vs website_url distinction, which is exactly the kind of semantic value an AI agent needs.
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 customer by ID', a specific verb+resource+scope that clearly states what the tool does. It also clarifies partial-update semantics ('Only the fields you pass are changed'), which distinguishes it from create/retrieve/delete customer siblings.
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 the usage context clear: update an existing customer by ID with optional fields. It does not explicitly state when not to use it or name alternatives, but the partial-update note and the presence of create/retrieve/delete siblings imply the intended use case well.
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 burden. It explains status value semantics, conditional requirements for snoozed_till and duplicate_to, the conversion of accepted intake items to active work items, and the non-obvious work_item_id mapping. It doesn't mention permissions or reversibility, but covers key side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, status values, args, and returns sections. There is some redundancy in restating status values in the arg list, but the organization is clear and each section earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter update tool with 0% schema coverage and no annotations, the description covers all required information: parameter types, conditional dependencies, return type, and special behavior. It is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions, so this description is essential. It adds meaning to every parameter, including the exact status enum values, conditional dates, and the crucial work_item_id gotcha. This far exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an intake work item and specifically handles triage status. The resource is specific (intake work item) and the verb is clear (update), differentiating it from update_work_item and other intake 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 provides clear context that this tool is for intake work items and gives a critical guidance to use the 'issue' field as work_item_id. It does not explicitly name alternatives or exclusions, but the domain is well-scoped.
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 the partial update behavior, the distinct semantics of release_date vs target_date (including that target_date is not shown in UI), and the return value. It does not mention permissions, error scenarios, or side effects, which would have made it more complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, an Args block, and a Returns line. Every line adds information without redundancy, making it both concise and highly readable.
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 9-parameter update tool with no annotations, the description covers the essential semantics: partial update, parameter meanings, and the return value. It does not address edge cases like validation rules or permission requirements, and the role of target_date could be even more explicit, but overall it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description lists all 9 parameters with meaningful explanations. It adds crucial context, especially for release_date ('The date shown as Target date in the Plane UI') and target_date ('A separate date stored on the release but not shown in the release UI'), fully compensating 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 opens with 'Update a release by ID', which clearly identifies the action and target resource. It further specifies partial update behavior ('Only the fields you pass are changed'), distinguishing it from other release-related tools like create_release or delete_release.
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 (updating a specific release) and gives field-level guidance, such as 'Prefer release_date unless you specifically need this field.' However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full exclusionary 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, the description carries the full burden. It discloses key behavior: plain text is converted to HTML and a ProseMirror doc, description_html is ignored when set, description_json overrides the generated doc, and the editor would show nothing if the doc is absent. This goes well beyond basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with Args and Returns sections, front-loads the main purpose, and has no fluff. It is slightly verbose due to the rendering explanation, but every sentence adds necessary detail about parameter behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all four parameters, explains their interactions and edge cases, notes the return value, and the presence of an output schema means return-value details are not omitted. It is fully self-contained for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description thoroughly explains each parameter: release_id is a UUID, description_html is the HTML body, description_stripped is a plain-text convenience that gets wrapped into HTML and ProseMirror, and description_json is an optional ProseMirror doc that takes precedence. This compensates entirely for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update a release's changelog body.' This is a specific verb-resource pair and differentiates it from sibling tools like update_release (general release fields) and get_release_changelog (reading the changelog).
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 detailed guidance on parameter precedence (e.g., 'Ignored if description_html is set' and 'it wins over the doc generated from description_stripped'), but it does not explicitly compare this tool to alternatives like update_release or get_release_changelog. Usage context is implied by the tool name and first sentence, but no explicit 'use this when...' or 'instead of...' is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses that the MCP server downloads the file server-side and uses the standard three-step presigned S3 flow, and warns about SSRF-related URL restrictions. This goes beyond basic function but doesn't discuss error behavior, size limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear action statement, process explanation, constraints, and organized Args/Returns sections. Every sentence adds necessary detail without 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?
The description covers the process, constraints, all parameters, and return value, making it quite complete for its complexity. It lacks explicit error handling or size limit details, but the core information needed for using the tool is present.
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 input schema has zero descriptions, but the description compensates fully. It explains each parameter: project_id and work_item_id as UUIDs, url with examples (GitHub raw, S3, direct download), and name as an override with default behavior (filename from URL path). This far exceeds 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 states the exact action: 'Fetch a file from a public URL and attach it to a work item.' It clearly identifies the resource (file via URL to work item) and distinguishes from sibling tools like list_work_item_attachments and get_work_item_attachment_download_url. The mention of the S3 flow adds specificity.
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 is for attaching files from public URLs, and explicitly defines when-not (URL must be publicly accessible, no private/internal addresses). However, it does not name alternative tools for other attachment scenarios, so it stops short of the most explicit 'use instead' 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 full burden. It discloses the ToolError condition for disabled features and the fallback action, and mentions the return value. However, it doesn't specify permission requirements or other side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary followed by Args, Returns, and Raises sections. There is no redundant or extraneous information; each section serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters and no annotations, the description covers parameters, return value, and a critical error case with fallback steps. The output schema exists, so return details are not needed. Minor gaps include uniqueness constraints or state transition rules, but the description is largely 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 description coverage is 0%, but the description adds meaning for all 7 parameters: ISO 8601 for dates, dictionary for logo_props, enumerated states, UUID for lead, and HTML format for description. This significantly enhances the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new initiative in the workspace' with a specific verb and resource. It distinguishes itself from sibling tools like update_initiative or delete_initiative by explicitly indicating creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Raises section provides an explicit alternative: when the feature is disabled, it tells the agent to create a 'Initiative' work item instead. This gives clear when-to-use and when-not-to-use guidance, including a fallback.
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 disclosure. It transparently states the global effect ('detaching it everywhere') and the destructive nature of the operation. However, it does not explicitly mention irreversibility or potential side effects beyond detachment, which would strengthen the 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 exceptionally concise: two sentences and an argument doc. It is front-loaded with the core purpose, includes an alternative usage hint, and provides parameter information with no extraneous text. Every sentence 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?
Given the low complexity (one parameter, no output schema, no annotations), this description is nearly complete. It explains what the tool does, the global scope, the alternative for partial removal, and the parameter meaning. The only gap is the lack of an explicit warning that deletion is permanent, but the description otherwise fully covers the necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify parameters. It does so by labeling label_id as 'UUID of the release label', which adds semantic meaning (UUID and purpose) beyond the raw string type in the schema. This adequately compensates for the lack of schema-based documentation.
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 action: 'Delete a release label from the workspace palette, detaching it everywhere.' It uses a specific verb ('Delete'), names the resource ('release label'), and defines the scope (workspace palette, all releases). This distinguishes it from the sibling tool manage_release_labels, which removes a label from a single release.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by contrasting with an alternative: 'To only remove a label from one release, use manage_release_labels with action="detach".' This tells the agent exactly when not to use this tool and which sibling to use instead, fulfilling the usage criterion.
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 of disclosing behavior. It explicitly states that properties with no value set and inactive properties are absent from the result, and describes the return format (Property UUID mapped to values). This adds meaningful behavioral context beyond what the schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, then an Args section and a Returns section. Every sentence adds useful information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with two parameters and an output schema, the description is complete. It explains the behavior for missing values, the return mapping, and the optional parameter. No critical gaps are evident.
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 has 0% description coverage, but the description fully explains both parameters: customer_id as the UUID of the customer and property_id as an optional UUID that can be omitted to read all properties. This adds significant meaning that the bare schema lacks.
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 ('Read') and a clear resource ('custom property values a customer holds'), which precisely distinguishes it from siblings like set_customer_property_values (write) and list_customer_properties (definition listing). It also states the optional scope property_id, further clarifying what is read.
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 reading a customer's property values, and provides guidance on the optional property_id ('omit to read them all'). It does not explicitly mention when not to use it or name alternatives, but the read/write distinction with set_customer_property_values is implied by the sibling list.
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 responsibility. It discloses the key behavioral trait: the toggle between project and workspace scope based on project_id. It also specifies the return types (ProjectFeature vs WorkspaceFeature). It does not mention error handling or explicitly state that it is read-only, but for a getter this is mostly implicit, justifying a 4 rather than a 5.
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 perfectly sized: a one-line summary, one conditional explanation, and structured Args/Returns sections. Every sentence earns its place, and the most important info is front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one optional parameter, no annotations, and an output schema available, this description is complete. It fully explains the conditional behavior and the corresponding return types, leaving details of the return structure to the output schema. Nothing meaningful is missing.
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 input schema has 0% description coverage, so the description must compensate. It does so fully by explaining 'project_id: UUID of the project. Omit for workspace features,' giving type, meaning, and usage in one line. This adds significant value 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 opens with 'Get feature flags,' a clear verb+resource. It then explains the conditional scope: returns project features if project_id is provided, otherwise workspace features. This distinguishes it from sibling update tools like update_project_features and update_workspace_features, which are write 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?
It clearly states when to include project_id (to get project features) and when to omit it (to get workspace features), which is the primary usage decision. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, 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?
With no annotations, the description carries the burden of disclosing behavior. It covers pagination (cursor, next_cursor, prev_cursor), defaults for ordering and per_page, and the optional filter behavior. It does not explicitly state read-only semantics, but 'List' implies it, and the pagination details add substantial 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 well-structured with an Args section and a Returns section. Every sentence contributes necessary parameter or return information, and there is no filler or repetition. It is appropriately sized for a 7-parameter tool with pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, pagination, PQL filtering), the description covers all parameters, defaults, return envelope, and pagination mechanics. It also mentions output schema details in the Returns section, making it fully actionable for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 14% (only pql has a description), so the description must compensate. It provides meaningful one-line explanations for all 7 parameters, including defaults and usage (e.g., order_by prefix, per_page range, cursor source, expand/fields format). This adds significant value beyond 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 uses a specific verb+resource ('List archived work items') and clearly scopes it to 'in a project' with 'optional PQL filtering'. This distinguishes it from sibling tools like list_work_items and list_intake_work_items, so 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys that this tool is for archived work items and explains the default behavior ('Omit to list all archived items'). However, it does not explicitly state when not to use it or mention alternatives like list_work_items for non-archived items. Context is clear, but exclusions are not spelled out.
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 behavioral disclosure. It thoroughly documents pagination behavior (cursor, per_page, next_cursor, next_page_results), the default per_page value, the response envelope, and query semantics (name contains). This goes well beyond what the schema alone offers.
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 well-structured docstring: a one-sentence summary followed by an Args list and Returns list. Every line carries necessary information about pagination and filtering, with no fluff. The front-loaded purpose ensures quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with three optional parameters and pagination, the description covers the essential use cases: fetching all customers, filtering by name, and advancing through pages. It also explains the return envelope and the loop condition. Even with an output schema present, the description adds clarity without being excessive.
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 input schema has 0% description coverage, yet the description explains each parameter in plain language: query as a name substring filter, cursor for pagination (omit on first page), and per_page with range and default. This adds rich semantic meaning that the schema lacks.
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 statement: 'List customers in the workspace (paginated).' This clearly distinguishes it from sibling tools like retrieve_customer (single customer), list_customer_properties, or list_customer_requests. The pagination qualifier adds useful 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?
The description implies its use for fetching a paginated collection of customers and provides guidance on pagination and filtering, but it does not explicitly state when to choose this over alternatives like retrieve_customer or list_customer_requests. No exclusions or alternative tool names 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?
With no annotations, the description carries the full burden. It discloses that this is a read/list operation with no side effects, explains the id vs value relationship, and notes a dependency on get_project_estimate. However, it does not cover error conditions, authentication, or rate limits, preventing a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, use-case paragraph, numbered workflow, args, and returns. Each section is purposeful and there is no redundant information, making it both thorough and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a list tool: it covers the purpose, the workflow it belongs to, the parameters, and the return structure. The output schema exists, but the description still adds valuable context about how the fields map to update_work_item, making the tool self-sufficient.
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. The 'Args' section clearly explains project_id as the project UUID and estimate_id as coming from get_project_estimate. It also clarifies that the returned id is what to pass to update_work_item, adding meaning 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 opens with 'List all valid estimate points for a project', which is a specific verb and resource. It distinguishes from sibling tools like create_project_estimate_points and update_project_estimate_point by focusing on the read-only discovery of UUIDs for use with 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this to discover the available estimate point UUIDs before calling update_work_item' and provides a numbered workflow with get_project_estimate as a prerequisite. This gives clear context, but it does not explicitly mention when not to use this tool or name alternative tools that should not be used for this purpose.
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 discloses that results are paginated, describes the envelope (results, total_count, next_cursor, next_page_results), and explains the looping behavior. It does not mention error cases or permissions, but for a list operation 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 well-structured and front-loaded: a one-line summary, then scoping rules, then parameter definitions, then return format. Every sentence earns its place with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with an output schema, the description is complete. It covers both usage modes, explains pagination thoroughly, and documents all parameters. No critical gaps remain; the agent can invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage and all parameters are nullable. The description fully compensates by explaining each parameter: release_id as a UUID scoping filter, cursor as a continuation token, and per_page with a default of 20. This adds substantial meaning beyond the bare schema types.
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 begins with a clear statement: 'List release labels (paginated).' It then distinguishes two scoping modes: with release_id it lists labels attached to that release, without it lists the workspace palette. This differentiates it from siblings like list_labels and list_release_tags, making the tool's 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?
The description explains when to use each mode: 'With release_id... Without it...' and provides pagination guidance for cursor and per_page. It does not explicitly name alternative tools or state when not to use it, but the scoping context is clear enough for an agent to decide.
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 discloses pagination behavior and the exact return envelope structure (results, total_count, next_cursor, next_page_results), which is important for agents to know they must loop while next_page_results is true. It doesn't explicitly state read-only safety or permissions, but the 'List' verb conveys a non-mutating 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 well-structured with a one-sentence summary, a concept clarification, and compact Args/Returns sections. It front-loads the core purpose and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with an output schema, the description covers the concept, parameter semantics, pagination pattern, and return envelope, giving an agent enough to select and invoke it correctly. It also disambiguates from labels without requiring external reference.
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 input schema provides bare types with no descriptions (0% coverage), but the Arguments section fully explains cursor ('Prior response's next_cursor; omit for first page') and per_page ('Results per page (default 20)'), adding semantic meaning beyond the schema. This compensates for the schema's missing 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 'List' and resource 'release tags', and clearly differentiates a release tag from a label by stating 'not a label' and explaining it as a version marker plus optional git metadata. This distinguishes it from sibling tools like list_release_labels.
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 context by stating tags are attached to a release via tag_id and that the list is paginated, but it doesn't explicitly name alternatives or state when-not-to-use. The 'not a label' clarification helps prevent confusion, but there's no explicit alternative tool reference.
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 of behavioral disclosure. It effectively discloses pagination behavior, cursor usage, per_page default, and the paginated envelope including next_page_results and instructions to continue paging. It does not cover ordering or error handling, but for a read-only list operation the disclosed information is substantial and useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, an Args list, and a Returns list. Every sentence is informative and there is zero waste or redundancy. The front-loaded purpose statement immediately identifies the tool's function.
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 moderate-complexity list tool, the description covers the essential aspects: purpose, required parameter, pagination semantics, and return structure. Even though output schema exists, the description redundantly but usefully explains the return envelope. It is complete enough for an agent to understand and invoke the tool correctly without further documentation.
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 fully compensates by explaining each parameter: release_id as the UUID of the release, cursor as prior next_cursor with omit-for-first-page guidance, and per_page with a default of 20. This adds meaningful semantics beyond the raw schema types and defaults.
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 action: 'List the work items linked to a release (paginated).' The verb 'List' is specific and the resource is unambiguously 'work items linked to a release,' distinguishing it from sibling tools like list_work_items or list_releases. This is an exact and concise purpose statement.
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 indicates when to use the tool by specifying it returns work items for a given release_id, which is clear context. It does not explicitly mention alternatives or exclusions, but the purpose statement itself differentiates it from general work item listing tools. No explicit 'when not to use' is provided, 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that archived projects are hidden but not deleted, and that all work items, cycles, and modules are preserved, giving important non-destructive context. It lacks explicit details on permissions or reversal effects, but for a simple toggle operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, followed by key behavioral notes and an Args section that maps directly to the schema parameters. Every sentence 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?
Given that this is a simple two-parameter toggle with no output schema, the description covers all essential aspects: what the tool does, what the parameters mean, and the non-destructive side effects. It is fully 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.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only types and required flags with 0% description coverage. The description compensates fully by explaining project_id as 'UUID of the project' and archive as 'True to archive, False to unarchive', adding complete semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Archive or unarchive a project' which clearly identifies a specific action (toggle archive status) on a specific resource (project). This distinguishes it from sibling archive tools like manage_cycle_archive or manage_work_item_archive by explicitly naming the project as the target.
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: when you want to archive or unarchive a project. It explains the effect (hidden from active lists, preserves data), but does not explicitly mention alternatives or exclusions such as 'use this instead of managing work item archives separately'. Still, the use case is obvious.
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 clearly explains the effects of 'add' and 'remove' actions and states the return value ('The release's linked work items after the operation'). This provides a solid understanding of the mutation behavior. However, it does not mention edge cases (e.g., handling already-linked items) or permission requirements, which would be useful but are not essential for a simple add/remove 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 concise and well-structured, with a one-line summary followed by an Args section and a Returns section. Every sentence provides essential information without redundancy. It is easy to scan and understand, and the formatting clearly separates purpose from parameter and return details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only three required parameters and a straightforward add/remove operation, the description is fully complete. It explains the action, the parameters, and the return value. The reference to list_release_work_items covers the read scenario, and since an output schema exists, the return-value description suffices. No important information is missing.
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 description significantly enhances the input schema by explaining the meaning of each parameter in practical terms: action is defined as 'add to link' and 'remove to unlink', and work_item_ids are specified as the UUIDs to add/remove. Since the schema coverage is 0%, the description fully compensates by providing clear semantic context that the schema alone lacks.
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: 'Add or remove work items on a release.' The verb 'Add or remove' specifies the action, and 'on a release' identifies the resource. This distinguishes it from sibling tools like manage_cycle_work_items or manage_module_work_items, and the specific mention of 'release' differentiates it from other manage_*_work_items 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 explicitly recommends an alternative for read operations: 'Use list_release_work_items to read.' This gives clear context on when to use this tool (for modifications) versus a read-only sibling. However, it does not explicitly state when not to use it beyond the read scenario, so it lacks full 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, the description fully explains key behavioral traits: the upsert semantics, matching based on external_source/external_id or name, and that repeated calls never duplicate. It also clarifies that domain is an industry field, not a web domain, preventing misuse. This goes well beyond a simple 'create' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear upsert warning up front, followed by a detailed but necessary Args list and a Returns statement. Every sentence earns its place; the length is appropriate for an 11-parameter tool with nuanced behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no annotations, output schema not provided in context), the description covers purpose, upsert behavior, parameter details, and return value. It is sufficient for an agent to use the tool correctly without additional context.
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. It does so excellently by explaining each parameter's meaning, including name as a match key, allowed values for stage and contract_status, domain as industry (not web), revenue as a string, and the role of external_source/external_id. This adds significant semantic value beyond the raw 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 'Create a customer, or update the existing one it matches (upsert).' This specifies the verb (create/update), resource (customer), and the unique upsert behavior, distinguishing it from sibling tools like update_customer and delete_customer.
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 explaining it is an upsert, not a plain create, and describes the matching logic. However, it does not explicitly mention the alternative update_customer or state when to prefer that tool over this upsert, so it lacks explicit 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?
With no annotations, the description fully carries the behavioral transparency burden. It discloses immutability of key fields, the discarded 'name' argument, uniqueness constraints on display_name, interdependence of is_required and default_value, and conditional requirements for settings and relation_type.
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 long but tightly organized with 'Args' and 'Returns' sections, with each parameter on its own line and inline format hints. Every sentence adds necessary detail; nothing is redundant or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, 0% schema coverage, and no annotations, the description provides comprehensive information: all parameter meanings, constraints, defaults, and return value. It fully equips an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates admirably by explaining every parameter's purpose, constraints, and expected format. It provides examples for settings and options, which the bare schema does not offer.
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 ('Create') and resource ('customer property'), clarifying it as a workspace-wide custom field on customers. This clearly distinguishes it from sibling tools like create_work_item_property or create_customer.
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's opening parenthetical clearly defines the tool's domain (workspace-wide customer fields), which helps an agent select it over work-item property tools. However, it does not explicitly mention when not to use it or point to alternatives, though 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses that work_item_ids is never echoed back, that it links work items at creation, and that the returned object omits work_item_ids. This is meaningful behavioral context, though it stops short of covering permissions or idempotency.
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 structured with Args and Returns sections, one line per parameter, no redundant text. It is compact and front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, all parameters, the side effect of linking work items, the return value, and what is not returned (work_item_ids). It also names the relevant alternative tools, making it a complete guide for a create operation with an output schema.
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. Each parameter gets a semantic explanation: customer_id is a UUID, description_html is HTML, link is a URL, and work_item_ids are UUIDs that link work items and are only settable here. This adds far more meaning than the raw 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 opens with 'Create a request on a customer,' which is a specific verb+resource statement. This clearly distinguishes it from sibling tools like retrieve_customer_request, update_customer_request, and delete_customer_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to alternatives: 'Only settable here — use manage_customer_work_items to change links afterwards' and 'read the links with list_customer_work_items.' This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses filter behavior (case-insensitive contains, exact match, AND combination), sorting (prefix '-' for descending), pagination envelope, and a platform-specific nuance (self-hosted returns all members in one page). This is rich behavioral disclosure beyond the schema and tool 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 well-structured: a one-line summary, then a concise list of filters and args, then return info. Every sentence provides value and no redundant filler. It is front-loaded with the primary purpose and uses bullet-like formatting for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all essential aspects: purpose, filters, arguments, sorting, pagination, and return structure. Even though an output schema exists, the description provides additional detail about member fields and a pagination edge case. It is complete for a list tool with 9 parameters.
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. It explains every parameter: project_id as UUID, order_by as sort field with prefix rule, and all filter parameters with their matching behavior (contains vs exact). It also states how they combine (AND). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List members of a project (filterable)', which is a specific verb + resource + scope. It clearly distinguishes this from sibling tools like get_workspace_members by explicitly referring to project members. The additional 'filterable' note adds useful purpose context.
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 (when you need members of a specific project, optionally filtered). It provides details about filter semantics and sorting, but does not explicitly mention alternatives or exclusions. The context is clear, but it doesn't say 'use this instead of get_workspace_members for project-level queries'.
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 states that results are paginated, describes the return envelope (results, total_count, next_cursor, next_page_results), and clarifies the workspace-level nature of properties. While it doesn't mention permissions or side effects, there are none expected for a read-only list; the pagination behavior is the key contextual addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a leading summary sentence, a brief definition, and clearly labeled Args and Returns sections. It is compact, with no filler or redundant phrases, and every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers all necessary context: what the tool lists, how pagination works, how to use parameters, and what the response contains. It is fully self-sufficient for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/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's parameter explanations are essential. It fully documents both parameters: cursor as 'Prior response's next_cursor; omit for first page' and per_page with range and default, adding valuable semantics 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 'List customer properties (paginated)' with a specific verb and resource, and goes beyond a tautology by defining customer properties. It also differentiates from the sibling tool get_customer_property_values, saying 'Use get_customer_property_values to read what a specific customer holds for them.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to an alternative tool for a different use case and explains the pagination protocol ('page again while next_page_results is true'). This gives clear guidance on when to use this tool vs. get_customer_property_values.
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 provided, but description discloses default behavior, parameter semantics including status filter being ignored when archived, pagination cursor format, and return envelope. This gives the agent a solid behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Args and Returns sections. Each parameter explanation is concise and informative. No redundant content.
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 six parameters and no schema descriptions, the description covers all aspects: defaults, filtering, pagination, ordering, and return format. The output schema exists, so the return description is a bonus.
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 has no descriptions (0% coverage), so the description compensates fully. Every parameter is explained: project_id, archived, status with enum meanings, cursor format, per_page range, order_by prefix.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'List cycles in a project.' Scope is explicitly defined with 'Active (non-archived) cycles by default.' This distinguishes it from project-listing and work-item-listing 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 clear context: default to active cycles, archived flag switches to archived, status filter ignored when archived. It doesn't explicitly name alternative tools, but the behavior is well-specified.
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 discloses the paginated envelope, the caveat that slug is stable but not globally unique, and the recommendation to key by (namespace, slug). It also states the return fields. This is thorough and 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 efficiently structured with a lead sentence, a caveat about slug uniqueness, and clearly labeled Args and Returns sections. Every sentence contributes valuable information and there is no filler. It is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has optional parameters, no annotations, and an output schema. The description thoroughly covers all parameters, return envelope, pagination behavior, and the namespace semantics, making it complete for an agent to invoke correctly without additional context.
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. It explains all three parameters in detail: namespace enum values, per_page default of 20, and cursor as the prior response's next_cursor. This adds meaning well 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 opens with a clear verb and resource: 'List role definitions in the workspace.' It further clarifies the scope by distinguishing workspace vs. project roles, which differentiates it from the sibling retrieve_role. The purpose is unambiguous and specific.
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 explicit context for when to pass namespace values, including that omitting returns both. It explains the meaning of workspace and project roles, helping the agent decide which invocation is appropriate. However, it does not explicitly name an alternative tool or state when not to use this tool, so it lacks an explicit exclusion.
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 the full burden and delivers: it explains the total_count is the true DB total, not page-bounded; the cursor usage; and the gotcha that a misnamed field in the sparse fieldset is simply absent. This discloses operational behavior well 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?
The description is well-structured: a one-line summary, usage pointers, an Args block, and a Returns block. It is relatively long but every sentence adds necessary detail for a 9-parameter tool.
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 the complexity (9 optional params, no annotations), the description covers all parameters, explains the output structure (results, total_count, cursors), and gives practical field-sparse usage guidance. It is complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 11% (only pql has a schema description), but the description compensates by explaining every parameter: defaults, ranges, syntax, and semantics. It even clarifies field-name quirks like using `project` rather than `project_id`.
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 clear verb+resource: 'List work items with optional PQL filtering.' It also explains scope options (workspace-wide vs. project-specific), distinguishing this from more specific list tools like list_archived_work_items or list_cycle_work_items.
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 context on when to use workspace-wide vs. project-scoped listing and provides a concrete workflow tip: call the relevant list_* tool first to resolve UUID fields. However, it does not explicitly name alternatives (e.g., search_work_items) or provide exclusion criteria, so it stops 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.
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 discloses the behavioral constraint that description text is not searched, specifies exact match fields, and states the return type. However, it does not explicitly mention read-only safety, pagination, or permission requirements, but for a search tool the disclosed behavior is substantial.
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 front-loaded with a one-sentence purpose, immediately followed by an alternative usage, then a structured Args list and Returns. No fluff; each sentence provides useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters all explained, an explicit usage alternative, and a stated return object, the description is complete for a search tool. The presence of an output schema means return structure is already defined elsewhere.
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%, and the description fully compensates with a clear Args list. Each parameter (query, expand, fields, external_id, external_source, order_by) gets a meaningful explanation, including behavior like prefix '-' for descending order.
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 'Search work items by text across a workspace' with a specific verb, resource, and scope. It also specifies the search fields (name, sequence id, project identifier) and distinguishes itself from list_work_items, which is used for structured filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to use list_work_items with a PQL expression for structured filtering, and implies this tool is for free-text search. This provides clear guidance on when to use this tool versus an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains partial updates, immutable fields, display_name re-slugging and uniqueness, is_required forcing default_value empty, and options behavior (edit vs add). This is rich, non-obvious behavioral context beyond what the schema or annotations would convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise summary line, a critical warning, a clear Args list, and a Returns line. Each parameter explanation is short but information-dense. No unnecessary words or repetition, making it easy to scan and parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 10-parameter mutation tool with an output schema. The description covers all parameters, key constraints (partial updates, immutable fields, field interactions), and return type. It gives enough context for correct invocation without needing additional details like permissions (not expected here). The presence of an output schema means return format needs no further elaboration.
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%, requiring the description to compensate. It does so thoroughly: every parameter is explained with meaning beyond type, e.g., display_name's re-slugging/uniqueness, relation_type's allowed values and condition, options' edit-vs-add semantics, and constraints on default_value and is_required. This greatly exceeds the minimal schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Update a customer property', using a specific verb and resource. It clearly distinguishes this tool from sibling tools like update_work_item_property and update_customer by explicitly naming 'customer property'. The partial-update semantics ('Only the fields you pass are changed') further clarify its 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 when-not guidance: 'property_type, is_multi and settings cannot be changed after creation — delete and recreate the property instead.' This tells the agent to avoid this tool for immutable fields and offers an alternative action. However, it does not name specific alternative tools (e.g., delete_customer_property/create_customer_property), 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does well: it explains grouping behavior, supported group_by values, the requirement for sub_group_by, and the return format including key types (UUIDs, strings, ISO dates, 'None'). This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with clear sections (overview, usage, Args, Returns). Every sentence adds value, and the structure makes it easy to scan. Length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description explicitly documents return fields and their formatting, covering edge cases like 'None' for unset values and UUID vs string keys. This makes the tool fully understandable without external references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, but the description fully compensates by explaining pql filters with examples, listing all supported group_by values, and noting that sub_group_by requires group_by. It adds substantial meaning beyond 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?
Description clearly states the tool counts work items across the workspace with optional grouping, using a specific verb (count) and resource (work items). It distinguishes from siblings like list_work_items by emphasizing aggregation without fetching full payloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use for analytics questions like 'how many urgent items?' and 'distribution by state?' and notes the benefit of not fetching full work item payloads, implying a contrast with list/search tools. This provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It explains the two modes (full vs brief), including payload size implications and the exact return structure, giving the agent a complete picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose, a clear usage directive, and tersely documented args/returns. Every sentence earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple one-parameter tool, the description covers all necessary information: purpose, usage context, parameter options, and return format. It is fully self-contained and does not rely on external schemas beyond what's already provided.
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?
While the schema merely lists an enum with default, the description adds rich semantics: it defines what 'full' and 'brief' return, including content details and payload trade-offs. This fully compensates for the 0% schema description 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 'Return the Plane Query Language (PQL) syntax reference,' identifying the specific resource and action. It also distinguishes itself from sibling tools by focusing solely on PQL reference, not on any other operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this when composing the `pql` filter for' and lists the exact sibling tools that require it, providing clear when-to-use guidance. No alternatives are mentioned because this tool is unique, but the context leaves no ambiguity.
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 the full burden of behavioral disclosure. It discloses pagination behavior, the precise meaning of the cursor parameter, the per_page range and default, and the response envelope structure (results, total_count, next_cursor, next_page_results). It also clarifies that work items are not included, preventing false expectations. This is comprehensive 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 well-structured with a clear one-line summary followed by a brief domain clarification and then organized Args/Returns sections. Every sentence adds value: the alternative-tool note prevents misuse, and the parameter explanations are brief yet precise. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (paginated listing with filters and cursor) and the presence of an output schema (which describes the response items), the description provides all necessary context: usage, pagination mechanics, parameter semantics, and response envelope. There are no significant gaps that would impede an agent from correctly selecting and invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must fully compensate. It explains every parameter: customer_id is a UUID, query filters by name containing text, cursor is the prior response's next_cursor (omit for first page), and per_page has a range of 1-1000 with default 1000. This far exceeds the schema's bare property definitions and gives the agent everything needed to invoke the tool correctly.
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: 'List a customer's requests (paginated).' It further clarifies the domain by defining what a customer request is and explicitly differentiating from list_customer_work_items, which is the correct tool for reading work items. This leaves no ambiguity about the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance by stating that work items addressing a customer request are read via list_customer_work_items, not from this endpoint. It also gives clear pagination usage instructions: 'page again while next_page_results is true,' which tells the agent exactly how to iterate through results. This is strong alternative and usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It fully discloses return types (image vs string), size limits (5 MB images, 1 MB text), error conditions (ValueError), and even explains why certain formats are unsupported (missing extraction libraries). This is exemplary transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into logical sections (supported, unsupported, args, returns, raises) and every sentence adds value—no fluff or repetition. It's longer than many but each detail is necessary for correct use.
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 moderate complexity (format handling) and the absence of annotations and output schema, the description provides complete guidance: supported and unsupported types, return formats, size limits, and exception behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does. Each parameter is described as 'UUID of the project/work item/attachment', adding meaning beyond the bare type='string' in the schema. This fully covers parameter intent.
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 ('Fetch an attachment's content') and clarifies the LLM-focused purpose. It explicitly distinguishes itself from the sibling tool get_work_item_attachment_download_url by directing unsupported file types there.
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 clearly delineates when to use this tool (for images and text files) and when to use the alternative get_work_item_attachment_download_url for unsupported types. Supported and unsupported lists make the decision straightforward.
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 full burden. It discloses that the tool may create the type if missing, handles both workspace- and project-level modes, blocks project-level creation in workspace-owned mode and imports instead, enables project work item types feature if off, and performs exact case-sensitive whitespace-stripped matching without duplication. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an initial summary, bullet points for mode behavior, a note on matching, a clear preference statement, and labeled Args/Returns sections. Every sentence adds value, no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a complex orchestration tool with no annotations, the description is remarkably complete. It covers possible side effects (creation/import/feature enabling), edge cases (exact matching, blocked creation), the return value (WorkItemType with id), and how to use the result. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides an Args section explaining both parameters: project_id is 'UUID of the project the type must be usable in' and name is 'Work item type name, e.g. Epic or Initiative.' This fully compensates 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 opens with a specific verb and resource: 'Find a work item type by name for a project, create it if missing, and guarantee it is usable inside that project.' It clearly distinguishes this from sibling tools by positioning it as a convenience wrapper over get_workspace_features, list_work_item_types, create_work_item_type, and import_work_item_types_to_project, and by stating its use case: resolving type_id before create_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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it: 'Use this to resolve the type_id for a typed work item such as an Epic or Initiative before calling create_work_item(type_id=...)' and provides an explicit alternative: 'Prefer this over manually combining...' It also explains the automatic mode handling, so the caller knows they don't need to determine workspace vs project-level behavior.
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:

[![plane-mcp-server-adapter MCP server](https://glama.ai/mcp/servers/leigangzhang/plane-mcp-server-adapter/badges/card.svg)](https://glama.ai/mcp/servers/leigangzhang/plane-mcp-server-adapter)

Score Badge

Copy to your README.md:

[![plane-mcp-server-adapter MCP server](https://glama.ai/mcp/servers/leigangzhang/plane-mcp-server-adapter/badges/score.svg)](https://glama.ai/mcp/servers/leigangzhang/plane-mcp-server-adapter)

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/leigangzhang/plane-mcp-server-adapter'

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