wit_create

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the tool performs a write and requires a confirmation flag, which is valuable. Still, it does not mention what happens on success, whether creation is atomic, or potential side effects such as generated links or validation failures.

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 compact sentence that front-loads the core action and then adds the essential write-mode requirement. No filler or redundant restatement of 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?

Given the tool's complexity (10 parameters, nested relations, no output schema, no annotations), the description covers the core purpose and a key prerequisite but leaves out important behavioral context like return value, error behavior, and creation semantics. The schema fills some gaps, but the description alone is not fully 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?

Schema coverage is only 40%, but the description maps several parameters to plain concepts: 'campos, tags, área, iteração, pai e links' correspond to fields, tags, areaPath, iterationPath, parentId, and relations. This adds some meaning, but confirm, title, and tags semantics remain unexplained, so compensation is only partial.

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 begins with a clear verb ('Cria') and resource ('work item'), enumerating the item types and the main action dimensions (fields, tags, area, iteration, parent, links). It is immediately distinguishable from sibling tools like wit_update, wit_link, and wit_query.

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 states that this is a write operation and requires ADO_MODE=write and confirm:true, giving the agent actionable invocation conditions. However, it does not explicitly contrast with alternatives such as wit_update or wit_link, so it stops short of full when-to-use/when-not-to-use guidance.

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