cases_update_case

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says fields are updated but doesn't indicate whether it's a partial update, how existing values are handled, required permissions, or side effects on other resources. For a mutation tool, this is a significant gap.

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, front-loaded sentence with zero filler, making it efficient for quick reading. However, the brevity causes it to omit critical details, so it doesn't fully earn a 5.

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 3-parameter mutation tool with no annotations and no schema descriptions, the description covers only the basic action. While an output schema exists and return format is not needed, update semantics, valid field names, and error or edge-case behavior are entirely absent, leaving an AI agent with incomplete guidance.

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 description coverage is 0%, and the description only hints at the 'fields' parameter via examples. It doesn't explain the roles of domain_id and case_id, nor the expected format or permissible keys of the fields map beyond string values. Parameter meaning must be inferred almost entirely from parameter names.

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 clearly identifies the action ('Update'), the resource ('case fields'), and provides examples ('status, assignment'), making its purpose unambiguous. It distinguishes itself from get/delete/create case operations, though it lacks explicit scope qualifiers about which case types or constraints.

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?

No guidance on when to use this tool versus alternatives such as cases_create_case or cases_list_cases_for_contact. It doesn't state prerequisites (e.g., the case must exist) or when this should be preferred over other case-related mutations.

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