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

Annotations declare destructiveHint=true but not what is destroyed; the description discloses that archive closes the run and, importantly, that adds are append-only ('Adding cases/milestones appends, never replaces') and that each added case spawns a new run instance. It does not mention permissions/auth or reversibility of archive. No contradiction with the readOnlyHint=false / destructiveHint=true 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?

Front-loaded with the core action, then a dense but organized enumeration of mutatable fields with their constraints. It is long for one paragraph and relies on semicolons, but for a 13-parameter tool with several interacting modes almost every clause carries operational information.

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?

No output schema exists, yet the description covers the exception path ('a closed/archived run returns a clear message') and the append-vs-replace behavior an agent must anticipate. Auth requirements and the exact behavior of configuration_ids with apply_to_test_case_ids defaults could be clearer, but the definition is otherwise self-sufficient for a complex update tool.

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 baseline is 3, but the description adds cross-parameter meaning the schema alone does not: configuration_id replaces vs configuration_ids appends, apply_to_test_case_ids scopes both, and configuration_id must be kane-supported and platform-compatible on KaneAI runs. That is real semantic value beyond the per-field text.

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 ('Update an open test run') and then enumerates the exact facets that can be changed (status, title, objective, milestones, folder, cases, configuration, sequential, archive). An agent can immediately separate this from tm_create_test_run, tm_get_test_runs and tm_update_test_case.

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 concrete preconditions: 'Only open (active) runs can be updated; a closed/archived run returns a clear message', plus field-level gating (status is manual-only, is_sequential is KaneAI-only, cases must match the run's type). It stops short of naming a sibling alternative for related write paths (e.g. tm_record_test_results), but the when-conditions are explicit.

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