remove_cases_from_collection

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

Beyond annotations, it discloses that action is destructive and not reversible, deletes status/step results for these cases in this collection, ignores ids not present instead of raising an error, and preserves the test cases themselves in the project library. This aligns with destructiveHint=true and idempotentHint=true and adds concrete consequences, so no contradiction exists.

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 definition opens with a crisp one-summary action, then uses each following sentence for a high-value detail: return value, edge-case behavior, destructive consequence set, and sibling routing. No filler or restatement of schema-aware items; the text is dense but fully purposeful.

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 compensates by naming the return values (collectionId, collectionName, removed) and the count semantics. It covers error behavior, idempotency, and the scope of damage, and it routes all nearby sibling cases. An agent has enough to decide when to call it and to establish expectation about the result.

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?

Even though the schema covers both parameters, the description adds meaningful provenance: collectionId comes from list_test_collections, and caseIds are the numeric internal ids from list_test_cases, explicitly warning against TC-numbers. That disambiguates a common source error for this API family and goes well beyond the field 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 leads with a specific verb+resource pair: 'Remove test cases from a test collection.' It also disambiguates from nearby tools by explaining that test cases themselves stay in the project while the collection membership is removed, and it positions delete_test_case as the tool for project-wide case archival.

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 names the inverse operation (add_cases_to_collection) and gives when-to-use alternatives for related but distinct scenarios: delete_test_collection for retiring the whole collection, remove_source_from_execution for source groups on an Executions page, and delete_test_case for archiving the case project-wide. It also tells the agent where IDs come from, which is a definitive selection and parameter-prefill hint.

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