Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ado-search-mcp search for bugs related to login page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that wraps the ado-search CLI for Azure DevOps work item search and management.
Tool | Description |
| Full-text search of indexed work items and wiki pages |
| Regex pattern search across work item fields |
| List children/descendants of a work item |
| Show full content of a work item or wiki page |
| List links on a work item (live from ADO) |
| List comments on a work item (live from ADO) |
| Fetch specific work items by ID into local store |
| Create a new work item |
| Update an existing work item |
| Add a comment to a work item |
| Add a link between two work items |
| Remove a link between two work items |
Related MCP server: Azure DevOps MCP Server
Node.js 18+
ado-search CLI installed and on PATH
An initialized ado-search data directory (ado-search init && ado-search sync)
Clone and build:
git clone https://github.com/HurleySk/ado-search-mcp.git
cd ado-search-mcp
npm install
npm run buildCreate a config file (ado-search-mcp.json):
{
"dataDir": "/path/to/your/ado-search/data-dir",
"adoSearchPath": "ado-search"
}Add to your project's .mcp.json:
{
"mcpServers": {
"ado-search": {
"command": "node",
"args": ["/path/to/ado-search-mcp/dist/server.js"],
"env": {
"ADO_SEARCH_CONFIG": "/path/to/ado-search-mcp.json"
}
}
}
}The server looks for config in this order:
ADO_SEARCH_CONFIG environment variable (path to JSON config file)
ado-search-mcp.json sidecar file next to dist/server.js
ADO_DATA_DIR environment variable (data directory path only)
MIT
Add a comment to a work item
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Comment text (HTML supported) | |
| work_item_id | Yes | Work item ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only restates the action of adding a comment, without mentioning permissions, side effects, idempotency, or what happens on failure. This is a mutation tool with no additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is front-loaded and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with full schema coverage, the description is minimally adequate. However, there is no output schema and no mention of what the tool returns or what conditions might cause failure, leaving some context gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both parameters clearly, including HTML support for text. The description adds no parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a comment to a work item' uses a specific verb and resource, making the core operation unmistakable. It does not explicitly distinguish itself from sibling tools, but the sibling names are sufficiently different that ambiguity is minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: use this tool when you need to add a comment to a work item. However, there is no explicit guidance about when not to use it or how it relates to sibling tools like ado_list_comments or ado_add_link.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a link between two work items
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | Optional comment on the link | |
| link_type | Yes | Link type: related, parent, child, duplicate, duplicate-of, depends-on, predecessor, successor | |
| source_id | Yes | Source work item ID | |
| target_id | Yes | Target work item ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description carries the full burden of behavioral disclosure. It only restates the mutation implied by the tool name and does not mention idempotency, side effects, permissions, or failure behavior. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the verb and object with zero wasted words. It is appropriately sized for the simplicity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description leaves out important context such as return behavior and directional semantics for link_type (for example, whether source_id should be the parent in a parent-child link). An agent must rely on the schema's link_type list alone, which does not clarify direction or constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds no additional parameter-level meaning beyond the schema, but it does not conflict with or obscure the schema either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a link between two work items' states a specific verb (Add), a resource (a link), and the entities involved (two work items). It clearly separates this tool from the sibling ado_remove_link, so an agent can immediately understand what operation this performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives like ado_remove_link or ado_list_links. There are no conditions, exclusions, or context about when adding a link is appropriate, 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.
List children or descendants of a work item by parent ID
| Name | Required | Description | Default |
|---|---|---|---|
| parent_id | Yes | Parent work item ID | |
| recursive | No | Show all descendants, not just direct children | |
| type_filter | No | Filter by work item type (e.g. 'Bug', 'User Story') | |
| state_filter | No | Filter by state (e.g. 'Active', 'Closed') | |
| include_closed_date | No | Include closed date from state history |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. 'List' signals a read-only operation, but the description does not state defaults such as recursive=false returning only direct children, nor does it mention pagination or return format. It adds little beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler. It efficiently states the core action and resource without repeating schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description is minimally viable but incomplete. It does not mention default recursion behavior, when to apply filters, or what fields the returned list contains, so the agent must rely on schema defaults and tool naming.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only reiterates the parent_id concept and adds no new semantic meaning for recursive, type_filter, state_filter, or include_closed_date beyond the schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List'), resource ('children or descendants of a work item'), and the key required parameter ('by parent ID'). It clearly distinguishes from sibling tools like ado_list_comments and ado_list_links, which operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance. Usage is implied by the resource type, but there are no exclusions or comparisons to siblings, so the agent must infer when to choose this over ado_show or ado_list_links.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new work item in Azure DevOps
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | Area path | |
| tags | No | Semicolon-separated tags | |
| type | Yes | Work item type (Bug, User Story, Task, Epic, Feature) | |
| state | No | Initial state | |
| title | Yes | Work item title | |
| fields | No | Additional ADO fields as key-value pairs | |
| parent | No | Parent work item ID | |
| reason | No | Reason (e.g. for closing) | |
| priority | No | Priority (1=highest) | |
| iteration | No | Iteration path | |
| assigned_to | No | Assignee email or display name | |
| description | No | Description (HTML) | |
| story_points | No | Story points | |
| acceptance_criteria | No | Acceptance criteria (HTML) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It identifies the operation as creating a work item, implying a mutation, but doesn't disclose side effects, required team/project context, validation rules, or what happens on creation. It gives basic transparency but lacks behavioral depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that is efficient. It could potentially add usage/behavior details, but as written it has no waste and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but combined with a 100%-covered schema it is adequate. Missing elements include explicit mutation warning given no annotations, and guidance about which ADO project/organization context applies, but the core creation purpose is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents every parameter. The description ('Create a new work item') adds no additional parameter semantics beyond what the schema already provides, but because coverage is complete the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Create') and resource ('work item in Azure DevOps'). It is distinct enough from siblings like ado_update or ado_fetch, though it doesn't name any sibling differences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the creation action, but provides no explicit guidance about when to choose this tool over alternatives such as ado_update or ado_add_link. With many siblings, some distinction would elevate it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch specific work items by ID from Azure DevOps and add to local store
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Work item IDs to fetch | |
| include_comments | No | Fetch comments | |
| include_attachments | No | Download attachments |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It usefully discloses that fetched items are added to a local store, which is a meaningful side effect. However, it does not explain merge/overwrite behavior, failure semantics for invalid IDs, permissions needed, or whether the remote system remains untouched beyond being read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveys the action, the target resource, the source, and the side effect with no filler. The most important information is front-loaded and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple fetch operation with well-documented parameters, but it lacks explicit guidance on when to choose this tool over closely related siblings and does not describe return values or local-store update behavior. Given no output schema and no annotations, a bit more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already well-documented in the schema. The description only reinforces that IDs are the focus and does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a specific resource ('specific work items by ID'), and a clear side effect ('add to local store'). This distinguishes it from query-based siblings like ado_search and display-oriented tools like ado_show.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies this tool is for targeted retrieval when work item IDs are already known, contrasting with search/grep. However, it does not explicitly state when to prefer this over ado_show, ado_list_comments, or other siblings, leaving the selection partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regex pattern search across work item fields (title, description, comments, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| fields | No | Fields to search (default: title, description, comments) | |
| pattern | Yes | Regex pattern to search for | |
| tag_filter | No | Filter by tag | |
| area_filter | No | Filter by area path (prefix match) | |
| assigned_to | No | Filter by assignee email | |
| ignore_case | No | Case-insensitive matching | |
| type_filter | No | Filter by work item type (e.g. 'Bug', 'User Story') | |
| state_filter | No | Filter by state (e.g. 'Active', 'Closed') | |
| context_chars | No | Characters of context around each match |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the search scope and does not disclose result shape, default limits, filtering behavior, case-insensitivity, or whether snippets/context are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. However, the trailing 'etc.' is vague and slightly weakens the otherwise concise phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, no output schema, and several sibling tools to disambiguate from, a one-sentence description is insufficient. It does not explain return format, default field behavior, filtering semantics, or how this tool relates to ado_search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds little beyond echoing the 'fields' parameter and the regex concept; it does not compensate for or enhance the schema's parameter explanations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs regex pattern search across work item fields and names representative fields. It is specific enough to convey the core purpose, though it does not explicitly distinguish itself from sibling tools like ado_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used for regex-based searching within work item fields, but it gives no explicit guidance on when to prefer this over alternatives or when not to use it. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List comments on a work item (fetched live from Azure DevOps)
| Name | Required | Description | Default |
|---|---|---|---|
| work_item_id | Yes | Work item ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals that the tool performs a live fetch, which is useful, and 'List' implies a non-destructive read. However, it does not mention permissions, error behavior, or any side effects, so transparency is only partially addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler. It front-loads the action and resource, and the parenthetical 'fetched live from Azure DevOps' adds meaningful context without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool, the description plus schema is sufficient for an agent to understand what it does and how to invoke it. The only missing elements are optional details like the shape of the returned comments or pagination behavior, which are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents work_item_id fully with type, bounds, and a 'Work item ID' description, giving 100% schema description coverage. The tool description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a precise resource ('comments on a work item'), and a source ('Azure DevOps'), making the tool's purpose immediately clear. It also naturally distinguishes itself from write-focused siblings like ado_add_comment and ado_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: an agent would use this when it needs to retrieve comments for a particular work item. The phrase 'fetched live' hints that this tool should be chosen when fresh data is required, but there is no explicit when-to-use or when-not-to-use guidance or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List links on a work item (fetched live from Azure DevOps)
| Name | Required | Description | Default |
|---|---|---|---|
| work_item_id | Yes | Work item ID |
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 'fetched live from Azure DevOps', informing the agent of real-time API access and likely latency. The verb 'List' implicitly signals a read-only operation. However, it does not mention authentication needs, error behavior, or what qualifies as a 'link' (e.g., related work items vs hyperlinks).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and object, followed by a useful qualifier about live fetching. No redundant words, no repetition of schema content, and no wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, this description is mostly adequate, but it leaves ambiguity about the return shape (list of objects?) and link types. Since there are no annotations to cover safety or behavior, a little more detail—like 'returns related work items and hyperlinks'—would make the description complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the single parameter (work_item_id: Work item ID) with 100% coverage. The description adds no new parameter semantics beyond confirming the operation targets a work item. Per the calibration baseline, this is a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('links on a work item'), clearly distinguishing it from sibling tools like ado_list_comments. The 'fetched live from Azure DevOps' qualifier adds context. However, it does not explicitly differentiate from overlapping read tools such as ado_show or ado_fetch, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose this tool over alternatives like ado_list_comments, ado_show, or ado_fetch. The only hint is 'fetched live', which implies real-time data but does not explain scenarios, exclusions, or caching alternatives. An agent must infer usage purely 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.
Remove a link between two work items
| Name | Required | Description | Default |
|---|---|---|---|
| link_type | Yes | Link type: related, parent, child, duplicate, duplicate-of, depends-on, predecessor, successor | |
| source_id | Yes | Source work item ID | |
| target_id | Yes | Target work item ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool removes a link, but it does not disclose what happens if the link does not exist, whether the operation is idempotent, whether it requires special permissions, or what side effects might occur. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundant information. It is appropriately sized for a simple, well-named tool and front-loads the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive mutation tool with no annotations and no output schema, the description is too sparse. It fails to explain expected results, error conditions, whether the link_type parameter must match existing link data, or how to verify success. The agent would need external documentation or trial-and-error to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three required parameters and enumerates valid link_type values. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a link between two work items' uses a specific verb and resource, making the operation unambiguous. It also naturally distinguishes itself from the sibling tool ado_add_link, so an agent can tell them apart without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as ado_add_link or ado_list_links. There is no mention of prerequisites, directionality, or conditions under which removal is appropriate, 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.
Full-text search of indexed Azure DevOps work items and wiki pages
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| query | Yes | Search query text | |
| tag_filter | No | Filter by tag | |
| area_filter | No | Filter by area path (prefix match) | |
| assigned_to | No | Filter by assignee email | |
| type_filter | No | Filter by work item type (e.g. 'Bug', 'User Story') | |
| state_filter | No | Filter by state (e.g. 'Active', 'Closed') |
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 implies a read-only search operation but does not confirm side-effect freedom, result ordering, index staleness, pagination behavior, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word adds meaning, and it avoids repeating parameter names or schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter search tool with no output schema and no annotations, the description is minimal but sufficient for basic invocation: an agent knows to provide a query and can infer filters from the schema. However, it does not disclose what results look like, how they are ordered, or edge-case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds the 'full-text' and 'indexed' framing but does not provide meaningful parameter-level detail beyond what the input schema contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Full-text search'), the resource ('indexed Azure DevOps work items and wiki pages'), and the general scope. This helps distinguish it from siblings like ado_grep or ado_fetch, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool over alternatives such as ado_grep or ado_show. There is no mention of preferred use cases, exclusions, or conditions that would route an agent to a different sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show full content of a work item (by numeric ID) or wiki page (by path). Returns formatted markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes | Work item ID (number) or wiki page path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes the output ('Returns formatted markdown') and the read-oriented action ('show'), which implies non-mutating behavior, but it does not explicitly disclose whether the operation is read-only, whether it requires special permissions, or any failure modes. This is a moderate but not exhaustive disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the first states the operation and targets, the second states the return format. Everything present is useful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description adequately covers the input type, the two accepted forms, and the output format. It does not discuss error behavior or side effects, but for a 'show' operation this is a minor omission, so it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% coverage for the single parameter, describing item_id as 'Work item ID (number) or wiki page path'. The description repeats this information ('by numeric ID' / 'by path') without adding new semantic detail, so it meets the baseline but does not exceed what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show full content') and identifies the exact resources (work item by numeric ID, wiki page by path) and output format (formatted markdown). This clearly distinguishes it from siblings such as ado_search, ado_children, and ado_fetch by the scope of content returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you need the full content of a known work item or wiki page—but it does not explicitly state when to prefer this over sibling tools like ado_fetch or ado_search, nor does it list any exclusions. The 'by numeric ID or path' constraint provides some guidance, but no explicit alternative routing is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing work item in Azure DevOps
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | New area path | |
| tags | No | Semicolon-separated tags | |
| state | No | New state | |
| title | No | New title | |
| fields | No | Additional ADO fields as key-value pairs | |
| reason | No | Reason (e.g. for closing) | |
| priority | No | Priority (1=highest) | |
| iteration | No | New iteration path | |
| assigned_to | No | New assignee email or display name | |
| description | No | New description (HTML) | |
| story_points | No | Story points | |
| work_item_id | Yes | Work item ID to update | |
| acceptance_criteria | No | New acceptance criteria (HTML) |
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, and 'Update an existing work item' only signals mutation. It does not explain whether the update merges only supplied fields or replaces the item, whether state transitions (e.g., closing) require a reason, whether permissions are needed, or what the tool returns. For a high-impact 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 7-word sentence with no filler; the verb and object are front-loaded and every word earns its place. It reads as genuine conciseness rather than under-specification because the sentence conveys real meaning, though it is on the minimal side for a 13-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 13 parameters, no output schema, and no annotations, the description is too thin. It omits key context an agent needs: merge-vs-replace semantics, behavior on missing/empty fields, return value, and how it differs from ado_create, ado_fetch, and ado_show. The schema covers parameters, but behavioral context is entirely absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — all 13 parameters have descriptions in the schema — so the baseline is 3. The description adds no parameter-level detail, but it does not need to because the schema fully documents each field, including the nested 'fields' object.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('an existing work item in Azure DevOps'). The qualifier 'existing' implicitly separates it from create/read siblings like ado_create, ado_fetch, and ado_show, but it never names a sibling or an explicit contrast, so differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus its 11 siblings. The phrase 'existing work item' implies a modification scenario, but there are no explicit conditions, exclusions, or pointers to alternatives such as ado_create for new items or ado_fetch/ado_show for reads. This mirrors the update_drive calibration case, which scored 2 for the same gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0ado_add_commentado_add_linkado_childrenado_createado_fetchado_grepado_list_commentsado_list_linksado_remove_linkado_searchado_showado_updateScored across 12 tools
Most tools map clearly to distinct actions, but a few pairs overlap: ado_fetch and ado_show both retrieve work items by ID, and ado_search and ado_grep both search work items. The descriptions help differentiate local-store caching vs. formatted output and full-text vs. regex, but an agent could still misselect.
The consistent 'ado_' prefix helps, but the verb part is mixed: list_comments/list_links and add_link/remove_link use verb_noun, while fetch/create/update/search/show are bare verbs and children is a bare noun. This is readable but not a uniform convention.
Twelve tools is well within the ideal scope for an Azure DevOps work-item search and management server. Each tool covers a distinct operation such as searching, CRUD, comments, links, or hierarchy, so none feels like filler.
The set covers reading, creating, updating, searching, commenting, linking, and hierarchy traversal for work items. Minor gaps exist—there is no delete operation and no explicit general list/query tool—but the core workflows agents need are covered.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
