ado-workflows-mcp

by grimlor

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

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

Latest release: v0.12.0
Disambiguation4/5
Most tools have clearly distinct purposes, especially the PR and work item operations. However, the context management tools (set, clear, get status, discover, list) are numerous and could be confusing, though they perform different actions.
Naming Consistency4/5
Naming predominantly follows a verb_noun pattern in snake_case, but there is inconsistency between using 'pr' (add_pr_label, list_pr_reviewers) and 'pull_request' (abandon_pull_request, complete_pull_request). This mixing is minor but noticeable.
Tool Count2/5
45 tools is excessive for the apparent scope. Many tools are redundant (e.g., three comment posting tools) and the context management could be streamlined. The count feels bloated and increases cognitive load.
Completeness4/5
Core PR and work item lifecycles are well-covered, including creation, updates, reviews, and linking. Minor gaps exist (e.g., no delete work item), but the overall surface is rich. The analytics tools add valuable capabilities.
Average 3.9/5 across 45 of 45 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on May 5, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It lacks disclosure of side effects (e.g., triggers CI, permissions required) and only describes the creation action without 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with Args section and bullets. Not overly verbose, though the parameter list could be tightened slightly. Front-loading the main action is effective.
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 7 parameters and no annotations, the description covers parameters thoroughly. However, missing behavioral aspects like error conditions, required permissions, and side effects. Output schema exists, so return values are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds meaningful context for each parameter: branch formats, defaults, optionality, and purpose (e.g., 'working_directory for context resolution', 'work_item_ids to link'). This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new pull request') and resource ('via Azure DevOps SDK'), with a brief summary of how it works. However, it does not differentiate from sibling tools like 'complete_pull_request' or 'update_pull_request'.
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 use this tool versus alternatives. The description only states what it does, not when it should be chosen over other PR-related tools like 'update_pull_request' or 'complete_pull_request'.
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 provided, so description should fully disclose behavior. It mentions it's a list operation and returns summaries, but does not declare it as read-only, discuss error behavior, or mention side effects. States 'No ADO connection needed' adds some context.
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?
Two clear sentences of introduction followed by a structured Args section. Concise without wasted words. However, the contradiction with schema regarding optionality is a clarity issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 0% schema coverage, the description should provide more context (e.g., error conditions, read-only nature, repository prerequisites). It covers parameters and a basic environment hint but leaves significant gaps for a tool with 4 required fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds meaning for each parameter (e.g., repo_path is absolute path, authors optional, since date format). However, it contradicts the input schema by labeling authors and since as 'optional' when schema lists them as required. This inconsistency undermines reliability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists git commits from a local repository and specifies the fields returned (sha, message, author, date, repo name). No sibling tool does exactly this, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for local repositories (no ADO connection) but does not explicitly state when to use this tool vs alternatives or provide exclusion criteria. Missing guidance on prerequisites like repo existence.
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 provided, and the description does not disclose any behavioral traits beyond the basic action, such as side effects, permissions, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary words, directly stating the purpose and 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?
Despite having an output schema, the description is too sparse, lacking context about the return value or any behavioral implications.
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 minimal meaning by explaining pr_url_or_id and working_directory, but with 0% schema coverage, more detail would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 on a PR,' with a specific verb and resource, distinguishing it from siblings like add_pr_label and remove_pr_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 on when to use this tool versus alternatives (e.g., add_pr_label or remove_pr_label) or any context about 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, the description must disclose behavioral traits. It only states the action without mentioning side effects (e.g., if label already exists), idempotency, permissions, or rate limits. This leaves the agent uninformed about safe usage.
Agents need to know what a tool does to the world before 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 three short sentences, front-loading the main action. Every sentence adds 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?
While the output schema exists (not shown), the description lacks behavioral context such as whether labels must pre-exist, idempotency, or relationship to list_pr_labels. The explanation of working_directory is insufficient for complete understanding.
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 description must explain parameters. It provides basic explanations: pr_url_or_id format, name meaning, and working_directory as optional path. However, 'context resolution' for working_directory is vague, and no further details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Add a label/tag to a PR,' using specific verb and resource. It distinguishes from sibling tools like remove_pr_label (removes) and list_pr_labels (lists).
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 use this tool versus alternatives (e.g., add_pr_reviewer, create_pull_request). Does not specify 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose whether the tool is read-only, requires specific permissions, or has any performance implications. It solely states the action without 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 exceptionally concise: two sentences with no wasted words. It front-loads the purpose and immediately specifies 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?
For a tool with only 2 parameters and an existing output schema, the description covers the basics but omits usage context and behavioral notes. It is minimally sufficient but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by explaining that pr_url_or_id can be a full URL or numeric ID, and working_directory is optional for context resolution. However, it does not elaborate on format constraints or the nature of 'vote details,' leaving some gaps 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 reviewers on a PR with vote details,' specifying the verb (list) and resource (reviewers on a PR). It is distinct from sibling tools like add_pr_reviewer and remove_pr_reviewer, and no ambiguity exists.
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_pr_review_status or analyze_pending_reviews. The description lacks any contextual hints for 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, and the description only states that the tool removes a reviewer, without detailing side effects such as required permissions, error handling for non-existent reviewers, or the impact on PR review state.
Agents need to know what a tool does to the world before 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, containing one sentence for the purpose and a brief bullet-style list of arguments with no redundant 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 tool's simplicity and the presence of an output schema, the description covers the essential parameters and action. However, it lacks behavioral context such as return values or potential errors, which would be helpful 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?
Although the input schema has 0% description coverage, the description explains each parameter: pr_url_or_id as a full URL or numeric ID, reviewer_id as an Azure DevOps identity GUID, and working_directory as an optional path. This adds meaning beyond the schema but lacks constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove a reviewer from a PR', specifying the verb, resource, and context, distinguishing it from sibling tools like add_pr_reviewer and list_pr_reviewers.
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_pull_request or remove_pr_label), nor are there any preconditions or exclusions 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 full responsibility. It only states the basic action without disclosing behavior on missing labels, idempotency, side effects, or error conditions. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence followed by three parameter lines. No redundant information. Front-loaded with purpose. Every element 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?
Output schema exists, so return values are covered. However, the description lacks behavioral context (error handling, idempotency, permissions) and does not explain how the 'working_directory' parameter affects execution. Incomplete for an agent to use safely.
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 adds basic semantics: 'A full PR URL or numeric PR ID', 'Label name to remove', 'Optional path for context resolution.' This is adequate but minimal, lacking format details 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?
Description clearly states 'Remove a label from a PR.' The verb 'Remove' and resource 'label from PR' are specific and unambiguous. It distinguishes from sibling 'add_pr_label'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (removing a label) but provides no explicit when-to-use or when-not-to-use guidance. It does not compare with alternatives like 'add_pr_label' or other removal 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the mutation ('adds a reviewer') but lacks details on side effects, permissions required, or what happens on duplicate reviewer additions.
Agents need to know what a tool does to the world before 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 one-line purpose followed by a clear list of arguments. Every element is meaningful, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While parameter descriptions are provided, the tool is a mutation with no annotations, and the description omits usage guidelines and behavioral traits (e.g., permissions, side effects). The presence of an output schema (not shown) reduces the need to explain return values, but overall the description is minimally 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?
The schema has 0% description coverage, so the description compensates well by explaining each parameter's meaning and expected format (e.g., 'Azure DevOps identity GUID', 'full PR URL or numeric PR ID'). This adds significant value over 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 ('add a reviewer') and the target resource ('to a PR'), which distinguishes it from sibling tools like 'remove_pr_reviewer' and 'list_pr_reviewers'.
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., when to add vs. remove a reviewer) or any prerequisite conditions (e.g., PR must exist, user must have permissions).
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 full behavioral disclosure. It mentions enrichment with staleness detection but does not clarify what that entails, nor does it indicate if the tool is read-only, requires authentication, or has 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: two short paragraphs and an args list. No redundant sentences. The purpose is front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 (3 optional params, output schema exists), the description covers main behavior and filtering. However, it lacks guidance on context dependencies (e.g., whether set_repository_context is needed) and does not mention the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description includes an Args section with brief explanations (e.g., max_days_old: 'Exclude PRs older than this many days'). This adds meaning beyond raw schema, though explanations are minimal (e.g., 'context resolution' is 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 discovers PRs needing review attention, lists active PRs, filters by age and creator, and enriches with staleness detection. This distinguishes it from sibling tools like list_pull_requests and analyze_pr_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 usage for review prioritization but does not explicitly state when to use this tool versus alternatives like list_pull_requests or analyze_pr_comments. No exclusions or when-not-to-use 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?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature or side effects. It only describes the return value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences for purpose and usage, followed by a clear parameter explanation. It is well-structured and front-loaded with the main functionality.
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 presence of an output schema (not seen but known), the description adequately covers return values and one optional parameter. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains the single optional parameter 'working_directory' as 'path for context resolution', adding meaningful context beyond the schema type.
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 the identity of the authenticated user' and specifies it returns display name and GUID, making the purpose specific and distinct from sibling 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?
It mentions use cases like 'self-praise filtering, commit attribution, and permission checks' but does not explicitly state when not to use or provide alternatives. However, no other sibling tool serves this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It implies a read-only batch operation with full field data, but does not disclose rate limits, pagination, batch size constraints, or authentication requirements. Lack of behavioral detail beyond basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (one sentence + args list), front-loaded with the primary purpose. Every sentence adds value with no redundancy. Structured with clear parameter references in args format.
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?
With output schema existing, return format is covered. However, for a batch tool, missing info on maximum batch size, error handling for invalid IDs, or behavior when items not found. Adequate for basic use but gaps for robust selection.
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 description must clarify parameters. It provides brief but helpful definitions: project name, work_item_ids as numeric list, working_directory as optional path. Adds meaning beyond schema types and required status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Batch-fetch multiple work items by ID with full field data,' specifying verb (batch-fetch), resource (work items by ID), and scope. Distinguishes from siblings like get_work_item (single) and query_work_items (query-based).
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 purpose suggests batch use, it does not mention when to prefer get_work_item for single items or query_work_items for filtering. Missing exclusions or context.
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 behavioral traits such as required permissions, idempotency, or whether it modifies existing data. For a creation tool, this lack of transparency is a 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 purpose, and includes a clear list of arguments. Every sentence adds value; no redundant 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 description covers the tool's action and key parameters but does not mention output schema or behavioral context (e.g., whether it requires an existing PR context, rate limits). Given the presence of an output schema and siblings, it is somewhat lacking.
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?
Despite 0% schema description coverage, the description adds meaning: pr_url_or_id is 'a full PR URL or numeric PR ID', comment_text is 'Comment body text', status is described with default, and working_directory as 'optional path for context resolution'. This significantly clarifies the parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Post a new comment thread to a PR' with a specific verb and resource. It distinguishes from siblings like 'reply_to_pr_comment' and 'post_rich_comments' by focusing on creating a new thread.
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 use this tool versus alternatives like 'reply_to_pr_comment' or 'post_rich_comments'. The description lists parameters but does not provide explicit context 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 only states the basic action of changing the target branch, but does not disclose side effects (e.g., impact on reviews, approvals, or CI status), permissions required, or error conditions (e.g., if target branch doesn't exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with a single sentence for the main action and a clean bullet list for parameters. Every piece of information earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (not shown), return value details are not required. However, the description lacks context on when the operation might fail or what happens to the PR after retargeting. For a simple mutation, this is minimally adequate but could be more informative.
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 description explains all three parameters: pr_url_or_id ('A full PR URL or numeric PR ID'), target_branch ('New target branch name'), and working_directory ('Optional path for context resolution'). This adds 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 clearly states 'Change the target branch of an existing PR,' specifying the verb (change) and resource (target branch of a PR). This distinguishes it from siblings like 'update_pull_request' which is more generic, and 'create_pull_request' or 'abandon_pull_request'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'update_pull_request' or 'set_pr_draft_status'. There is no mention of prerequisites (e.g., PR must be open, user must have write access) 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 only states the action and arguments, without disclosing behavior like idempotency (what if already in target state?), authorization needs, 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 with a single purpose sentence and a bulleted list of args. No fluff, 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered. However, the description lacks behavioral context (e.g., error handling, state change confirmation) and does not fully guide an agent on typical use cases or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning by explaining each parameter: pr_url_or_id as 'full PR URL or numeric PR ID', is_draft with True/False mapping, working_directory as optional. However, further details (e.g., URL format, context resolution) are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action: 'Toggle a PR between draft and published state.' It clearly identifies the resource (PR draft status) and the verb (toggle), distinguishing it from siblings like 'update_pull_request' which handles other fields.
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 toggling draft status, but lacks explicit guidance on when to use vs alternatives (e.g., update_pull_request) or prerequisites like the PR existing. No exclusions or when-not-to-use 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 provided, so description carries full burden. It only mentions 'Update' without explaining side effects, permissions, idempotency, or constraints (e.g., PR must be open). The term 'context resolution' for working_directory is vague.
Agents need to know what a tool does to the world before 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-loading the main action in the first sentence, followed by a clear bullet list of arguments. 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?
With 5 parameters and no annotations, the description explains each param but lacks details on return value, error conditions, or behavioral nuances (e.g., whether at least one of title/description must be provided). 'working_directory' remains ambiguous.
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 description compensates well: it explains each parameter's purpose, including the meaning of pr_url_or_id, optional title/description, working_directory for context, and work_item_ids for linking. However, could be more detailed on 'context resolution'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates title and/or description of an existing PR, with a specific verb and resource. It distinguishes from sibling tools like create_pull_request, complete_pull_request, and set_pr_draft_status.
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 use this tool versus alternatives such as retarget_pull_request or set_pr_draft_status. The description lacks explicit context selection 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?
No annotations exist, so the description carries full burden. It discloses some behavioral traits like configurable merge strategy and options to delete source branch or bypass policies, but lacks details on side effects (e.g., commit creation, conflict handling) and overall impact.
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 clear first sentence followed by a parameter list. Each line earns its place; 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?
Given 8 parameters and a merge operation, the description adequately documents each parameter but lacks overall behavioral context (e.g., effect on repository, authorization needs). An output schema exists but its content is unknown.
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 provides meaningful comments for each parameter (e.g., enum values for merge_strategy, condition for bypass_reason). This compensates well for the schema gap, though some defaults are already in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Complete (merge) a PR with configurable merge strategy.' This is a specific verb+resource combination that distinguishes it from siblings like create, abandon, or update PR tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as update_pull_request or abandon_pull_request. The description only lists parameters without context on 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?
Without annotations, the description only indicates a read operation (getting identity) but does not disclose any side effects, permissions, rate limits, or error conditions. It is minimal in behavioral 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 with a clear purpose statement and well-structured parameter docs. No extraneous information, and the most important details are 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 that an output schema exists, the description adequately covers return fields. However, it lacks information about potential errors or prerequisites (e.g., the PR must exist). Still, it is fairly complete for a simple getter.
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?
Despite 0% schema description coverage, the description provides clear parameter explanations: 'pr_url_or_id: A full PR URL or numeric PR ID' and 'working_directory: Optional path for context resolution', adding 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 'Get the identity of a PR's creator' and lists the specific fields returned (display name, GUID, email), making the purpose unambiguous and distinct from siblings like 'get_pull_request' which may return full PR details.
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 such as 'get_pull_request' which may also include author information. The description does not mention preferred use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral transparency. It explains the parameters and indicates that 'working_directory' is for context resolution, but does not disclose potential side effects, error conditions, permissions, or behavior if the thread does not exist.
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 one-sentence summary followed by a structured 'Args' block. It is front-loaded with purpose. The length is appropriate, though the 'Args' block could be integrated into prose 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 tool has an output schema (not shown) so the description does not need to explain return values. However, it lacks mention of prerequisites (e.g., thread must exist, user permissions) or error conditions. For a straightforward tool, the description covers core functionality but leaves some context 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?
Despite 0% schema description coverage, the description's 'Args' section adds meaning beyond parameter names: it clarifies that 'pr_url_or_id' accepts a full URL or numeric ID, 'thread_id' must be an existing thread, and 'working_directory' is optional. This significantly aids parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Reply to an existing comment thread' and 'Adds a reply to a specific thread on a PR', using a specific verb ('reply') and resource ('PR comment thread'). This clearly distinguishes it from sibling tools like 'post_pr_comment' which seem to create new threads.
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 provide explicit guidance on when to use this tool versus alternatives. It implies usage for replying to existing threads but does not mention when not to use it or list alternative tools like 'post_pr_comment' for new threads.
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 states the basic action without disclosing side effects, permissions, or reversibility. Minimal behavioral detail beyond the 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 front-loaded purpose and a clean Args block. Every sentence adds 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 simple tool with an output schema and no annotations, the description is adequate but lacks details on side effects or prerequisites (e.g., permissions). It covers the basics but leaves gaps for an agent to fully understand implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning by explaining pr_url_or_id as a full URL or numeric ID, and working_directory as optional path for context resolution. However, 'context resolution' is vague, and no other constraints or formatting are described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'abandon (close without merging) an existing PR,' using a specific verb and resource. It distinguishes from sibling tools like complete_pull_request (merge) and update_pull_request (modify).
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 for closing a PR without merging. It provides clear context but does not explicitly exclude alternatives or provide when-not-to-use guidance. Siblings like complete_pull_request help differentiate.
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 states 'create' and mentions hierarchy linking via parent_id, but does not disclose permissions, validation behavior, side effects, or rate limits. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, followed by a clean args list. It is concise and contains no redundant information, though the parameter explanations could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 5 parameters, the description covers the creation purpose and all parameters. Output schema exists, so return value details are not needed. It does not mention error scenarios or prerequisites, but is generally complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining all 5 parameters, including examples for work_item_type and clarifying parent_id's role and fields as a dictionary. However, it lacks constraints on which field names are valid or case sensitivity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 work item of any type', using a specific verb and resource. It distinguishes itself from sibling tools like clone_work_item and update_work_item, which have different purposes.
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 creating new items but does not explicitly state when to use this tool versus alternatives like clone_work_item (for copying) or update_work_item (for modifying). 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.
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 return metadata structure (name, reference name, type, required), indicating a read-only operation with no side effects. However, it does not mention authentication, rate limits, or error conditions, but the information is sufficient for safe invocation.
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 three clear sentences. It front-loads the purpose and then lists parameters. There is no superfluous text. A slight improvement would be to integrate the parameter descriptions more naturally, but 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?
Given the presence of an output schema (not shown), the description adequately covers the return fields. However, it lacks information about potential errors, pagination, or prerequisites beyond the parameters. For a simple metadata-listing tool, this is minimally sufficient but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful explanations for all three parameters, including an example for work_item_type, which compensates for the schema's 0% description coverage. However, it incorrectly labels working_directory as 'Optional path' while the schema requires it, creating inconsistency. This error reduces the value of the added semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Discover available fields for a work item type') and resource ('fields for a work item type in a project'), distinguishing it from sibling tools like get_work_item or get_work_items which retrieve entire work items. The verb 'Discover' and the return details (name, reference name, type, required) add specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when field metadata is needed, but it does not explicitly state when to use this tool over alternatives or when not to use it. No alternatives are mentioned. The context is implied by the tool's name and description, but lacks 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?
No annotations are provided, so the description must fully disclose behavior. It describes reading work items but does not explicitly state read-only status, side effects, or constraints like rate limits. The behavior is implied but not 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, with a brief intro, return fields listing, and parameter list. Every sentence adds value, and the purpose 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?
With an output schema present, the description need not detail return values. It covers the required parameters and basic behavior. However, it could clarify 'enriched data' and provide examples of effort tracking fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains each parameter in the Args block: project as 'Azure DevOps project name', wiql as 'WIQL query string', top and working_directory with opt semantics. This adds meaning beyond the schema, though more detail on WIQL syntax would help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 queries work items via WIQL and returns enriched data with specific fields (id, title, state, type, effort tracking). This distinguishes it from siblings like get_work_item or get_work_items by emphasizing custom query capability.
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 get_work_items or clone_work_item. The description lacks context for selecting WIQL-based queries over direct fetches.
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 effectively discloses the behavioral traits: it fetches all threads, categorizes by status, and extracts author statistics. It implies a read-only operation with no destructive side effects, which is sufficient for an analysis tool. However, it could be clearer about potential implications like rate limits or performance.
Agents need to know what a tool does to the world before 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 three sentences and a parameter list, no wasted words. It front-loads the primary action and then details the parameters. Ideal for quick parsing by an AI agent.
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 existence of an output schema (not provided but known), the description does not need to detail return values. It adequately covers the tool's operation and parameters. However, it lacks information on error handling or authentication requirements, which could affect completeness in some contexts.
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 both parameters: 'pr_url_or_id' is explained as a full PR URL or numeric PR ID, and 'working_directory' is described as an optional path for context resolution. Since the schema has 0% description coverage, this provides necessary clarity. It would benefit from examples or format constraints.
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 analyzes all comment threads on a PR, categorizing by status and extracting author statistics for a structured overview. This differentiates it from tools like 'list_pr_reviewers' or 'get_pr_review_status', but does not explicitly compare to 'analyze_pending_reviews', which might have overlap. The purpose is specific and actionable.
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 structured overview of PR comments, but lacks explicit guidance on when to use this tool over alternatives. It does not mention when not to use it or provide exclusions, leaving the agent to infer context 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?
With no annotations provided, the description carries the full burden. It reveals that it scans directories, extracts ADO remote metadata, and selects the best match, but does not explain how 'best match' is determined, whether network access is needed, error handling, or output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences plus an args section. It front-loads the purpose but could be slightly tighter without losing clarity.
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 a simple tool with one optional parameter and an output schema, the description adequately covers the core functionality. However, it omits details on error handling and the exact matching logic, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description compensates by explaining the 'working_directory' parameter as a path defaulting to the current working directory. This adds meaningful context beyond the schema's null default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it discovers Azure DevOps repositories from local git remotes by scanning the working directory and selecting the best match. This distinguishes it from the sibling 'discover_all_repositories', which likely fetches all repositories remotely.
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 local scanning usage but does not explicitly specify when to use this tool versus alternatives like 'discover_all_repositories' or 'clear_repository_context'. No prerequisites or contexts are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the core behavior—creating context from input—but does not disclose side effects, permissions, or whether it modifies state. The description is transparent about the main action 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: two sentences followed by parameter explanations. It is front-loaded with the main purpose and avoids redundancy. Every sentence adds value, and the structure is 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?
Given the tool has two parameters, no annotations, and an output schema exists, the description is reasonably complete. It explains both parameters and the general behavior. The output schema covers return values, so the description does not need to detail them. Minor gap: vague on what 'reusable context' means in practice.
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 adds significant meaning: it clarifies that 'pr_url_or_id' can be a full URL or numeric ID, and explains 'working_directory' as an optional path for context resolution. This goes well beyond the schema's basic type 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 states 'Create reusable PR context from a URL or numeric ID' and explains it parses PR URLs or resolves numeric IDs using cached context. The verb 'create' and resource 'PR context' are specific, and the tool is clearly differentiated from siblings like 'establish_work_item_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 does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for setting up context before other PR operations, but there are no when-not conditions or mentions of alternatives. The guidance is adequate but 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 behavioral disclosure burden. It accurately describes a read operation (Retrieve) with no side effects, but lacks details on permissions, error conditions, or rate limits. It does not contradict annotations (none exist).
Agents need to know what a tool does to the world before 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 purpose and two brief parameter descriptions. No wasted words, and the structure 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?
The output schema exists, so return values need not be described. The description covers the key data returned (reviewers, labels, work items). It could mention error handling or that it works with Azure DevOps (inferred from sibling names), but it is largely complete for a retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning to both parameters: 'pr_url_or_id: A full PR URL or numeric PR ID' clarifies the accepted formats, and 'working_directory: Optional path for context resolution' hints at its purpose. This adds value beyond the schema's type-only 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 clearly states 'Retrieve full PR metadata including reviewers, labels, and work items', which specifies the verb (Retrieve) and the resource (full PR metadata). This distinguishes it from sibling tools like get_pr_author or get_pr_review_status that target specific subsets.
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 getting comprehensive PR details, but it does not explicitly state when to use this tool over alternatives (e.g., get_pr_author, get_pr_file_changes) or provide exclusion criteria. No guidance on context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It describes return fields (id, title, status, web_url) and parameter effects, but does not explicitly state it is read-only or disclose side effects, auth requirements, or rate limits. It adds value but is not fully 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 with a clear one-line purpose, a return summary, and a parameter list. It is concise (5 lines plus list) and front-loaded with the core action, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 required parameters), the presence of an output schema, and no annotations, the description covers purpose, parameters, and return type summary adequately. Missing pagination or ordering details, but these are acceptable for a listing tool with an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists all 7 parameters in an Args section with brief explanations (e.g., 'Optional GUID', 'PR status filter (default "all")'). This adds significant meaning beyond the bare schema types and 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 starts with 'List pull requests matching search criteria,' which is a specific verb+resource combination. It clearly distinguishes from siblings like 'get_pull_request' (single PR) and 'create_pull_request' (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 description implies usage by stating it lists pull requests with filters, but lacks explicit guidance on when to use versus alternatives. There is no mention of when not to use or why to choose this over similar listing tools among the 44 siblings.
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 provided, so the description carries the burden. It describes the output and operation but does not disclose any behavioral traits like idempotency, side effects, or auth requirements. It is adequate but not 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 brief and front-loaded, starting with the main purpose, then return format, then parameter details. Every sentence adds value 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 has an output schema, the description does not need to explain return values in depth, yet it does. It covers the core functionality, return structure, and parameters. Minor omissions like error handling or pagination are acceptable for a simple list 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, and the description adds clear meaning to both parameters: pr_url_or_id (full URL or numeric ID) and working_directory (optional path for context resolution). This significantly 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 clearly states it lists files changed in a PR with iteration metadata. The return format and key fields are specified. It is distinct from sibling tools like get_pr_file_contents (file content) and get_pull_request (PR details).
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 mentions it uses the latest iteration, providing some context but no explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool detects stale approvals and aggregates PR details, votes, and commits. It does not mention side effects, but as a read-only operation, this is acceptable. The Args list adds transparency about parameters. A score of 4 is appropriate given the lack 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: two sentences for the purpose and an Args list. It is front-loaded with the key value proposition. Every sentence 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.
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 (comprehensive review status) and the presence of an output schema, the description adequately covers what the tool retrieves: PR details, votes, commits, and stale approvals. It does not mention error handling or limitations, but for a read tool, this is sufficient. A score of 4 reflects good coverage without unnecessary details.
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% coverage, so the description must compensate. It explains 'pr_id' as 'Pull request ID' and 'working_directory' as 'Optional path for context resolution,' adding meaning beyond the bare schema types. This is good, but could be more detailed (e.g., expected format for working_directory).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Get comprehensive review status with vote invalidation detection.' It specifies fetching PR details, reviewer votes, commit history, and stale approvals. This distinguishes it from siblings like get_pull_request (basic PR info) and analyze_pending_reviews.
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 this tool is for deeper analysis than basic PR status, mentioning 'stale approvals that the raw API buries.' However, it does not explicitly state when to use this tool versus alternatives like get_pull_request or analyze_pending_reviews, leaving the agent without 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?
No annotations are provided, so the description bears full burden. It discloses the return dict keys and context resolution behavior. However, it lacks details on error scenarios, authentication needs, or rate limits, resulting in 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 concise with a clear summary followed by a bullet-like list of parameters. Every sentence provides essential 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?
Given the presence of an output schema (covering return values) and the description's coverage of context resolution and parameter semantics, it is mostly complete. It could mention potential errors (e.g., file not found) but still provides sufficient context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant meaning: it explains that 'ref' can be a branch, commit, or tag (null=default), and that 'repository' and 'project' override context. This effectively compensates for the schema's lack of parameter 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 explicitly states 'Fetch a single file's content from any branch, commit, or tag,' which is a specific verb and resource. It distinguishes from sibling tools like get_pr_file_contents by not being limited to pull requests.
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 context resolution from a cached RepositoryContext unless explicit params are provided, giving clear guidance on when to use parameters. It does not explicitly compare to siblings, but the purpose implicitly differentiates.
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 bears full transparency burden. It discloses that children are not auto-included, but omits potential side effects (e.g., state changes, notifications) and permissions needed. The mechanism (updating iteration path) is clear, but deeper behavioral details are lacking.
Agents need to know what a tool does to the world before 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 line for purpose, one line for behavioral nuance, and a compact parameter 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?
Given moderate complexity, the description covers the core action, parameters, and a key behavioral trait (no children). It does not explain output format or error handling, but the presence of an output schema partially mitigates this. Still, for a mutation tool, more context on postconditions would be beneficial.
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 description must define parameters. It provides clear, brief descriptions for all four parameters (project, work_item_ids, iteration_path, working_directory), adding meaning beyond the schema's type-only definitions. However, it could add more detail on allowed values or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'move' and the resource 'work items to a target sprint', with the mechanism 'by updating their iteration path'. It distinguishes itself from sibling tools like 'update_work_item' and 'clone_work_item' by its specific focus on moving multiple items to a sprint.
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 notes that children are not auto-included, guiding callers to decide which IDs to move. However, it does not contrast with similar tools like 'update_work_item' or 'clone_work_item' to specify when to use this tool versus those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses enum coercion, dry_run, and filter_self_praise behavior. With no annotations, it carries full burden and does well, though it omits 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 front-loaded with purpose and structured, but the detailed dict key list and behavior notes are justified given the complexity. It is clear and well-organized.
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, parameters, and key behaviors. The output schema is separate, so that is not a gap. Minor ambiguity in 'working_directory' context resolution, but overall complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds extensive meaning beyond the schema: each comment dict key is detailed, and each parameter (dry_run, batch_size, etc.) is explained, compensating for 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 it batch-posts structured review comments with severity, type, and formatting, distinguishing it from simpler comment posting tools like post_pr_comment and post_pr_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 for batch-structured comments but does not explicitly state when not to use it or compare to sibling tools. The context from the name and detail provides implicit 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 full burden. It explains caching and skipping redundant lookups, but does not detail side effects like overwriting previous context, validation of the path, or session-level persistence. 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 very concise: two sentences plus an arguments section. It front-loads the purpose and contains no fluff. Every sentence is earned.
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 (1 parameter) and presence of an output schema, the description is mostly complete. It explains the effect and parameter adequately, though it could mention error conditions. Overall sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'working_directory' has a description in the args section ('Path to the git repository root.'), which adds meaning beyond the schema's empty type string. This compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool caches repository context by setting the working directory and caching discovery results, distinguishing it from siblings like clear_repository_context and discover_all_repositories. It uses a specific verb 'cache' and resource 'repository 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 implies that the tool should be used before operations that need repo context to avoid redundant git lookups, but it does not explicitly state when not to use it or mention alternative tools. It is clear enough for intended use.
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?
Describes that it walks the working directory for git repositories with Azure DevOps remotes. No annotations are provided, so the description carries the full burden. It does not disclose potential performance implications or side effects, but it adequately conveys the scanning 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 with two paragraphs and an Args list. Every sentence adds value, no redundancy. It is well-structured and front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's simplicity (single optional parameter), the description is complete. It covers what the tool does, when to use it, and the parameter semantics.
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 provides a clear explanation for the only parameter 'working_directory': 'Path to scan. Defaults to the current working directory when omitted.' This adds significant context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List every Azure DevOps repository discovered under the working directory.' The verb 'list' and resource 'Azure DevOps repositories' are specific. The description also distinguishes from sibling tools by specifying use in multi-repo ambiguity error scenarios.
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 says 'Use this tool when another tool surfaces a multi-repo ambiguity error to enumerate the candidate repos so an end user can disambiguate.' Provides clear context for when to use, though does not explicitly mention when not to use.
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 shoulder the burden. It only notes 'read-only', leaving out potential behavioral traits like pagination, performance, error handling, 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 extremely concise (3 sentences), front-loaded with purpose, and every word adds value. No irrelevant 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 tool's simplicity (2 params, list action) and the presence of an output schema, the description is almost complete. It could mention error cases or default behavior, but the core usage is adequately covered.
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 meaning beyond the schema (which has 0% description coverage). It clarifies that 'pr_url_or_id' accepts full URLs or numeric IDs, and explains 'working_directory' as an optional path. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List work items linked to a PR') and includes a read-only hint. This distinguishes it from sibling tools like get_work_item (generic) and PR modification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when needing work items for a PR) but lacks explicit when-not or alternative tool guidance. However, since no sibling tool duplicates this function, the clarity 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?
No annotations are provided, so the description must fully disclose behavior. It mentions the return values but does not explicitly state that it is read-only or discuss potential side effects, authentication needs, or rate limits. For a simple inspection tool, 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 three concise sentences, front-loaded with the primary purpose. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema, the description is complete. It adequately explains what the tool does and what it returns, sufficient for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no input parameters, so the schema fully covers them. The description adds meaning by explaining the output (cache state, timestamps, working directory details) beyond the schema. Baseline for zero params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects the current cached context state and lists specific return items (cache state, timestamps, working directory details). It is distinct from sibling tools like 'set_repository_context' and 'clear_repository_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 explicitly states it is useful for debugging context issues or verifying setup, providing clear context. However, it does not explicitly exclude other usage scenarios or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses partial-success semantics ('individual thread errors don't fail the entire batch'). However, it omits details about authentication, rate limits, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear headline and bulleted arguments. Every sentence serves a purpose, no redundant phrasing. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but indicated), the description appropriately avoids explaining return values. It covers the main operation, partial-success, and parameters. However, it lacks information on batch size limits or behavior when the PR does not exist.
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 compensates fully. Each parameter is explained: 'pr_url_or_id' (full URL or numeric ID), 'thread_ids' (IDs to resolve), 'status' (target, default 'fixed'), and 'working_directory' (optional path). This adds significant clarity beyond the schema's type 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 begins with 'Batch-resolve PR comment threads', clearly specifying the verb (batch-resolve) and resource (PR comment threads). This distinguishes it from sibling tools like 'post_pr_comment' and 'reply_to_pr_comment'.
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 batch resolving comment threads and mentions partial-success semantics, but it does not explicitly state when to use this tool versus alternatives like 'analyze_pr_comments' or 'post_pr_comment'. No exclusion criteria or prerequisite conditions are 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?
No annotations provided, so description carries full burden. It discloses return format (list of dicts with keys), error handling (omitted from successes, included as error entries with ai_guidance), and behavior when file_paths is None. Lacks details on auth or rate limits but covers core 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?
Description is well-structured with a short summary line, then return format, then a note about behavior, then a clear Args list. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema (though not shown), the description covers return format, error handling, and all parameters. It is complete for an agent to understand usage and behavior.
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 description must add meaning. It explains each parameter clearly: pr_url_or_id (full URL or numeric ID), file_paths (optional list), exclude_extensions (optional, case-insensitive, leading dot optional), working_directory (optional). 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?
Description clearly states 'Fetch file contents for files changed in a PR.' with specific verb and resource. It distinguishes from sibling tools like get_pr_file_changes (which likely only lists changes) and get_repo_file_content (which fetches a single file).
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?
Description explains optional filtering (file_paths, exclude_extensions) and default behavior when file_paths is None, but does not compare to alternative tools or provide explicit 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description covers iteration context auto-resolution, dry_run behavior, and comment positioning, but omits batch limits or partial failure handling.
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 bullet points and clear sections, but includes some redundant phrasing that could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential behaviors and parameters; output schema exists, so return details are less needed. Missing error handling notes, but sufficient 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?
With 0% schema coverage, the description fully compensates by detailing each comment dict key, their optionality, and explaining all parameters (pr_url_or_id, comments, dry_run, working_directory) 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 clearly states the tool posts multiple comments to a PR with optional file/line positioning, distinguishing it from single-comment sibling 'post_pr_comment' and 'post_rich_comments'.
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 the batch behavior and dry_run validation, but does not explicitly compare to alternatives like 'post_pr_comment' or state when to use batch vs single.
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 provided, but description discloses mutation behavior, the risk of wrong tenant, and the need for existing work item. Does not mention output schema behavior, but overall transparent about key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, caveat, args. Every sentence adds value. Slightly verbose with the example inline but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers inputs thoroughly but does not mention output format despite an output schema existing. Minor gap given complexity of tool and lack of schema descriptions.
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; description compensates fully by explaining each parameter in detail, including types, purpose, and an example for the fields parameter. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update fields on an existing work item' with specific verb and resource. Distinguishes from sibling tools like create_work_item, get_work_item, etc., by focusing on updating fields on an existing 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 guidance to prefer URL over numeric ID due to cross-tenant risks. Includes a caveat about unrecoverable mutations. Could explicitly mention alternatives but sufficiently covers when and how to use.
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 provided, but description fully covers behavior: clears cached results, forces fresh discovery, idempotent. Adds value beyond schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. First sentence states purpose, second adds behavioral details. Front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a parameterless tool: explains purpose, behavior, and safety. Output schema exists but needs no extra description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description adds no param info, but baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Reset cached context' and explains it clears cached discovery results. Differentiates from siblings like set_repository_context and get_repository_context_status.
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 notes idempotency and safety even when no context is set, guiding when to use. Does not explicitly mention when not to use, but context implies it's for refreshing.
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 explains the tool's behavior: resolves URL or ID, uses cached repository context for numeric IDs, and returns a structured context. It also discloses a caveat about incorrect org_url when work board and code repo are in different orgs. Missing error handling or failure modes, but overall 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 main sentence, a paragraph explaining the output, a caveat paragraph, and an Args section. It is somewhat lengthy but every sentence adds value. It is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, an output schema (not shown), and no annotations, the description covers input, output, and a notable edge case. It explains the resulting data structure (organisation, project, ID, org_url) and provides a behavior caveat. This is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions in schema). The description adds full semantics for both parameters: work_item_url_or_id ('A full Azure DevOps work-item URL or a numeric work-item ID.') and working_directory ('Optional path for repository-context resolution when using a numeric ID.'). This provides meaning beyond the type-only schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Resolve a work-item URL or numeric ID into a structured context.' It specifies the input types and what the output context carries (organisation, project, ID, org_url). This distinguishes it from siblings like get_work_item and query_work_items by focusing on context resolution.
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 guidance on when to use each input type: it advises preferring a full URL over a bare numeric ID due to potential org mismatches. It mentions the caveat about work board vs code repo. However, it does not explicitly state when not to use this tool or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavior: copies all fields, applies overrides, preserves parent link, does not close source, and warns about caveats. Output schema covers return values.
Agents need to know what a tool does to the world before 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, front-loaded purpose, then caveat, then args. Each sentence adds value with no redundancy. Appropriate 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?
Output schema exists, so return values covered. Input and behavior explained well, including caveats. Missing error conditions or handling of missing source, but overall complete for a clone 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?
With 0% schema description coverage, the description adds meaning for all three parameters: explains URL vs ID for source, optional override dict, and working directory for context resolution. Could list example field overrides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Clone a work item into a new item of the same type', which is a specific verb and resource. It clearly distinguishes from siblings like create_work_item and update_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on using URL vs numeric ID and warns about tenant resolution issues with numeric IDs. Lacks explicit when-not-to-use or alternative tools, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the behavior: what the tool returns, default values for path and recursion, and context resolution. Without annotations, this covers most behavioral aspects, though it does not mention edge cases like empty directories or performance considerations.
Agents need to know what a tool does to the world before 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 concise summary, return format note, context explanation, and a bulleted Args list. Every sentence adds value and is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 required parameters and presence of an output schema, the description covers all necessary aspects: parameter defaults, override behavior, return format, and recursion options. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: path defaults to '/', ref defaults to default branch, recursion options, and how repository/project/working_directory override context. This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists files and folders at a path on any branch, commit, or tag. It specifies the return format as a list of dicts with specific keys, and distinguishes itself from sibling tools like get_repo_file_content (which retrieves single file content) and list_commits (which lists commits).
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 explains context resolution and how to override with explicit parameters, providing clear usage guidance. However, it does not explicitly state when not to use this tool or compare to specific siblings, leaving room for slight improvement.
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 full burden. It discloses the important caveat about numeric ID resolution across tenants, but does not explicitly state the tool is read-only or has no 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 summary, a separate caveat paragraph, and a concise args list. 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 presence of an output schema, the description adequately covers the return type (WorkItemDetail with fields) and the operational context. The caveat about numeric ID resolution provides critical completeness for correct tool 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 coverage is 0%, but the description explains both parameters in detail: work_item_url_or_id as 'full Azure DevOps work-item URL or numeric ID' and working_directory as 'Optional path for repository-context resolution when using numeric ID', adding significant meaning beyond the schema's type 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 explicitly states 'Fetch a single work item by URL or numeric ID' and details the return type, clearly distinguishing it from sibling tools like get_work_items and query_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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to prefer full URL over numeric ID due to potential wrong organization resolution, and explains the working_directory parameter's role.
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:

[![ado-workflows-mcp MCP server](https://glama.ai/mcp/servers/grimlor/ado-workflows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/grimlor/ado-workflows-mcp)

Score Badge

Copy to your README.md:

[![ado-workflows-mcp MCP server](https://glama.ai/mcp/servers/grimlor/ado-workflows-mcp/badges/score.svg)](https://glama.ai/mcp/servers/grimlor/ado-workflows-mcp)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/grimlor/ado-workflows-mcp'

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