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

Annotations already disclose the read-only, idempotent, non-destructive, and open-world nature of the tool. The description adds value by naming what the result contains (status, result, timing), but it does not go deeper into potential access requirements, response shape, or edge cases. With annotations carrying most of the safety behavior, 3 is appropriate.

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, well-structured sentence that front-loads the action, scope, and key output fields. There is no filler, and every clause contributes to understanding what the tool does.

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-resource fetch tool, the description plus schema fully covers the required inputs, the return focus, and the non-destructive behavior via annotations. No output schema exists, but naming status, result, and timing gives sufficient return-value context. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, and both parameters already have meaningful descriptions, including the buildId provenance from list_builds. The tool description primarily restates the id-based lookup and does not add substantial semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('Fetch'), a specific resource ('a single build / pipeline run'), and the retrieval key ('by id'). It also lists the key returned aspects (status, result, timing), and the 'single' qualifier distinguishes it from sibling list_builds without relying on the schema.

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

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

The description implies the right usage context: use this tool when you need one build identified by its id rather than a list of builds. It does not explicitly name alternatives or exclusions, but the id-based and single-item framing provides clear context. The schema's 'from list_builds' hint further reinforces the workflow.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the list of returned fields, which is useful behavioral context about the output, but does not describe error conditions or side effects. This is adequate given the annotations.

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

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

A single, front-loaded sentence states the action and the exact fields returned. Every word adds value, and there is no extraneous 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?

For a simple read operation with one well-documented parameter and annotations covering safety, the description is nearly complete. It lists the output fields, and the schema covers the parameter constraint. It does not mention not-found behavior, but that is a minor gap for such a tool.

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

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

The input schema has 100% coverage, fully describing the 'project' parameter including the allowlist constraint. The description adds no additional parameter-level information, so the baseline of 3 applies—the schema carries the semantic load.

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 ('Fetch') and a clear resource ('full details of a single project'), explicitly listing the fields returned (id, description, visibility, state, capabilities). This distinguishes it from list_projects and other get_* siblings without needing to inspect schemas.

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 clearly implies usage for retrieving details of a specific project by name or id, which differentiates it from list_projects. However, it does not explicitly name the alternative or state when not to use it, leaving some inference to the agent.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds value by specifying the response content (branches, status, reviewers), which is not in annotations. No contradictions.

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 verb and resource. Every word adds value without 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?

Given the simple read-only nature, rich annotations, and full schema coverage, the description is sufficient. It mentions the key returned fields, and no output schema exists to require extra explanation. It could note error handling, but that is not expected for a fetch tool.

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% with clear parameter descriptions for id, repo, and project. The tool description does not add any additional parameter meaning beyond what the schema provides, 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 clearly states it fetches a single pull request by id and lists the included fields (source/target branches, status, reviewers). This is specific and distinguishes it from list_pull_requests which fetches multiple. The verb 'Fetch' and resource 'pull request' make the purpose unambiguous.

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

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

The description implies usage when a specific pull request id is available (since it says 'by id'), but it does not explicitly mention alternatives like list_pull_requests or when not to use this tool. The context is implied rather than stated.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that the tool returns 'all of its fields', which is useful context. However, it doesn't disclose error handling, rate limits, or authentication requirements, but the annotation coverage lowers the burden. No contradiction with annotations.

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 that front-loads the core action and resource, then adds detail on fields. There is 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?

For a simple fetch tool with one parameter and annotations covering safety, the description is nearly complete. It mentions the return fields, though it doesn't specify the exact response format or error behavior. Given the absence of an output schema, the description could have added a bit more about the response structure, but overall it's adequate for an agent to call it correctly.

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

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

The input schema has 100% description coverage; the parameter 'id' is documented as 'Work item id (from query_work_items)', providing context. The description does not add any additional semantic meaning beyond the schema. Baseline 3 is appropriate when the schema already documents the parameter well.

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: 'Fetch a single work item by id' with a specific resource and action. It also enumerates the fields returned, distinguishing it from list tools like query_work_items. The verb 'Fetch' and resource 'work item' are explicit.

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 (fetch by id) but doesn't explicitly state when to prefer this over alternatives. The parameter description 'from query_work_items' hints at a workflow, but the description itself lacks explicit when-to-use or when-not-to-use guidance. There's no mention of exclusions or alternatives.

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?

Annotations already cover read-only, idempotent, and non-destructive behaviorebb. The description adds value beyond those by clarifying the scope ('refs/heads') and specifying the return content (the commit each branch points at). No contradiction with the annotations.

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

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

A single sentence with no filler. It is front-loaded with the action and resource, and the extra detail about commit pointers is concise and relevant.

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 read-only list tool, the description covers the return value at a useful level, and annotations cover side effects and safety. A fully explicit output shape would be nice, but the description is otherwise complete enough for calling the tool correctly.

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 both parameters are already documented. The description does not add parameter-level meaning beyond identifying the repository as the source of branches; this is acceptable given the high schema coverage.

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

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

The description uses a specific verb ('List'), a clear target resource ('branches (refs/heads)'), and even names the returned info ('commit each one points at'). This distinguishes list_branches from sibling list tools like list_repositories and list_pull_requests without opening their schemas.

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?

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites like first calling list_repositories to obtain project/repo IDs, and no exclusion notes. The intended use is only implied by the tool's name and description.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds ordering ('most recent first') and result fields ('status and result'), which is useful but does not disclose pagination behavior, default limits, or what happens when no builds exist. With annotations covering the core behavioral traits, a 3 is appropriate.

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

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

A single sentence that is front-loaded with the action and resource, and includes the most important behavioral details (ordering, status, result). No wasted 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?

For a simple read-only list tool with full schema coverage and safety annotations, the description is mostly adequate. However, it does not mention pagination, the default 'top' value, or how to interpret the result list, and there is no output schema to fill that gap. An agent could call it correctly, but may not know the response shape or limits.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no extra meaning beyond the schema, and the 'top' parameter's default and range are already in the schema. Baseline 3 is correct.

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

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

The description states a specific verb ('List') and resource ('recent builds / pipeline runs in a project'), and adds ordering ('most recent first') and included fields ('status and result'). It is clear, though it does not explicitly distinguish itself from sibling tools like get_build or list_pipelines.

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 a read-only listing use case and the schema notes the project parameter, but it does not explicitly say when to use this tool versus alternatives such as get_build or list_pipelines. The context is clear enough for a simple list operation, but no exclusions or alternative routing are provided.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful return-shape detail of path and dates, but it does not disclose pagination, ordering, or result-set scope beyond that.

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

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

A single, front-loaded sentence states the action, the resource, and the relevant output fields with no redundancy or filler. Every word 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 read-only list tool, the description, rich annotations, and fully described required parameters are nearly complete. It names the key return fields despite lacking an output schema, though it leaves minor ambiguity about whether all iterations are returned and whether any ordering is defined.

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 both required parameters are already documented in the schema. The description adds no extra parameter-level semantics, so the 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 and resource: 'List a team's iterations (sprints).' It also states what each result contains (path and start/finish dates), which clearly differentiates it from sibling tools such as list_teams or 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.

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

The description gives clear context: use this tool when you need a team's sprint/iteration schedule. It does not explicitly name alternatives, but no sibling tool covers the same resource, and the team-scoped wording is sufficient guidance.

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?

The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds value by disclosing that the tool returns ids and names, and by noting the relationship with run_pipeline. This enriches the behavioral context beyond what annotations provide.

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 filler. It front-loads the main action and includes a useful pointer to run_pipeline without unnecessary elaboration.

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 list tool with one parameter and no output schema, the description is complete: it states the purpose, the output fields, and the follow-up usage. Minor details like pagination or filtering are not mentioned, but they are not critical for this straightforward 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?

Schema coverage is 100% because the only parameter 'project' has a description. The description does not add any parameter-specific details beyond what the schema already provides, so it meets the baseline but does not elevate 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 tool lists pipelines in a project, including the specific outputs (ids and names). It also distinguishes the tool by pointing to run_pipeline, making its purpose unambiguous and differentiating it from sibling tools that operate on other resource types.

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: list pipelines in a project. It also suggests the follow-up action of using the pipeline id with run_pipeline. However, it does not explicitly state when not to use this tool or contrast it with alternatives like list_builds, though the context is sufficient for most agents.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific types and the downstream use in project creation, but does not disclose any additional behavior such as pagination or response format, which is minor for a simple list operation.

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

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

Two sentences with no filler: the first states the action and result, the second explains how to use the output. Information is front-loaded and every word adds value.

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 zero-parameter, read-only list tool with no output schema, the description is fully sufficient. It tells the agent what is returned (templates with ids) and how to use them, covering everything needed to invoke and consume the result.

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, and the schema coverage is 100% (vacuously). The description correctly omits parameter details since none exist. With no parameters, the baseline of 4 applies, and no additional parameter explanation 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 uses a specific verb 'List' and resource 'process templates', specifies the types (Agile, Scrum, CMMI, or inherited) and states that ids are returned. This clearly differentiates it from sibling list tools like list_projects or list_teams.

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?

It explains the purpose of the returned ids ('Pass one of these ids as the process when creating a project'), giving clear context on when to use this tool. There are no direct alternatives, so no exclusion is needed, but the usage scenario is clearly implied.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those annotations by clarifying what 'protected' means ('readable but never mutated') and by stating that only allowlisted projects are returned, which is not implied by the annotations.

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?

Three concise sentences, each earning its place: the first states the action and scope, the second lists the output fields, and the third gives practical usage guidance. The content is front-loaded and there is no filler or repetition of annotation data.

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 zero-parameter, read-only list tool, the description is complete: it states what is returned, the scope, and how to use it as a discovery starting point. The output schema is absent, so listing the returned fields is essential and adequately covered.

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 parameterswing, so there is nothing meaningful for the description to add beyond the empty input schema. Baseline for 0-parameter tools is 4, and the description contains no ambiguous parameter references or required inputs.

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 names the exact resource ('projects in the Azure DevOps organization') and the specific scope ('that pass the allowlist'), and it lists the returned fields. 'Start here to discover valid project names' also signals the tool's role as the entry point, clearly distinguishing it from singular tools like get_project.

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?

'Start here to discover valid project names' provides clear guidance on when this tool should be used first. However, it does not explicitly mention alternatives or exclusions, such as using get_project when a single project's details are needed, so it stops short of full when/when-not guidance.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds value by stating the default status filter ('active by default'), which is behavioral information not in the schema or annotations. This supplements the structured metadata effectively.

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

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

The description is a single, front-loaded sentence with no fluff. It communicates the primary action, optional filter, and default behavior efficiently. Every word earns its place, making it highly concise and well-structured.

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

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

For a simple read-only list operation, the description covers the key behavior (listing by repository with an optional status filter) and functional details like the default. It omits pagination or response format, but these are not critical given the tool's simplicity and the safety annotations. Overall, it is complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description reinforces the `status` parameter's default but does not add new meaning beyond what the schema provides for repo and project. The baseline of 3 is appropriate when the schema carries the full parameter burden.

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') and the resource ('pull requests in a repository'), and specifies an optional filter on status with a default. This distinguishes it from sibling get_pull_request (which fetches a single PR) and other list tools by naming the exact 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 when to use it (to list PRs) but does not explicitly contrast with siblings like get_pull_request or mention when NOT to use it. There is no guidance on selecting between this and get_pull_request for a single item, though the filter hint ('active by default') provides some context.

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?

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful value beyond those annotations by specifying the returned fields (ids, names, default branches), which matters here because no output schema is provided.

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

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

A single sentence with no filler. The verb and resource are front-loaded, and the return-field list is given compactly after the main action. Every part 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 one-parameter, read-only listing tool with strong annotations and a fully documented schema, the description is complete enough for an agent to select and invoke it correctly. It states the project scope, required input, and what the result contains, and no output schema is needed.

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

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

The input schema already documents the single required parameter at 100% coverage, including the allowlist constraint. The description repeats the project scoping but does not add new parameter detail beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a specific resource ('Git repositories'), and a scoping constraint ('in a project'), and tells the agent what fields will be returned (ids, names, default branches). This is clearly distinct from sibling tools like list_projects or list_branches.

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

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

The description gives clear context: use this tool when you need to enumerate Git repositories within a particular project. It does not explicitly name alternatives or exclusions, but there is no ambiguity about the intended use case given the required project parameter and the sibling tool names.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds value by specifying the output shape ('display name and unique name') and the scoping constraint ('specific team within a project'). This goes beyond the annotations by clarifying what the agent will receive and the required context, without contradicting any annotation.

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, well-formed sentence that front-loads the action ('List the members') and immediately provides the key detail (identities: display name and unique name). There is no filler or repetition. Every word contributes to understanding the tool's 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?

For a simple list operation with only two parameters and no output schema, the description is complete. It states what is returned (display name and unique name), the required scoping (team within a project), and the annotations cover idempotency and read-only behavior. An agent has all necessary information to invoke the tool correctly without further clarification.

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

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

Schema description coverage is 100%, and both parameters have detailed descriptions in the schema itself: 'team' is 'Team id or name (from list_teams)' and 'project' is 'Project name or id (must be within AZDO_PROJECT_ALLOWLIST when that is set).' The tool description adds no new parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate. The description's mention of 'specific team' is redundant with 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 uses a specific verb 'List' and clearly identifies the resource as 'members (identities: display name and unique name) of a specific team within a project.' This distinguishes it from sibling tools like list_teams or list_projects, which operate on different resources. The purpose is unambiguous and immediately actionable.

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 states the tool lists members for a specific team in a project, implying the user must know the team and project identifiers. It does not explicitly exclude alternatives, but the context is clear: to get team members, you need this tool, whereas list_teams would be used to fetch teams. There is no explicit 'when not to use,' but the purpose is specific enough that an agent can infer the correct usage scenario.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by specifying the output format (ids and names), which is beyond the annotations. It doesn't contradict any annotations and provides useful behavioral context about the returned data.

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 short sentences, front-loading the purpose and adding a practical usage note. No wasted words. It is efficiently structured and easy 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 simple list tool with one well-documented parameter, no output schema, and annotations covering safety, the description is complete. It states the output content and how to use it, which is all an agent needs to invoke it correctly.

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 single parameter 'project' is fully documented in the schema with a clear description including the allowlist constraint. Since schema coverage is 100%, the description need not add parameter details. It doesn't, but the baseline of 3 is appropriate because the schema handles the 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 verb 'List', the resource 'teams', and the scope 'in a project'. It also specifies the output contains 'ids and names', distinguishing it from other list tools like list_projects or list_repositories. The purpose is unambiguous.

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

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

The description gives implicit guidance: use this tool to obtain team ids/names for use with 'team-scoped tools'. It doesn't explicitly state when not to use it or name alternatives, but the context of sibling tools makes the usage clear. The instruction to use the output with other tools adds practical guidance.

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?

Annotations already convey readOnlyHint, idempotent, openWorld, and non-destructive behavior. The description adds useful behavior beyond annotations by specifying that the tool returns IDs only rather than full work-item data, which is helpful for setting expectations and invoking get_work_item afterward.

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 compact and front-loaded: one clear sentence states what the tool does, then adds a terse but informative WIQL example. Every sentence earns its place, and there is no padding or repetition of annotation content.

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

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

For a two-parameter tool with rich annotations and a complete input schema, the description covers what the tool returns, the required project context, points to get_work_item for follow-up data, and includes an example query. This is sufficient for an agent to call it correctly.

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%, with both parameters already describing 'wiql' and 'project'. The description's example WIQL syntax adds a useful illustration but does not materially add meaning beyond the schema, so it meets the baseline without exceeding 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 uses a specific verb-resource pair ('Run a WIQL query against a project') and states a precise outcome ('return the matching work-item ids'). It also names the natural sibling path via 'fetch fields with get_work_item', distinguishing this from the work-item detail retrieval tool.

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 clearly communicates the query-oriented use case and directs the agent to get_work_item for fetching fields. It does not spell out explicit when-not or exclusions, but the context is strong enough to route the agent to the appropriate alternative.

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