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

Annotations only declare openWorld/readOnly/destructive, so the description carries most of the weight and does it well: it discloses credit consumption per draft, a small link fee, its absence on remix, a free dedup path for identical requests, and a ~40 second sync cutoff that falls back to a job_id for get_generation. The one gap is that the 40-second boundary is hedged as "about", leaving timeout behavior imprecise, and no pagination/output-shape detail is given (though none is needed for a generation call).

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?

Front-loaded with the capability, then routing, then cost and async behavior – a sensible information hierarchy with no filler sentences. It is dense and runs long in a single paragraph, which slightly hurts scanability for a tool with six distinct modes, but nothing is redundant.

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 complex, nested, multi-mode generation tool with no output schema, the description covers all three input modes, the nested remix keying options, cost mechanics, dedup behavior, and the async handoff to get_generation. The "it reads the creator's profile, voice examples and Creator Brain itself, so nothing needs to be looked up first" line removes the most likely agent misstep of calling get_voice or get_creator_brain first.

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 baseline is 3, but the description adds real meaning the schema cannot: it states the implicit prerequisite for remix (post must come from list_inspiration, find_viral_posts or get_creator_report), ties source_url to a fee and remix to none, and frames fresh as re-running a request from "the last few minutes" in cost terms. It does not explain the carousel_style house-style fallback beyond the schema, but overall it beats the 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?

"Writes drafts in the creator's saved voice, in one or more formats ... from an idea, a link, or a post to remix" names the verb, the resource, the input modes, and the output artifact in one sentence. The format list (Reels/TikTok scripts, LinkedIn, X, newsletter, YouTube, carousel) plus the explicit contrast with estimate_cost and get_generation makes it unmistakable against siblings.

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?

Routes the agent explicitly: remix for a post from list_inspiration, find_viral_posts or get_creator_report; fresh for new versions of a recent request; estimate_cost to see the total first. These are concrete when-to-use conditions tied to named sibling tools, not inference.

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