ado_pipelines_get_run

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

The annotations already declare readOnlyHint, but the description adds meaningful context by requiring vso.build PAT scope (an authentication requirement not present in annotations) and by listing the returned fields (state, result, timestamps, URL). This goes beyond what annotations capture and clarifies the tool's behavior for the agent.

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 short and to the point: it first states the core function, then what the user gets, then the auth requirement. Each sentence is informative, and there is no filler or duplication. It is front-loaded with the primary action.

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

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

Given the tool is a straightforward query with three required parameters and read-only annotations, the description covers purpose, output, and authentication. It does not mention error cases or how to obtain the run ID, but for a simple retrieval endpoint this is adequate. The presence of an output schema is not required because the description already indicates the return fields, which is sufficient.

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?

With 100% schema description coverage, all three parameters are already documented. The description merely repeats that the run is addressed by pipeline ID and run ID, not adding new semantics or guidance on parameter relationships. It stays at the baseline neutral level because it neither enriches nor is necessary for understanding the params.

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 is explicit: 'Get details of a single Azure DevOps pipeline run by pipeline ID and run ID.' This clearly identifies the verb and resource and differentiates itself from sibling tools that list or trigger runs by emphasizing a single run and specifying return fields. The mention of 'single' distinguishes it from listing operations.

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 that this tool is used when you have a specific pipeline ID and run ID to request details, but it does not provide explicit guidance on when to use this versus alternatives like listing runs or fetching logs. It lacks exclusions or comparative routing, which keeps it at a basic 'implied usage' level rather than a clear 'use this when' statement.

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