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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context by stating it does not read credentials or perform a login test, telling the agent this is safe to call for inspection without triggering auth side effects. It stops short of describing response shape, but with no output schema that is a minor omission given the enumerated data categories.

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

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

Two short sentences with zero filler. The capability list is front-loaded and the negative scope statement follows in the natural 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 zero-parameter, no-output-schema read tool, the description is largely sufficient: it names the four categories of information returned and explicitly bounds the operation. The one gap is the absence of any sibling comparison, which matters given how similar ado_context sounds.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not need to compensate for any schema gap here.

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 "Describe" and enumerates exactly what is returned: profile names, provider types, allowed organizations, and bindings. An agent can tell this is a local configuration-inspection tool, though it never distinguishes itself from the sibling ado_context, which an agent would plausibly confuse it with.

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?

"Does not read credentials or test login" implicitly scopes usage by ruling out authentication verification, but the description never states when an agent should call this rather than ado_context or ado_projects_list. Usage must be inferred from the returned-data list rather than read directly.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description still earns credit by disclosing two traits annotations cannot: no credential is acquired (a side-effect boundary) and resolution never falls back to cwd. It omits what a failed resolution looks like, which keeps it off a 5.

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

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

Two short sentences, zero filler, with the core action front-loaded and the calling constraint immediately after. Nothing could be removed without losing 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?

There is no output schema, so explaining what 'resolved context' returns would be the description's job, and it doesn't. Combined with five undescribed nested fields and no stated error/fallback behavior, the definition is adequate for a single-parameter read tool but leaves real gaps.

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 0% and the single parameter is a nested object with five undocumented fields (profile, project, repoPath, repository, organization). The description names only target and repoPath, leaving profile/repository/organization semantics entirely unexplained, so it does not compensate for the coverage gap.

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

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

States a specific verb (resolve) and two specific resources (target, credential profile), and the clause 'without acquiring a credential' implicitly separates it from the credential-acquiring sibling ado_config. It stops short of naming the sibling, so the differentiation is inferential rather than 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?

'Supply explicit target or absolute repoPath; no cwd guessing' gives a real precondition for calling the tool, which is more than nothing. However, it never says when to choose this over ado_config or the *_list tools, nor what happens if the precondition is violated.

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 safety is covered. The description adds nothing beyond that — no mention of pagination, auth/profile requirements, error behavior for missing pipeline IDs, or what the read actually returns.

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?

Single short sentence with zero waste and front-loaded verb+resource, but the brevity comes from omission rather than efficiency — there is no useful detail to be concise about.

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

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

With a nested target object, 0% schema coverage, and no output schema, the description should explain what the target fields are for and what the returned definition contains. It provides none of that, so an agent must guess how to construct the target object.

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 0% and the target parameter is a nested object with five sub-fields (profile, project, repoPath, repository, organization) whose meaning and selection rules are entirely undocumented. The description mentions no parameters at all, leaving both pipelineId and the target object unexplained.

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

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

States a specific verb (Read) and resource (pipeline definition), which is enough to separate it from ado_pipelines_list and ado_pipeline_run_get at a coarse level. However, it doesn't articulate what part of the definition is returned or how it differs meaningfully from listing 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?

There is no explicit guidance on when to use this vs. ado_pipelines_list or ado_pipeline_run_get; the agent must infer that this fetches one definition by ID. No prerequisites or exclusions are mentioned.

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

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

Annotations already declare destructive/openWorld/non-idempotent, and the description adds genuinely new context beyond them: this runs remote code, it can deploy resources, user authorization is required, and the call is not automatically retried. The non-retry disclosure is important because the non-idempotent hint means a blind retry could double-queue a deployment.

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?

Four short sentences, front-loaded with the 'WRITE:' risk marker, and each sentence carries distinct information (action, blast radius, authorization gate, retry behavior). No filler or restatement of the name.

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?

There is no output schema, and the description never indicates what the agent gets back (e.g. a run ID to poll with ado_pipeline_run_get), which matters for a queue-and-watch workflow. The risk profile is thorough, but the silent nested target schema is a meaningful completeness gap.

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 0% and there are three parameters, including a nested 'target' object with five ambiguous sub-fields (profile, project, repository, repoPath, organization). The description provides no parameter meaning at all, leaving questions like repository vs. repoPath resolution and how refName is validated entirely unanswered.

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

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

States a specific verb and resource ('Queue a pipeline run') and immediately names the consequence ('executes remote pipeline code and can deploy resources'). This is clearly distinguishable from the read-oriented siblings ado_pipeline_get and ado_pipeline_runs_list without opening either 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?

Gives a concrete gate for invocation ('Obtain explicit user authorization'), which tells the agent both when this is appropriate and what precondition must hold. It stops short of naming when-not-to-use or pointing at an alternative tool (e.g. ado_pipeline_run_get to poll status), so it falls short of a 5.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond restating that it reads a run, such as permission requirements, error behavior, or what the nested target implies.

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 wasted words. However, it is arguably too terse for a tool with a nested target object and three required parameters.

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 a simple read operation and annotations cover its safety profile, but the nested target object has five optional fields with no descriptions and the schema has 0% coverage. The description does not explain the target object or provide enough context to call the tool confidently beyond its name.

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 0%, and the description does not mention any of the three required parameters or the nested target object. It does not explain pipelineId, runId, or the target fields, so it fails to compensate for the undocumented 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 clear verb, 'Read', and a specific resource, 'a specific pipeline run'. It implicitly distinguishes retrieval of one run from the sibling list operation, but it does not explicitly differentiate itself from siblings such as ado_pipeline_runs_list or ado_pipeline_run.

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

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

The phrase 'a specific pipeline run' implies usage when the agent already has a run identifier, which is a reasonable contextual cue. However, there is no explicit guidance on when to use this versus ado_pipeline_runs_list or ado_pipeline_run, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context that annotations cannot convey: the Azure DevOps service cap of 10,000 and a 4 MiB response cap. It stops short of saying what happens when the cap is hit (truncation marker? error?).

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 tight sentences with the operation front-loaded and the limits second. No filler, no restatement of the tool name.

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 a nested target object, 0% schema coverage and no output schema, the description is too thin. An agent cannot tell what fields a run record contains, whether ordering is newest-first, or how the response cap manifests, all of which matter for correct invocation and interpretation.

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 0%, and 'target' is a nested object with five undocumented sub-fields (profile, project, repository, repoPath, organization) whose interaction is non-obvious. The description mentions none of them and says nothing about pipelineId being a numeric identifier versus a name, so it fails to compensate for the coverage gap.

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 and resource ('List recent runs for a pipeline'), which clearly separates it from ado_pipeline_get and ado_pipeline_run_get (single entities) among the siblings. It does not explicitly name those siblings, so the differentiation is inferred rather than stated.

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

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

There is no guidance on when to use this versus ado_pipeline_run_get or ado_pipeline_run, no mention of prerequisites or required scopes. The 'recent' framing implies a default ordering but never says how to retrieve older or more runs.

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, destructiveHint=false and openWorldHint, so the safety profile needs no restating. The description adds genuine behavioral context beyond them — that results are paged and how to continue — but says nothing about ordering, page size defaults, or the shape of returned items.

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

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

Two short sentences, both earning their place, with the paging instruction front-loaded rather than buried. Nothing is wasted, though the brevity leaves the nested target parameter unaddressed.

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?

A nested-object, 0%-coverage schema with no output schema needs more than two sentences. The agent is never told what a target must contain to resolve a pipeline scope, nor what a returned pipeline record looks like, which is significant for a list tool with no 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 description coverage is 0%, so the description carries the full burden, yet it only explains continuationToken. The required `target` object (with profile, project, repository, repoPath, organization) and the `top` page-size parameter with its 1-100 bounds are entirely undocumented anywhere.

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

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

States a specific verb and resource ("List a page of pipelines"), which cleanly separates it from ado_pipeline_get and ado_pipeline_runs_list in the sibling set. It stops short of stating the scope (which project/repository the pipelines belong to), so an agent must open the schema to learn that.

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 only guidance is a pagination mechanic (pass continuationToken back), not when to choose this over ado_pipeline_get or ado_pipeline_runs_list. No prerequisites, no mention of required target scoping or what to do when the list is empty.

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 readOnly, idempotent, non-destructive, open-world. The description adds value beyond them: it discloses pagination behavior (one page at a time, token for next page) and a security caveat that remote content is untrusted. It doesn't state default/max page size or error behavior, so not a 5.

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

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

Three short sentences, front-loaded with purpose, then pagination mechanics, then the safety note. No filler.

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?

Pagination and untrusted-data handling are covered, which is the hardest part for an agent. But with a nested required object and zero schema descriptions, the definition leaves the agent guessing which target fields to populate for a plain project listing.

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 0% and the schema is a nested 'target' object with six undocumented sub-fields (profile, project, repoPath, repository, organization). The description says nothing about which target field is needed (e.g., organization), what 'top' controls beyond the schema's silent default of 50/max 100, or the token's origin. It fails to compensate for the coverage gap.

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?

Specific verb + resource + scope: 'List one page of projects in an organization'. Distinguishable from other list siblings (repositories, pull requests, pipelines) by resource, though it doesn't explicitly contrast itself with any of them.

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

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

The pagination instruction ('Pass returned continuationToken for the next page') implies usage, but there's no explicit when-to-use guidance, no mention of how this relates to ado_context or ado_config (which may also resolve organization state), and no stated prerequisites for the 'target' object.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds real value on top by flagging 'Never retried automatically' (consistent with non-idempotency) and requiring user confirmation before writing. It still doesn't say whether the created PR is immediately active, which permissions are needed, or what happens on branch conflicts.

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 short clauses with the mutation class front-loaded and the safety instruction adjacent. Nothing is redundant or buried; the brevity is appropriate for a create call, with the detail burden correctly pushed to the schema.

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 destructive, non-idempotent write with a nested target object and no output schema, the description covers the two things an agent most needs (user confirmation, no auto-retry). It falls short on parameter-level behavior — draft default and ref naming — leaving the 0%-coverage schema to carry too much.

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 0% across 6 parameters, including a nested target object with five documented-by-name only fields, yet the description only gestures at 'target, branches and contents.' Critically it never mentions the surprise default isDraft=true, the required refs/heads/ prefix on both ref names, or the title/description limits — the agent must read the raw schema to avoid errors.

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

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

States a specific verb and resource ('Create a pull request') and prefixes it with 'WRITE:', which alone separates it from read-side siblings like ado_pull_request_get/list and from ado_pull_request_update. It does not explicitly name the sibling it replaces, but the create/update split 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?

'Confirm target, branches and contents with the user' is a prerequisite/guardrail rather than a selection rule, and no alternative tool is named for cases where the PR already exists (update) or for verifying state first (get/list). Usage is implied by the WRITE label rather than spelled out.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description contributes only the vague notion of a 'selected repository' context and says nothing about what is returned, what happens when the PR ID does not exist, or auth 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?

A single short sentence with the resource front-loaded and no filler. Its brevity is close to under-specification, which caps it below a 5.

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 whose only required target is a nested, five-field object with zero documented fields and no output schema, the description leaves the agent unable to construct the target reliably or know the return shape. Annotations cover the mutation/read profile but not the calling contract.

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 0%, so the description must compensate, and it does not. The nested 'target' object contains five fields (profile, project, repoPath, repository, organization) that are entirely undocumented anywhere, and 'pullRequestId' is only obliquely implied by 'a pull request'.

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 ('Read a pull request'), and the verb alone distinguishes it from ado_pull_request_create and ado_pull_request_update. It stops short of explicitly naming those siblings or describing the returned data, so it is clear but not maximally differentiated.

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 gives no guidance on when to select this tool over ado_pull_requests_list or ado_pull_request_update, and no prerequisites are spelled out. The phrase 'in the selected repository' only faintly implies a prior ado_context/ado_config selection step without stating it.

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, openWorldHint and destructiveHint=false, so the safety profile is covered; the description adds the useful "bounded page" behavior. However, it omits the most consequential behavior for an agent: status defaults to "active", so completed and abandoned PRs are silently excluded, and page size is capped at 100.

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

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

Two short, front-loaded sentences with no filler. It is efficient, though the second sentence spends its budget on pagination while more important semantics are left out.

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

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

With four parameters, a nested required target object, 0% schema coverage, no output schema, and no annotations covering filtering behavior, the definition is too thin. An agent cannot tell what scope of PRs it will get back or how to shape the target object from this description alone.

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 0%, so the description carries full burden, yet it explains only skip. The required nested target object (organization/project/repository/repoPath/profile) and the status enum with its non-obvious "active" default go entirely unmentioned.

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 gives a specific verb and resource ("List ... repository pull requests") and distinguishes it from ado_pull_request_get by framing it as a paged listing. It does not explicitly name the sibling, but "list a bounded page" is unambiguous against the singular get 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?

"Use skip to page" is the only usage instruction, and it addresses just one of four parameters. There is no guidance on when to pass a status filter, when to use this versus ado_pull_request_get, or that the default result set is limited rather than comprehensive.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety burden is partly covered. The description adds real value by naming the destructive action (abandon) alongside its counterpart (reactivate), which signals the state change is reversible via this same tool, and clarifies that completion cannot be performed.

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 write intent and the mutable field list, then closed with the critical negative constraint. Every clause earns its place and nothing is restated from the schema or annotations.

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 three-parameter mutating tool with a nested required `target` object at 0% schema coverage, the description leaves the addressing/identity portion of the call entirely undocumented. Since there is no output schema, no return-value explanation is needed, but the target resolution story (repository vs. repoPath, project, organization) remains a real gap.

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 0%, so the description must carry parameter meaning, and it partly does: the listed editable fields map directly to the sub-properties of `changes` (title, description, isDraft, status). However, the required `target` object (profile, project, repoPath, repository, organization) and `pullRequestId` are never mentioned, and there is no guidance on which target fields are needed or how they interact.

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 opens with a specific verb and resource ('WRITE: Edit ... a PR') and enumerates exactly which fields are mutable: title, description, draft state, and status (abandon/reactivate). It also states a hard scope boundary ('Merge/completion is not supported'), which cleanly separates it from ado_pull_request_create and ado_pull_request_get.

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

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

Usage context is clear: this is the mutation path for pull request metadata, and the explicit exclusion of merge/completion tells the agent when NOT to use it. It stops short of naming a specific alternative for completion (none exists among the siblings), so no exclusions point anywhere, but the operative guidance is unambiguous.

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 readOnly/idempotent/non-destructive, so the description is free to add operational behavior instead: it discloses that the API returns a single unpaginated collection and that the response is capped at 4 MiB. That truncation/collection-shape detail is genuinely useful context an agent cannot get from 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?

One sentence, front-loaded with the action and scope, with the parenthetical carrying two non-obvious operational facts. No filler.

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

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

With a nested target object, zero schema descriptions, and no output schema, the definition leaves the agent without the structure of the required parameter or what a repository record contains. The 4 MiB note helps but does not compensate for the undocumented parameter shape.

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 0% and the single parameter is a nested object with five sub-fields (profile, project, repoPath, repository, organization), none documented anywhere. The description only obliquely hints that 'project' matters, leaving the agent to guess how to populate the rest.

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

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

States a specific verb+resource ('List repositories') and adds scope ('in a project'), which is enough to distinguish it from siblings like ado_projects_list or ado_pipelines_list that target different resources. It does not explicitly name an alternative, but no sibling overlaps in resource.

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 call this versus other list tools, no prerequisites (auth/profile selection), and no note on whether a project is required or optional. The agent must infer usage entirely from the resource name.

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 this a non-readonly, non-idempotent, destructive, open-world write, so 'WRITE:' adds little. The description does contribute one genuine constraint beyond the schema — 'No credential values in fields or arguments' — but omits the operationally important consequence of idempotentHint=false (retries create duplicate work items) and says nothing about permissions or failure 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?

Three short, front-loaded sentences with no filler; the mutation marker and the required field lead. The only mild redundancy is 'WRITE:', which restates what readOnlyHint=false already conveys.

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?

Placeholder for completeness assessment.

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 0% across three required parameters, so the description must carry the load and largely does not. It names only one field key ('System.Title') inside the free-form `fields` object and says nothing about `type` (work item type) or the nested `target` object's organization/project/repository components.

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

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

States a specific verb and resource ('Create a work item'), which cleanly separates it from ado_work_item_get/update/query siblings. It does not explicitly name an alternative, but the create-vs-read-vs-update split is unambiguous from the verb.

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 when-to-use or when-not guidance: nothing says to check for an existing item first (ado_work_items_query) or to use ado_work_item_update for subsequent changes. The only guidance is a required-field hint ('Supply System.Title'), which is parameter help rather than usage routing.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds project scoping, which is useful behavioral context, but does not explain permissions, error behavior, or return format. With annotations carrying the safety burden, this is adequate but not rich.

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

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

The single sentence is front-loaded and wastes no words. It is appropriately concise in form, though its brevity contributes to the missing context captured elsewhere.

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 has a nested target object with no schema descriptions and no output schema, increasing the description's explanatory burden. A one-sentence summary does not provide enough detail about target fields, workItemId semantics, or return behavior for an agent to invoke it confidently.

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

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

Schema description coverage is 0% for two required parameters, and the nested target object contains five properties with no semantic documentation. The description only hints at project scope and does not explain workItemId or target fields such as profile, repository, or organization, so it fails to compensate for the coverage gap.

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, 'Read', and a specific resource, 'work item', and adds the scoping constraint 'scoped to a project'. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like ado_work_items_query or ado_work_item_update.

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

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

There is no explicit when-to-use or when-not-to-use guidance, no mention of alternatives, and no prerequisites. The agent can infer that this retrieves one work item by ID, but the choice against query/update siblings is left unstated.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are lightweight references and are capped at 200, which matters because there is 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?

Three short sentences, each carrying distinct information (read-only query, reference-shaped results, hard cap), with the core purpose front-loaded and no filler.

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 return-shape and cap notes compensate well for the absent output schema, but for a tool with a nested target object and zero schema descriptions, the definition leaves WIQL authoring and target scoping unexplained. It is workable but has clear gaps.

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 0%, so the description must carry parameter meaning and largely does not. It implies project scoping via "in a project" and echoes the 200 cap, but never explains WIQL syntax/format, the top parameter or its default of 50, or the target object's fields (profile, organization, repository, repoPath).

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

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

States a specific verb and resource ("Execute read-only WIQL in a project") and adds scope. "Returns references, not expanded items" implicitly distinguishes it from ado_work_item_get, which expands items, though no sibling is named explicitly.

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

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

Usage is only implied: the note that results are references rather than expanded items hints that ado_work_item_get is needed afterward, but there is no explicit when-to-use/when-not statement or named alternative. An agent must infer 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the mutation profile is known. The description adds genuinely new operational context the annotations cannot carry: a required revision test that prevents overwriting concurrent changes and the instruction to fetch the current rev first. It's still silent on what happens to unmentioned fields and what a stale-revision error looks like.

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

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

Two short sentences, front-loaded with the operation type (WRITE) followed by the safety constraint, with no filler. The extreme terseness is a virtue here, though the missing detail is a completeness problem rather than a conciseness one.

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?

A destructive write tool with a nested, undocumented target object, 4 required parameters and no output schema deserves far more: which field names are legal, what target sub-fields are mandatory, and the error behavior on a failed revision check are all absent.

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

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

Schema description coverage is 0% and nothing in the description compensates. It only alludes to 'fields' and 'revision'; the required nested 'target' object (profile, project, repository, repoPath, organization) is completely unexplained, as are valid field-name patterns and workItemId 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?

Specific verb+resource: 'WRITE: Update named work item fields', with a clear WRITE marker that separates it from the read-side siblings (ado_work_item_get, ado_work_items_query). It never names a sibling or states its scope relative to ado_work_item_create, so it stops short of full differentiation.

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 clause 'read current rev first' gives a real precondition workflow and implicitly routes to ado_work_item_get before calling. But it never states when to choose update versus create/get or what to do if the revision test fails, so usage is only implied.

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