update_run

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

With no annotations provided, the description carries the full disclosure burden and does so well. It reveals the permanent flip of the auto_named flag, the partial-update behavior, notes clearing semantics via empty string, and field constraints like the 255-character name cap and tag limits.

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 front-loaded with purpose and then scoped through a clearly structured Args list. The short rationale with naming examples is not filler; it explains the permanent auto_named flag behavior that matters for using the tool correctly. No sentence is wasted.

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 is complete for 6 parameters and covers required fields, allowed values, behavioral nuances, and constraints. The only notable gap is that it does not describe the return value or error behavior, which is relevant because there is no output schema and no annotations to supply that context.

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%, so the description must compensate, and it does. It explains every parameter beyond the schema: the artifact type and id prefixes, that model_hash identifies the run's model, the meaning of run_id, name as a non-empty capped display name, notes as clearable free text, and tags as a replacement list with size limits.

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 opens with a specific verb and resource: 'Rename / annotate a saved optimizer or scenario run.' It clearly distinguishes this tool from run execution, retrieval, and model/project rename tools among the siblings by naming the exact action and artifact types it operates on.

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 first sentence gives clear context for when to use the tool: when a saved run needs renaming or annotating. It also explains why renaming is useful and clarifies that only provided fields are changed, but it does not explicitly name alternatives or state when not to use this tool.

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