Enable or configure an agent

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

Annotations only set readOnlyHint=false and openWorldHint=false, so the description carries the burden for behavioral disclosure. It does disclose that turning on/off is a mutation, that live agents require confirm, and that two agent types never change status. However, it does not explain side effects like whether other fields are reset when enabled is toggled, what happens if confirm is missing for a live agent, or whether changes are reversible. The information given is helpful but incomplete 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 two sentences, front-loaded with the core action and then adding constraints. Every sentence adds value: the first states the primary function and target fields; the second covers the confirmation requirement and immutable agents. There is no filler or redundancy.

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 tool with 5 parameters (1 required), no output schema, and minimal annotations, the description covers the essential call requirements: what you can set, the special confirmation condition, and the two agent types that are unaffected. However, it omits details like whether optional parameters are additive or resets, how to determine if an agent is 'live', and what the response looks like. It is adequate for a straightforward configuration setter but leaves some edge cases to inference.

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 clarify parameters. It explicitly maps enabled to on/off, names every_ms and account_id as settable fields, and explains confirm as required for live agents. Agent_id is not described but is self-evident from the enum. The description covers the main intents of most parameters, but it does not elaborate on the interplay between confirm and enabled, nor on the meaning of every_ms (e.g., is it an interval?) beyond the schema's minimum. This is sufficient but not exhaustive.

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 (turn on/off, set) with a specific resource (agent) and names the configurable fields (every_ms, account_id). It also adds precision by noting that analytics_digest and paused_audit never change status, distinguishing behavior per agent type. This fully differentiates it from any sibling tool, such as the read-only agents_list.

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 usage (configure an agent) and gives a key precondition: live agents need confirm=true. It also warns that analytics_digest and paused_audit are immutable. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use agents_list to inspect status first, or how this differs from scheduler_setup). The guidance is contextual but lacks explicit routing or exclusions beyond the two agent types.

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