consumers_update

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does disclose a meaningful limitation (system consumers cannot be renamed or disabled) and the required permission level, which is useful context beyond the schema. However, it does not state whether the update is partial (PATCH-style, omitted fields unchanged) or full (PUT-style), nor what happens on invalid ids or failed permission checks — critical behavioral traits 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?

Three short sentences with zero filler: purpose, constraint, and permission each earn their place. The action verb and resource are front-loaded, and no sentence repeats what the name or schema already conveys.

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 9-parameter mutation tool with no annotations and no output schema, the description is not complete. The permission and system-consumer constraint are useful, but the description omits the most decision-critical facts: whether unspecified fields are preserved or reset, error behavior for invalid or system-consumer targets, and what the response looks like. An agent cannot invoke this tool correctly with high confidence based on the current information.

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, but it does not. 'Renamed' and 'disabled' only weakly map to the name and isEnabled parameters. The remaining seven parameters (applicationUrl, offloadTargetUrl, instructionHandlerUrl, offloadUseWindowsAuth, offloadPostTimeoutSeconds, maximumSimultaneousInFlightInstructions) are left entirely to name-guessing, with no explanation in either the schema or the description.

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 specific verb and resource: 'Update an existing Consumer.' The word 'existing' distinguishes it implicitly from consumers_add (creation) and consumers_delete (removal) among its siblings, and the update verb itself makes the mutation intent unambiguous. However, it does not explicitly name alternatives, so it stops short of full sibling differentiation.

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 provides a permission prerequisite ('Requires Write on Consumer') and a usage constraint ('System consumers cannot be renamed or disabled'), which implies a when-not: do not attempt to rename or disable system consumers. But it never explicitly routes the agent to an alternative tool (e.g., consumers_add for creation) or states when this tool should be preferred over similar update tools like cached_users_update.

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