ado_list_release_approvals

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

The description is consistent with the readOnlyHint annotation, confirming read-only behavior. However, it adds no additional behavioral context beyond what the annotation already implies (e.g., no mention of return format, pagination, or that results are filtered to pending status). With annotations covering the safety profile, a score of 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, clear sentence with no wasted words. It is concise but could benefit from slightly more detail (e.g., what constitutes 'pending'). It earns a 4 because it is efficient while leaving room for improvement.

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 nature of the tool (2 optional parameters, no nested objects, no output schema), the description is minimally adequate. It does not explain what information is returned (e.g., approval details), but the context signals indicate low complexity. A score of 3 reflects sufficiency without excellence.

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%: the 'top' parameter has a description ('Max results to return') and constraints, and 'project' has a default description. The tool description adds no further meaning beyond the schema. Baseline score of 3 applies since the schema already documents the parameters adequately.

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

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

The description clearly states the action 'List', the resource 'pending release approvals', and the scope 'in a project'. It effectively differentiates from sibling tools like 'ado_approve_release' (which performs an approval action) and other list tools (e.g., ado_list_releases lists all releases, not pending approvals).

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 guidance on when to use this tool versus alternatives. For instance, it does not mention that listing approvals is a prerequisite for approving a release via 'ado_approve_release', nor does it specify any conditions for pending approvals. The description is purely functional without contextual advice.

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