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

readOnlyHint=true is consistent with the read-only verb 'Fetch' — no contradiction. The description adds meaningful behavioral context beyond the annotation: it returns raw structured context only (NOT a finished analysis), requires DEVOPS_ORG_URL + DEVOPS_PAT env vars, and imposes a post-call synthesis obligation on 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?

Front-loaded with purpose, scope, and trigger phrases before any behavioral detail. The post-call Copilot instructions section is long but earns its place because the tool returns raw context and the agent needs the response contract; minor redundancy in the French section template (section descriptions + bullet elaborations) keeps it from 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?

With no output schema, the description carries the return-value burden and discharges it fully: it enumerates 4 concrete return categories (metadata, KB object details, custom code, CoC relation graph). For a 6-parameter tool with heavy sibling overlap, nothing blocking is missing — triggers, exclusions, env prerequisites, return shape, and post-call behavior are all 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?

Schema description coverage is 100%, so the baseline is 3. Each of the 6 parameters already has a rich schema description with usage tips (maxComments cap 20, focusObjects speeds up analysis, includeImages costs latency/tokens), and the tool description itself adds no parameter-level detail beyond the env var requirement. The schema does the heavy lifting 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?

States a specific verb + resource ('Fetch a Work Item and assemble ALL technical context needed for D365 F&O expert analysis') with an explicit platform boundary ('AZURE DEVOPS ONLY'). It differentiates from siblings by naming what it is not for and by defining its output as full context assembly rather than a simple query (which distinguishes it from ado_query_workitems).

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

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

Provides an explicit PRIORITY TRIGGER phrase list in both French and English, and an explicit NEVER-for clause with alternative tool routing ('use search_labels / search_d365_code instead'). It also states a hard exclusion: never call ado_post_comment on linked/related work items — only on the analyzed WI.

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