Add Test Case

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

With no annotations, the description carries the full burden and does well: it discloses that there is no delete endpoint (effectively irreversible), that creation fails with "Type is required" without `test_case_type`, and that the call returns the created object. It omits permission/auth or rate-limit context, but the key risk profile is covered.

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 compact paragraphs, front-loaded with purpose, then prerequisites, then the parameter gotcha. Every sentence carries actionable information and nothing is repeated from 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?

For a mutation tool with no annotations and no output schema, the description covers prerequisites, irreversibility, and the main failure mode. Only the shape of the returned object and any tenancy/permission caveats are left implicit, which is a minor gap.

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 already 100%, so baseline is 3; the description adds real meaning beyond the schema by turning the optional-looking `test_case_type` into a practical requirement and explaining how to obtain a valid ID from the `testCaseTypeId` field of a `list_test_cases` row. That is genuinely useful cross-tool parameter guidance.

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 and resource ("Creates a new test case in a project and returns it") and scopes where it happens. It does not distinguish itself from the close sibling `upsert_test_case`, so an agent still has to infer which one to pick.

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?

Useful prerequisites are given ("The test suite and section must already exist: this tool does not create them") plus a sandbox recommendation for experimentation. However, there is no explicit when-to-use-this-instead-of guidance against `upsert_test_case` or `list_test_cases`, so routing is only implied.

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