Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden of behavioral disclosure. It explains the interactive browser window, MFA inclusion, session persistence on an isolated profile, headless reuse, and explicitly states that no PAT or token is stored. This fully discloses the tool's side effects and security posture, going well beyond what the schema or name alone would convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core action and followed by concise usage guidance and behavioral notes. Every sentence earns its place: the first defines the action, the second covers usage frequency and session behavior. No redundant or filler content is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, with one optional parameter and no output schema. The description covers the full context: what it does, when to run it, how authentication persists, and the absence of stored tokens. For an authentication tool, this is complete and leaves no ambiguity about the agent's next steps or the tool's effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage for the single parameter (timeoutSeconds) is 100%, with a clear description already in the schema: 'How long to wait for sign-in (default 240s).' The tool description does not add additional meaning about this parameter, so the baseline score of 3 applies. No compensation is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Sign in to Azure DevOps by opening a VISIBLE browser window for interactive login (MFA included).' This uses a specific verb ('Sign in') and resource ('Azure DevOps'), and it is unambiguously distinct from the sibling tools, all of which are read-oriented data retrieval tools. The first sentence fully defines what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use it: 'Run this once (or whenever a tool returns AUTH_REQUIRED).' This is a clear, actionable condition that tells the agent exactly when this tool is needed versus other tools. It also implies when not to run it (when no AUTH_REQUIRED is returned), providing complete usage guidance for this prerequisite auth tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It adds valuable context by stating that the download validates archive integrity (size, sha256, valid zip/tgz) for re-hosting, and that it uses the browser session. This goes beyond a simple 'downloads artifact' statement, though it doesn't detail error handling or file overwrite behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two focused sentences: the first states the core action and resource, the second adds validation detail. Every phrase earns its place, and it is front-loaded with the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, the description covers the essential context (purpose, authentication via browser session, validation behavior). It doesn't explain return values, but for a file-download tool the saveDir parameter implies the outcome. It could mention prerequisites or failure modes, but overall it is fairly complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter meaning beyond what the schema already provides. It mentions package formats in general but doesn't elaborate on specific parameters like project override or saveDir semantics, leaving that to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action ('Download a package artifact') and the specific resource (.nupkg / .tgz from a feed via pkgs.dev.azure.com). It further distinguishes the tool by mentioning validation for re-hosting, making it distinct from sibling tools which deal with projects, work items, or PRs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (downloading artifacts from a feed) but does not explicitly state when to use this tool versus alternatives or list exclusions. The mention of 'browser session' hints at a prerequisite, but lacks explicit guidance like 'use this when downloading packages, otherwise use search_feeds to locate them.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 does state the download behavior and that it returns size/sha256 stats, but it is ambiguous about what happens when saveDir is omitted and whether this writes to disk or is a read-only operation from the agent's perspective.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, every clause earns its place. The first sentence front-loads the core purpose, and the second succinctly describes return value. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the scope of attachments and return stats, but lacks clarity on side effects, error behavior, and the role of the optional saveDir in the overall flow. Without an output schema, a bit more detail would be needed for full agent certainty.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline applies. The description adds context about attachment sources (AttachedFile relations + comment body references) but does not clarify parameter semantics beyond what the schema already provides (e.g., the effect of omitting saveDir).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific compound verb ('Resolve...AND download') identifying both the resource (work item/comment) and the action (download attachments). It distinguishes itself from siblings like get_work_item and get_work_item_comments by explicitly including attachment download and content stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied ('if you need work item details plus attachments'), but no explicit alternatives or exclusions are stated. Sibling tools are not referenced, so the agent must infer when to choose this over get_work_item or download_artifact.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description adds context by listing the contained fields (metadata, branches, reviewers, linked work items) and discloses the org-wide resolution behavior and repoId flexibility. It lacks explicit side-effect or error information, but the read-only nature is implied by 'Get'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and scope. The second sentence adds a crucial resolution detail without verbosity; every phrase earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter get operation with no output schema, the description provides the essential return scope and a key resolution caveat. It is complete enough for an agent to invoke correctly, though it doesn't describe the output structure or error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers both parameters, and the description adds extra meaning to repoId by noting it may be a GUID or name. This goes beyond the schema's type/description, providing actionable resolution semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Get' and names the resource (pull request) with a clear scope: metadata, branches, reviewers, and linked work items. This distinguishes it from siblings like search_pull_requests and get_pull_request_comments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when/when-not guidance or alternatives are mentioned. Usage is implied by requiring prId and the verb 'Get', but the description doesn't reference sibling tools or criteria for choosing this over search_pull_requests.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It adds useful behavioral details like 'system vs human' threads and 'Resolved org-wide' for repoId lookup. However, it omits other behavioral aspects such as output format, pagination, or any side effects, keeping it at a mid-level.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the primary action. Every phrase adds value, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description should clarify what the tool returns. It only says 'Get PR threads' without describing the structure of a thread or comment, leaving a significant gap for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description's note about repoId ('may be a GUID or a repository name') essentially repeats the schema description, adding minimal extra meaning beyond the structured data.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get PR threads (system vs human).' The verb 'Get' and resource 'PR threads' are specific, and the 'system vs human' distinction helps differentiate it from sibling comment-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use by specifying it retrieves PR threads and notes that repoId can be a GUID or name. However, it does not explicitly mention alternatives or when not to use this tool, which would push it to a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses $expand=all and resolved relations, but does not mention caching behavior (though bypassCache exists), error handling, or authentication. The information about relations is useful but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the key action and scope. No wasteful words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is moderately useful but leaves gaps: it doesn't describe the return format, potential errors, or when to use alternatives. It provides some context with the expansion detail, but could be more complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for both parameters (id and bypassCache), so the description does not need to add param explanations. It adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' with resource 'a single work item', clearly distinguishing from search_work_items and get_work_item_comments. It also adds the $expand=all detail, further clarifying scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for fetching a single work item by id but provides no explicit guidance on when to choose this over search_work_items or get_work_item_comments. No exclusions or alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. The verb 'Get' indicates a read-only operation, and 'full discussion' suggests the complete set of comments is returned. However, it does not disclose potential pagination, ordering, or error behavior, leaving some gaps 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence. The main action is front-loaded, and the parenthetical adds valuable technical context without unnecessary verbosity. Every word contributes to understanding the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-parameter read tool with no output schema, the description and schema together provide complete information. The agent knows what the tool does (gets full discussion), what input is needed (work item id), and the relationship to the broader API. No further details are necessary for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage for the single 'id' parameter with the description 'Work item id.' The tool description adds no additional parameter-level information, so the baseline score of 3 is appropriate since the schema already handles parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and the resource ('full discussion for a work item'), which distinguishes it from sibling tools like get_work_item (which retrieves the work item itself) and get_comment_details (which likely gets a single comment). The parenthetical about the separate endpoint further clarifies its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description strongly implies the intended use case: to fetch the complete comment thread for a work item. The note that this is a separate endpoint not part of $expand guides the agent away from using get_work_item's expand option. It doesn't explicitly name alternative tools for exclusions, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It indicates a read-only operation via 'List' and 'GET', and notes the important constraint that it returns only projects the user can access. However, it does not disclose potential pagination, output structure, or authentication requirements, which are relevant for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: two sentences that front-load the action and resource, include a scoping parenthetical, and end with a clear usage directive. Every word contributes, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema, no annotations), the description provides sufficient context for an agent to understand its purpose and when to invoke it. It could optionally mention return details, but its current coverage is adequate for a zero-parameter list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100% and there is no parameter information to add. The baseline of 4 applies, and the description appropriately does not attempt to explain nonexistent parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Purpose is crystal clear: 'List ALL Azure DevOps projects the user can access in the organization' uses a specific verb and resource, and explicitly scopes to accessible projects. It also includes the API endpoint (GET _apis/projects) for additional precision, and distinguishes itself from the sibling list_repositories by focusing on projects rather than repositories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'Use this to discover projects to browse.' This implies it is the entry point for browsing, making the usage obvious. It does not explicitly mention alternatives or exclusions, but given the unique role among siblings, this is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'id, name and owning project for each repo,' and notes that it lists only repositories 'the user can access,' which adds context about permission filtering. It does not mention pagination or rate limits, but for a simple list endpoint, this is reasonably transparent. The return structure and access scope go beyond what a bare name would suggest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundant words. It front-loads the primary action and scope, includes a technical endpoint reference, and states the return values. Every word adds value, making it appropriately sized and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 optional parameter, no output schema, no annotations), the description is complete: it covers what the tool lists, the optional project scoping, and the returned fields. There is nothing missing for an agent to correctly invoke or interpret the result. The description fully compensates for the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%: the only parameter 'project' has a detailed description ('Restrict to a single project (optional; omit for org-wide)') that already explains its meaning and optionality. The main description restates this concept ('or within one project') but does not add new semantic detail. Thus, the schema already does the heavy lifting, and the description merely reinforces it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List'), the resource ('Git repositories'), and the scope ('across the organization' or 'within one project'). It distinguishes itself from sibling tools like list_projects by explicitly focusing on Git repositories, and from search_work_items/get_work_item by being a direct listing tool. The specific verb and resource make the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: to list all accessible repositories or restrict to a project. It implies this is the tool for repository enumeration, but it does not explicitly mention alternatives or when not to use it (e.g., 'use search_work_items to find work items'). This is a minor gap, so a 4 is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the HTTP method (GET), the effect of feedId, and the nuanced project property behavior (null for org-scoped feeds, automatic project addressing). This goes beyond a minimal description, though it stops short of detailing pagination or response structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences with no filler. The core operation is front-loaded, and each additional sentence adds valuable context (feedId behavior and project-scoping nuance). Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description covers the main behavior, the parameter's effect, and an important edge case (project vs org-scoped feeds). It is sufficiently complete for an agent to use it effectively, though it could mention authentication prerequisites or pagination explicitly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that supplying feedId also lists packages and versions, which is not stated in the parameter description. This improves the agent's understanding of the parameter's semantic effect.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Browse') and clearly identifies the resource (Azure Artifacts feeds), including the REST endpoint. It also distinguishes the tool's behavior when feedId is passed (listing packages + versions), which differentiates it from sibling tools focused on work items, repositories, and pull requests.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: browse feeds by default, pass feedId to additionally list packages and versions. It also explains the project-scoping behavior for feeds, which helps the agent decide when and how to invoke the tool. It does not explicitly name alternatives, but no sibling feed-specific tool exists, so this is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It discloses the default org-wide scope, the ability to restrict to repo/project, and the available filters. The API endpoint '(GET _apis/git/pullrequests)' informs the agent that this is a read-only operation, but it does not address pagination, result ordering, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise clauses plus a parenthetical API path, with no wasted words. It front-loads the core purpose and scope, then lists filters, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a search tool with 6 optional parameters and no output schema, the description gives a solid overview of scope and filters. It does not mention pagination via `top` or the return format, which would be useful, but the tool name and API path make it inferable that a list of pull requests is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, and the description reiterates the filter parameters (status, creatorId, targetRef) and scoping (repoId, project) but adds little beyond what the schema already provides. The `top` parameter lacks a schema description and is not mentioned in the description, leaving that parameter under-explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it 'Search[es] pull requests ORG-WIDE by default' and can scope to a repo or project, naming specific filters. This verb+resource+scope structure distinguishes it from sibling tools like get_pull_request (which retrieves a single PR) and search_work_items (which searches a different entity).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: 'ORG-WIDE by default, or within a repo (repoId) or a project' indicates the search scope. However, it does not explicitly exclude alternatives or mention when to prefer get_pull_request over this search, so it's clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 cross-project default, WIQL backend, almsearch behavior for text, and return fields (id + summary). It does not mention pagination or auth requirements, but covers essential behavioral traits for a read-only search operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-loaded with purpose and scope. No wasted words; technical backend detail is integrated efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 optional parameters and no output schema, the description covers target resource, default scope, parameter usage, and return fields. It omits the default query when no `wiql` is provided (though schema covers this). With no annotations, it could marginally benefit from explicitly contrasting with get_work_item, but sibling context helps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description mentions `text` and `project` usage but largely parallels the schema property descriptions. It adds marginal value by explaining the backend and org-wide default, but does not significantly enrich parameter understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Search/browse' with a clear resource 'work items' and scope 'ORG-WIDE (cross-project)'. It distinguishes the tool from siblings like get_work_item (which retrieves a single item) and search_pull_requests (different resource type).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: default is org-wide, use `project` to scope, and use `text` for full-text search. Implicitly differentiates from get_work_item by focusing on search/browse, but does not explicitly name alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.