update_chute_session

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

It discloses an important behavioral trait: the widget grid is a full replacement list, not an incremental edit. It also clarifies the state constraint that only PROPOSED sessions are editable, which goes beyond the minimal readOnlyHint=false and destructiveHint=false annotations. This gives the agent meaningful behavior information for invoking the tool safely.

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 two sentences with no wasted words. It front-loads the action and state constraint, then adds the crucial replacement semantics and exclusion. Every clause contributes useful 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?

For a 6-parameter mutation with no output schema, the description covers the core operation, the session-state restriction, and the full-replacement semantics. It could be slightly more explicit about what happens when optional fields like group_name or record_type are provided, but the schema covers those parameters, so the gap is minor.

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 83%, so the baseline is 3. The description adds value by mapping the tool's purpose to the name and widgets parameters ('rename it or replace its widget grid') and pointing to create_chute_session for widget types and arrangement rules. It doesn't elaborate on farm_id, group_name, or record_type, but the schema already documents those.

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 states a precise action and resource: 'Revise a PROPOSED chute session before the user starts it,' with concrete operations (rename or replace the widget grid). It also contrasts with create_chute_session by referencing the same widget rules, making it easy to distinguish from creation/list/get siblings.

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?

It explicitly says when to use the tool: before the user starts the session. It also explicitly says when not to use it: started sessions cannot be changed here, and only the operator can edit those in the app. This provides clear routing guidance relative to create_chute_session and app-side editing.

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