Update an agent

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

Annotations already mark the tool as non-read-only, destructive, and idempotent. The description adds useful behavioral context beyond annotations by explaining that no_schedule=true drains the agent, allowing it to finish current work and accept nothing new. It also surfaces the admin-only requirement, which is not present in the 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?

The description is two short sentences, front-loaded with the primary action and immediately covering the most behaviorally important detail. Every sentence earns its place, and there is no filler or repetition of schema content.

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?

Given the full parameter schema coverage and the presence of an output schema, the description covers the critical non-obvious context: admin-only access and the meaning of no_schedule as a drain switch. It is sufficiently complete for an agent to select and safely invoke this tool correctly.

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 100%, so the schema documents every parameter. The description adds a useful clarification for no_schedule with the drain-switch explanation, but it largely repeats the schema's own parameter description. It does not describe name, org_id, or custom_labels beyond what the schema already provides.

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 clear verb and resource: 'Changes an agent.' It also includes the notable 'Admin only' restriction. It does not enumerate what can be changed, but the title and input schema cover that, and the resource clearly differentiates it from sibling update_* tools like update_user or update_secret.

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 gives a clear usage context: this is for changing an agent and is restricted to admins. It also explains a specific scenario for no_schedule=true, which is the drain switch. It does not explicitly mention when not to use it or discuss alternatives, but for an update operation on a specific resource this is adequate.

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