update_config

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

It discloses important non-obvious behavior: each call creates a new version instead of overwriting, changes apply immediately to all API keys and prompts, only provided fields change, and the slug is immutable. With only false annotations, this description carries the full burden of safety and semantics, and it does so comprehensively.

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 dense but every sentence earns its place: versioning behavior, editable fields and slug constraint, immediate effects and prerequisite workflow, and return value. It avoids fluff while covering all critical operational details for a complex update tool.

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 tool's complexity (versioning, partial updates, global side effects) and the availability of an output schema, the description provides all necessary context: how to prepare, what changes, what remains fixed, how to recover, and what is returned. No significant gaps remain.

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 baseline is 3. The description adds valuable semantics beyond the schema by clarifying partial-update behavior ('Only provided fields change') and the immutability of the slug. It also enumerates the editable settings, reinforcing which parameters are meaningful for an update call.

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 'Update a config by slug', which is a specific verb+resource statement. It distinguishes this from create_config by noting slug stays fixed and every call creates a new version, and from delete_config by the recoverability of old versions. The editable field groups are enumerated, making the scope clear.

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 clear context by instructing to get the slug from list_configs and review current settings with get_config before editing. It also mentions list_config_versions for recovery of earlier versions. However, it does not explicitly name create_config as the alternative for creating a new slug, so the when-not-to-use guidance is only implicit.

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