Update Filter

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

Annotations only say destructive/non-idempotent/open-world; the description adds the substantive policy layer — which edits are blocked by default, which are permanently refused, and that the call can return {status: "pending_user_confirmation", confirmationId} instead of applying. That outcome-shape disclosure is exactly the behavior an agent cannot infer from the hints.

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 core action is front-loaded in the first clause and every subsequent sentence carries refusal or confirmation information that earns its place. The second sentence is densely nested with parentheses and quoted policy names, costing some parseability.

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 7-parameter destructive mutation with full schema descriptions and no output schema, the description supplies the missing decision-critical context: refusal policy, confirmation return shape, and the permanently blocked filter types. Nothing needed to call it safely is absent.

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 coverage is 100% so the baseline is 3, but the description earns more by giving meaning to the otherwise bare `type` bitmask (64, 128, 256 = outgoing, archiving, periodic) and by tying `enabled` edits to the refusal rules. It does not clarify that omitted fields are left untouched rather than reset, which is the main semantic ambiguity remaining.

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?

"Change an existing filter's properties, conditions or actions" gives a specific verb plus the exact resources being mutated, which cleanly separates it from createFilter, deleteFilter and reorderFilters in the sibling set. An agent can pick this tool without opening any schema.

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 spells out when the call will be refused (forward/reply actions, editing a list holding a sending rule, types 64/128/256) and what to do on the "Ask me each time" path, which is real routing guidance. It never explicitly contrasts createFilter for new filters, and the instructed follow-up ("listFilters, confirmation: true") names a tool that does not expose a confirmation parameter, leaving the retry path ambiguous.

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