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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that the call consumes one analysis from the account's monthly plan regardless of length, that repeating the same URL does not consume another, that results may be asynchronous with a job_id requiring a get_analysis poll after 30-60 seconds, and that a finished result ends with next_steps. It also explains the divergent thread content_type output. There is a mild tension between idempotentHint=false and the 'repeating the same URL does not' billing note, but that is a cost statement, not a claim about side-effect-free execution, so it is not a contradiction.

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?

It is front-loaded with a 'Use this when...' trigger list, followed by output, cost, async behavior, and exclusions in that order. It is long and a few clauses are crammed into run-on sentences, but nearly every sentence carries operational information an agent needs.

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 one-parameter async analysis tool with no output schema, it covers triggers, required input, cost model, job polling procedure, output shape (hook score, viral reasons, script, caption, hashtags, next_steps), and the Threads variant. Nothing an agent needs to invoke and follow up correctly is missing.

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% for the single url parameter, but the description compensates by constraining what counts as a valid link: a public Instagram Reel, carousel or photo post, YouTube Short, TikTok, or one Threads post on threads.net/threads.com, not a profile. That is meaningful validation guidance the bare string type does not convey, though no URL format examples are given.

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 names the specific verb and resources (why a short video or Instagram carousel went viral: hook score, viral reasons, ready-to-shoot script, caption, hashtags) and enumerates the exact supported inputs (public Instagram Reel, carousel or photo post, YouTube Short, TikTok, single Threads post, explicitly not a profile). It also distinguishes itself from get_analysis for reopening a finished analysis, so an agent can separate it from siblings without opening the schema.

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?

Usage is spelled out with concrete triggers (user asks why it went viral, how strong the hook is, wants a script, or talks about their own flops/next film) and the required precondition of a link, with the instruction to ask the user when it is missing. It also states the negative case: do not use to reopen a finished analysis, use get_analysis instead.

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