zuckerbot_analyse_account_history

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

With no annotations, the description fully discloses behavior: for accounts with history, it returns aggregated metrics, top creatives, and CPL ranges; for new accounts, it returns is_cold_start=true and industry benchmarks. This transparently sets expectations about the two distinct outcomes based on account history.

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 only two sentences: one explaining the tool's function for both account types, and one providing usage guidance. Every sentence is valuable and there is no redundancy, making it concise and well-structured.

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 no output schema, the description covers return values (aggregated metrics, top creatives, CPL ranges for history; is_cold_start and benchmarks for new accounts). It also explains the cold start scenario. However, it could be slightly more detailed on the exact format of aggregated metrics, but overall it is sufficiently complete for its role as a first-step analysis tool.

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 baseline is 3. The description does not add significant new meaning beyond the schema; it reiterates parameter purposes (e.g., business_id auto-resolves, lookback_days range, target_audience optional check). No additional semantics are provided, so score remains at baseline.

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 analyzes historical ad performance for a business, distinguishes between accounts with history (returns aggregated metrics, top creatives, CPL ranges) and new accounts (cold start flag with industry benchmarks), and positions it as the first step in campaign planning. This is specific and differentiates from sibling tools like zuckerbot_get_account_insights.

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?

Explicitly instructs 'Use this as the FIRST step in campaign planning — feed the result into zuckerbot_recommend_campaign_structure.' This provides clear context and a sequential workflow, effectively guiding the agent on when to use this tool versus alternatives.

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