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

The description clearly discloses that this operation writes to Azure DevOps and is visible to the team, which goes beyond the annotations. It also explains the return value (the created item with ID and link), warns that work item types vary by process, and gives a concrete recovery instruction if the type is invalid. This is substantial behavioral context.

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 long but well structured: purpose first, then usage guidance, then grouped parameter details, then example requests that should trigger the tool. Every section earns its place, and the most decision-relevant information is front-loaded.

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 high complexity (12 parameters, nested objects, output schema, sibling tools), the description covers the required fields, optional project default, HTML formatting rules, custom fields, error recovery, and user confirmation. It even describes what the tool returns, so an agent can invoke it correctly without guessing.

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%, so the schema already documents all parameters. The description adds value by listing valid workItemType examples, showing how additionalFields works with reference names, emphasizing that long-text fields must be HTML, and providing trigger examples that map naturally to parameters. This is above the baseline but not essential documentation for every parameter.

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: 'Cria um novo work item em um projeto do Azure DevOps Server e devolve o item criado, já com o ID gerado e o link.' It also states when to use it ('Use quando o pedido for para registrar algo novo') and gives concrete trigger examples, making it easy to distinguish from the sibling tools list_work_items, get_work_item, and update_work_item.

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 explicitly says when to use the tool: when the user wants to register something new such as a task, bug, or story. It also instructs the agent to confirm type, title, and project when ambiguous. It does not explicitly name alternatives or state 'do not use this for existing items', but the 'registrar algo novo' framing implies the boundary.

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, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details beyond the schema, such as the API constraint that 'fields' requires expand='none', the default expand value of 'all', and the trade-off that expand='none' is more economical for simple state/title checks.

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 well-structured and front-loaded with the primary purpose, followed by usage guidance, parameter details, and examples. It is somewhat longer than the minimum viable description, but the parameter section and examples earn their place by making the tool easy to invoke correctly without consulting the schema separately.

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 that an output schema exists and the annotations cover the read-only, idempotent safety profile, the description is complete for both selection and invocation. It covers when to use the tool, what the ID represents, the optional project default, expansion levels, the fields constraint, and concrete trigger phrasings. Nothing essential for correct use is missing.

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 all four parameters thoroughly. The description largely repeats schema content, though it adds minor context such as 'id as shown in the web interface' and the default project behavior. Baseline 3 is appropriate because the description does not substantially extend the parameter semantics beyond what the schema provides.

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 function: retrieving all details of a single Azure DevOps Server work item by ID, and enumerates the types of information returned (title, description, acceptance criteria, state, assignee, area, sprint, priority, tags, dates, author, custom fields, and links). It distinguishes itself from sibling tools by explicitly targeting one known work item, versus list_work_items for discovery.

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 explicitly states when to use the tool: when the ID is already known, either from the user or from a prior list_work_items call. It also gives the alternative: call list_work_items first if the ID is unknown. Concrete example user requests are provided to help an agent recognize triggering scenarios.

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 behavior. The description adds valuable behavioral context beyond that: pagination limits (max 200, default 50, use skip, read totalMatched), the precedence of wiql over direct filters, and the @me resolution for assignedTo. These are concrete operational details an agent needs to call the tool correctly.

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 long but well-structured: it opens with the core purpose, then gives usage guidance, then details filtering methods and pagination, and ends with concrete examples. Each section earns its place; there is no fluff. It is front-loaded with the most important information (what it does and when to use it). It could be slightly more compact, but the density of useful info justifies its length.

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 10 optional parameters, three filtering modes, and pagination, the description covers all critical aspects: return summary fields, when to use it, the three filtering approaches with precedence, pagination behavior, and example prompts. The presence of an output schema further covers return details. Nothing an agent needs to invoke it correctly is missing.

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 each parameter is individually documented. The description goes beyond that by organizing the parameters into three coherent filtering modes (direct filters, queryId, wiql) and explaining when to use each, which helps the agent choose the right parameter combination. This adds strategic value on top of the schema's per-parameter descriptions.

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 ('Lista') and resource ('work items') with a clear summary of what is returned (ID, tipo, título, estado, etc.). It distinguishes from the sibling get_work_item by explicitly noting that tool is for a single item with more detail. This makes the tool's purpose unambiguous and distinct.

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 explicitly says 'Use quando o pedido for por um CONJUNTO de itens que atendem a um critério' and directs to get_work_item for a specific item. It also gives examples of user requests that should trigger this tool and explains the three filtering methods with precedence, leaving no ambiguity about when to use it vs 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?

Beyond the annotations (readOnlyHint=false), the description discloses that the operation writes to Azure DevOps and generates notifications to involved parties. It also clarifies that only provided fields are sent and others remain unchanged, that tag replacement is destructive while tagsToAdd/Remove are incremental, and that long text fields must be HTML – all valuable behavioral context beyond 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?

The description is well-structured: it leads with the core function, then lists usage scenarios, then details parameters with specific constraints, and ends with illustrative example prompts. While long, every sentence adds value – there is no fluff or redundancy, and the most important behavioral notes (write + notification, partial update) appear early.

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 14 parameters and complex behaviors, the description covers everything needed: required fields, the at-least-one-other-field rule, state transition constraints, tag handling, HTML formatting for long text, additionalFields usage, and example prompts. The output schema is present, so return format is defined externally; nothing essential for correct invocation is missing.

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?

Although schema coverage is 100%, the description adds significant meaning: it explains that tags replaces the entire list and [] clears it, warns against combining tags with tagsToAdd/tagsToRemove, specifies that comment goes to System.History in HTML, and describes additionalFields as reference-name key-value pairs. These details are not present in the schema alone and materially help the agent build correct calls.

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 precise statement: it updates fields of an existing Azure DevOps work item and/or registers a comment in the Discussion tab, and returns the updated item plus a list of changed fields. It then lists concrete update targets (state, assignee, title, description, priority, sprint, tags, custom fields) and gives example user requests, making the tool's purpose unmistakable and clearly distinct from the read/create siblings.

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 explicit use cases ('Use para mudar estado, responsável, título...') and provides five realistic user-phrase examples that should trigger this tool. It implies the tool is for existing items by saying 'work item existente', but it does not explicitly direct agents away from create_work_item for new items or mention when not to use it; however, the context is strong enough for correct routing.

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