create_campaign

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that the script generation is synchronous and takes 5 to 15 seconds, that the campaign starts as PENDING, and that the result is JSON with campaign data, ID, and generated scripts. It does not mention failure modes or authorization requirements, but the key operational behaviors are transparent.

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 well organized: a concise purpose statement, key behavioral notes, a labeled parameter list, and a return-value summary. Each bullet earns its place and provides concrete examples without unnecessary fluff.

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 creation tool with zero schema descriptions and no annotations, the description is remarkably complete. It covers what the tool does, how long it takes, resulting state, every parameter's meaning, defaults, and the response shape. Little is left for the agent to guess.

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 fully explain the parameters. It does: every parameter is listed with a human-readable meaning, examples, defaults, and allowed values for audio_style and production_mode. It also clarifies relationship hints like free_text being optional when data is sent, adding real semantic value beyond the bare JSON schema.

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 a specific verb and resource: 'Cria uma nova campanha comercial no QuickerSpot e gera o roteiro em formato texto via IA.' This clearly distinguishes it from read-only siblings like list_campaigns and get_campaign_status, and from create_recado, by defining the exact object and outcome.

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 practical context by noting that voice selection should be done via list_voices and that the campaign starts in PENDING state waiting for script approval, which implies subsequent use of approve_script. It does not explicitly name alternatives or say when not to use the tool, but the usage context is clear enough.

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