create_autotest

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

Annotations already declare this is a non-read-only, non-idempotent, open-world write with no destruction, so the safety profile is covered. The description adds useful side-effect context (linked work items become automated, enabling test runs) beyond the annotations. However, with idempotentHint=false it never says what happens if the externalId already exists — error, duplicate, or upsert — nor whether permissions beyond project access are needed.

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?

Three tight sentences, front-loaded with the action and then the two facts that most affect correct use (linking semantics and result correlation). Every sentence earns its place; the only slight friction is the embedded clause about test plans, which could be its own sentence.

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 14-parameter tool with nested objects and no output schema, the description covers the relational workflow well but leaves most field-level semantics and the return value (presumably the created autotest and its id) unaddressed. It is enough to call the tool correctly for the common case but not for the nested step/setup/teardown payloads.

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 21% across 14 parameters, so the description carries real burden. It usefully explains workItemIds (link target), externalId (result correlation key) and payload (escape hatch for extra AutoTestCreateApiModel fields), which the schema leaves as an undescribed free-form object. But the nested setup/steps/teardown structures, tags, classname, namespace and the projectId-vs-projectName choice get no explanation anywhere.

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?

Opens with a specific verb+resource ('Create an autotest') and immediately explains the key semantic consequence of the workItemIds parameter, which distinguishes it from a plain CRUD create. It does not explicitly contrast with siblings like set_autotest or link_autotest_work_item, so an agent must infer the create-vs-update boundary.

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?

Gives real usage context: linking workItemIds is what makes cases automated and is a prerequisite for creating test runs from a test plan. It also points forward to submit_test_run_results for the results step, which is a genuine workflow handoff. It stops short of stating when to use this instead of set_autotest (e.g. on an already-existing externalId).

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