mmar_update_class_instance

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait: the tool expects a complete desired state, meaning it replaces the entire instance rather than patching fields. It also hints at supported fields (position, attribute instances). However, it does not disclose side effects, reversibility, permission requirements, or what happens to omitted fields, leaving gaps for a mutation tool.

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 sentence that front-loads the verb and resource, then provides a concise instruction about the required payload. No unnecessary words or repetition of schema details.

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?

The description covers the core purpose and the critical 'full-state' requirement, but lacks details on expected response, error conditions, or the exact structure of the JSON data. Without annotations or an output schema, the agent must infer several behavioral aspects. The trailing 'etc.' adds ambiguity about field completeness.

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?

The schema already documents both parameters with 100% coverage. The description adds meaning to class_instance_data by specifying it must represent the complete desired state including position and attribute instances, which is more specific than the schema's 'updated ClassInstance data'.

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 states the verb ('Update') and resource ('existing class instance'), and distinguishes from sibling tools by emphasizing 'complete desired state' which is unique to update operations. The mention of 'position, attribute instances, etc.' clarifies the scope of the update.

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 implies the tool is for modifying an existing class instance and explicitly requires sending the complete desired state, signaling this is a full replacement rather than a partial update. However, it does not mention when to use this over alternatives like update_relationclass_instance or provide exclusions.

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