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

Beyond the annotations, the description discloses that execution is asynchronous and backgrounded, that results are persisted and emailed (a real side effect not captured by destructiveHint=false), that repeats can be scheduled with 'every', and that cost is metered in 'reads' ('a video about 200'). A mild tension exists with idempotentHint=false, since the description claims an identical request returns the existing progress/result rather than starting new work.

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 behavior is front-loaded in the first sentence, which is good, but the rest is a single dense run-on paragraph whose parenthetical workflow catalogue is hard to scan. Every element is arguably useful, yet the lack of list formatting makes the workflow-to-parameter mapping unnecessarily effortful to parse.

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 an 11-parameter, async, no-output-schema tool it does well on outcome and lifecycle (background run, saved/emailed results, polling, repeats, cost). It is incomplete on 'shape' and 'country', and it says 'stop ends a repeat' without any 'stop' parameter existing in the schema, leaving the stopping mechanism unexplained for a scheduling-capable 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 coverage is 0%, so the description carries the full burden and mostly succeeds: it defines 'workflow' by enumerating valid values, explains that 'about' is interpreted differently per workflow, and documents 'model' (default is a low-cost one), 'every', 'offer', 'place', 'platform' (tiktok/instagram/youtube), and 'image'/'image_link'. Two parameters, 'shape' and 'country', are never mentioned, and the per-workflow parameter requirements are only shown by example inside parentheses rather than stated explicitly.

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 opening sentence gives a specific verb and resource with scope: 'Several steps in one job, run by Puley in the background, with every result saved and emailed', and the ten named workflows make the covered job types concrete. It does not, however, distinguish this from the sibling tools that share the same names (trend_to_video, competitor_report, customers_and_openers, ugc_ad, etc.), so an agent cannot tell from the description alone whether to call this or the single-purpose sibling.

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?

Some operational guidance is implied: 'The same request again returns its progress or the finished result' tells the agent to poll rather than re-submit, and 'every: day or week repeats it' explains scheduling. But there is no explicit when-to-use-this-vs-alternatives, no prerequisites, and no exclusions, especially against the identically named sibling tools.

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