update_campaign

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

No annotations are provided, so the description carries the full burden. It discloses the draft state constraint and that it is a mutation, but omits important behavioral details: what happens if the campaign is not in draft (error? ignored?), whether partial updates are allowed (only campaign_id is required, implying partial updates), what the tool returns (success indicator or full campaign object?), and any rate limits or side effects. This is insufficient for a tool with 16 parameters and complex conditional fields.

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 extremely concise, using two clear parts: the tool name ('Actualizar campaña') and a single sentence explaining its purpose with a key condition and mutation tag. Every element earns its place, and there is no superfluous text.

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 (16 parameters including nested objects, boolean flags, and conditional fields) and the presence of many sibling tools for campaign state changes, the description is too sparse. It does not mention return values (no output schema), error handling, or the workflow for updating a campaign (e.g., that after updating in draft, an approval step might be needed). The lack of completeness forces the agent to infer too much.

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?

The input schema provides 100% coverage with descriptions for all 16 parameters. The description adds no additional meaning or constraints beyond what is already in the schema (e.g., it does not explain the relationship between `is_recurring` and `recurring_cron` or the meaning of `segment_filters`). The baseline is 3 since the schema already does the heavy lifting.

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 clearly states the tool's action ('Actualizar campaña' / update campaign) and specifies the resource ('campaña de marketing masivo existente') and a key condition ('solo en estado borrador'), which effectively distinguishes it from sibling tools like create_campaign, delete_campaign, and approve_campaign.

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 explicitly notes that the campaign must be in 'borrador' (draft) state to be updated, which is a crucial usage condition. The [mutation] tag signals it's a modification operation. However, it does not mention what to do if the campaign is not in draft or provide explicit alternatives among the many campaign state-change siblings (e.g., approve, archive), leaving some ambiguity for the agent.

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