ViralRecast

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

Annotations only declare read-only and open-world. The description adds real behavioral value beyond that: credit costs per network (8 Meta, 8/12 Google, 4 LinkedIn/TikTok) and the matched/alternatives resolution semantics are precisely the operational detail an agent needs before calling.

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?

Dense and front-loaded with the platform list and per-network summary up front, then inputs, then resolution behavior, then cost. Every sentence carries information, though the single long sentence is slightly heavy.

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?

With no output schema, the description fully covers what is returned (per-network summary: number of ads, formats, oldest running, plus matched/alternatives). Combined with input forms and cost, an agent has everything needed to call and interpret results.

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 75%, and the description meaningfully augments the advertiser parameter by clarifying accepted forms (company name, website, or an alternative's id) and that website is most precise. Country/platforms defaults are already in the schema, so no credit needed there.

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?

States a specific verb+resource ('all active ads of a brand or competitor') and enumerates the exact networks covered. This is clearly distinguishable from siblings like search_ads and read_ad, which imply search/read of individual ads rather than a per-network brand summary.

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?

Gives explicit input guidance ('website, the most precise') and a resolution workflow: if 'matched' is the wrong company, tell the user and re-call with the alternative's id. It does not explicitly contrast when to use this over search_ads or read_ad, so not a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety profile is covered. The description adds a genuinely useful non-schema fact: the call costs 8 credits, which nudges the agent toward cheaper siblings when appropriate. It does not disclose anything about timeouts, rate limits, or what an empty/private profile returns.

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?

Two compact sentences with no wasted clauses, and the payoff plus cost are stated up front. The trade-off is that the brevity comes from underspecification rather than discipline.

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?

With no output schema, the description must carry the return-value burden, and it does name the payload shape at a high level. However, 'averages' is undefined (average of what metric?), and the ranking rule for outperforming posts is left ambiguous, which matters for a tool whose whole point is surfacing top performers.

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 only 67%: handle and limit are documented in-schema, but platform is a bare enum with no description. The description adds nothing about any of the three parameters, and 'the posts that most outperformed their own average' obliquely relates to limit without clarifying selection logic.

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 identifies the resource ('A creator's profile') and the two payload elements (averages, outperforming posts), which is informative. But it is a noun-phrase fragment with no verb, and it never contrasts itself with near-neighbors like analyze_post, get_account, or similar_content, so the agent must infer what 'analyze' means here.

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 only guidance is the price signal ('Costs 8 credits'), which hints that this is a heavier operation than the plain read siblings. There is no statement of when to pick this over analyze_post, read_post, or get_account, and no exclusions or preconditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond annotations: it omits images and costs 20 credits, which matters for tool selection. It does not detail outputs, but that is partly covered by comparison to read_post.

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?

Three short sentences, no filler. The compatibility note, preferred alternative, and credit cost are all front-loaded and easy to scan.

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 simple two-parameter read-only tool with annotations and a sibling relationship, the description covers the essential selection context: what it is relative to read_post, why it exists, and its cost. Because there is no output schema, it relies on read_post for return-value understanding, which is acceptable given the explicit comparison.

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 both parameters are already documented in the input schema. The description adds no parameter-specific meaning beyond implying a post URL and image omission.

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 identifies the tool by relation to the sibling read_post and specifies the key difference: it omits images. It also signals legacy/compatibility status, though it does not directly describe what the analysis returns beyond that comparison.

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?

It explicitly says "Prefer read_post" and explains that this tool is "kept for compatibility," giving a clear when-not-to-use condition and naming the preferred alternative. An agent can route between the two tools without inference.

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

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

Goes well beyond the annotations by disclosing the async contract (returns a job_id to poll with get_job), expected latency (1-5 minutes), full cost model (100 credits + 4 per video minute), the 180-minute cap, and refund-on-failure behavior. These are exactly the traits an agent needs beyond readOnlyHint/destructiveHint/openWorldHint.

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?

Four tight sentences, front-loaded with the core action, then input contract, then timing/return, then cost/eligibility. No filler and nothing repeated from the schema verbatim.

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 async, credit-consuming, open-world generation tool with no output schema, the description covers the return value (job_id), the polling path, duration, cost, limits, and licensing. An agent has everything needed to decide and invoke correctly.

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 the baseline is 3, but the description adds a genuine constraint the schema cannot express: url and job_id are mutually exclusive alternatives (one or the other), which matters given zero required parameters. It adds no further detail on the tuning params, which is acceptable since the schema documents them.

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?

States a concrete verb and resource ('Cuts a long video into vertical clips') plus the enriched outputs (captions, title, hook, hashtags). An agent can distinguish it from download_video and get_job because the description frames download as a prerequisite and get_job as the follow-up.

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?

Clearly says to pass 'url OR the job_id of a finished download' and restricts use to 'the user's own or licensed content', which is actionable eligibility guidance. It does not explicitly name a sibling alternative to use instead when the source isn't licensed, so it stops short of full when-not/alternative coverage.

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

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

Annotations already declare openWorldHint=true, readOnlyHint=false and destructiveHint=false, so the description's job is to add operating context — and it does: 10-credit cost with refund on failure, plus the 'returns a download link' outcome. It doesn't cover link expiry, rate limits, or what a failure response looks like, which keeps it short of a 5.

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?

Three short clauses, front-loaded with what it does and what it returns, followed by the usage constraint and the cost. No filler or restatement of the title.

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?

With no output schema, the description correctly carries the return value ('returns a download link'), and it disambiguates scope, cost, and accepted platforms for a one-parameter tool. Minor gaps remain around link lifetime and failure behavior, but nothing essential to a correct invocation 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?

Only one parameter and the schema already documents it at 100% ('Video link'), so the baseline is high. The description nonetheless adds real meaning by enumerating the accepted sources, which is not captured in the schema and directly affects whether the agent supplies a given URL.

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?

States a specific verb (downloads) and resource (the video) plus the exact deliverable: a download link. Naming the supported platforms (YouTube, TikTok without watermark, Instagram, X, Facebook) makes it unmistakable against siblings like transcribe_video or create_clips, which consume video rather than return the file.

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?

Adds a clear usage condition — 'For the user's own or licensed content, or internal reference' — which tells the agent when the call is legitimate. It does not, however, route the agent to or away from specific sibling tools (e.g., use transcribe_video when text is needed instead), so an explicit alternative-routing sentence is missing.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuinely non-structured information: the operation consumes 1 credit, and the search runs against a pre-built index rather than live data. It stops short of describing result format or ordering, but the cost disclosure is the important behavioral fact here.

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?

Three short sentences, front-loaded with what the tool does and the corpus it hits. Nothing is redundant and no sentence is filler.

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 3-parameter tool with 33% schema coverage and no output schema, the description leaves important gaps: what a result contains (post text? metrics? similarity score?), how to interpret ranking, and what the platform filter constrains. An agent could call it, but not predict or use the output well.

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 only 33% — only 'text' is documented, and even that merely echoes the description's 'post idea'. Neither 'limit' (capped at 20) nor 'platform' is explained anywhere, so the description should have compensated for the uncovered parameters and does not.

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?

Names a specific operation (similarity search) and a specific corpus (already-indexed viral posts), which is more precise than the bare title. However it does not distinguish itself from close siblings like similar_content or search_viral_content, so an agent could not tell from the description alone which one to reach for.

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?

"Useful to validate a post idea" gives one concrete triggering scenario, which is real usage guidance. But there is no when-not guidance, no mention of the near-duplicate siblings, and no prerequisites (e.g. whether the index must be populated first).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description should then tell the agent what the snapshot contains (per-tool granularity? current period? account identity?) but gives only a loose field list plus the cryptic "Free.", which adds almost no behavioral context.

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?

Brevity is appropriate for a no-argument read tool, and the returned data is front-loaded. However, the one-word sentence "Free." is unexplained and reads as noise rather than earning its place.

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?

With no output schema, the description must explain return values; it names three of them but omits the shape and meaning of "plan" and "price of each tool" (currency, per-call vs per-unit). Adequate for a simple read but leaves an agent guessing about what it will receive.

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?

The tool takes zero parameters, so there is no parameter information the description needs to supply. The baseline of 4 applies; nothing is misleading here.

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 states what the tool surfaces (plan, remaining credits, per-tool price) but as a noun fragment with no verb and no statement that it returns the caller's own account. The trailing "Free." is ambiguous — it could be a plan tier or a claim that the call costs nothing.

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?

There is no guidance on when to call this versus the many sibling tools. A reader can infer it should be checked before running cost-incurring operations, but that inference is never stated, and no preconditions or alternatives are named.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds that it returns both status and result (not just status) and that the call is free, which is genuinely useful beyond the annotations, but it says nothing about possible job states, whether pending jobs return partial results, or failure behavior.

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?

Two short sentences, front-loaded with what is returned; the terse 'Free.' fragment still earns its place as cost information. Nothing is extraneous.

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?

With no output schema and no annotations beyond read-only, the description carries the burden of describing the response, and 'status and result' is only a sketch – it omits the possible status values and result shape for three different job types.

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?

There is a single parameter with 100% schema coverage, so the schema already documents job_id. The description adds no format, source, or lookup guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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?

States a specific resource (a download, transcription or clips job) and what it returns (status and result), so an agent can tell it apart from list_jobs, which enumerates many jobs. It is not a tautology of the title 'Job status', though it stops short of naming the sibling it is not.

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 only implied – the required job_id makes it clear this is a follow-up call on a job previously created by download_video, transcribe_video or create_clips, but the description never says when to use it rather than list_jobs or how often to poll.

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

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

With readOnlyHint=true already covering the safety profile, the description adds useful context by noting the jobs are 'latest' (recency ordering) and 'Free' (no cost). However, it does not describe pagination, ordering details, or output behavior beyond those hints.

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 very short and front-loads the core resource. 'Free.' is terse and potentially useful, though the overall phrasing is fragmented rather than polished.

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 simple read-only list tool with one optional parameter and no output schema, the description is still too sparse: it omits the meaning of 'limit,' ordering guarantees, and when to choose this tool over get_job. The annotations cover safety, but the description does not fill the remaining gaps.

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 compensate for the single 'limit' parameter. It does not explain what 'limit' controls, its default, or how it interacts with returning the latest jobs, leaving the schema as the only source of type and bounds.

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 identifies the resource as the user's media jobs and implies recency with 'latest,' but it does not explicitly state the list/retrieve action or distinguish itself from the sibling get_job tool. 'Free' adds pricing context but not purpose clarity.

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?

There is no explicit guidance on when to use list_jobs versus get_job or other job-related tools. 'Latest' implies recency, but no alternatives or exclusions are named.

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

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

Annotations only declare readOnlyHint, so the description adds meaningful context: the data spans multiple client surfaces, each returned post includes a Viral Score, and calls are free. It does not cover ordering or recency definition, but for a simple read tool this is solid added value.

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?

A single front-loaded sentence that names the resource first and the returned fields second. The trailing 'Free.' is terse but earns its place as a cost signal.

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 read-only tool with annotations covering safety and no output schema, the description supplies enough: what is returned, from where, and the cost. Only recency window and ordering are unspecified, which is a minor gap.

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% and the single limit parameter is already documented with default and bounds. The description adds nothing about it, so the baseline 3 applies.

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?

States the specific resource (the user's recent ViralRecast queries) and the sources they come from (dashboard, Claude, ChatGPT), plus that each post carries a Viral Score. It is distinguishable from siblings like search_viral_content because it clearly returns past query history rather than live search results, though it never contrasts with them explicitly.

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?

'Free' signals a cost advantage over presumably billable search tools, which is an implicit usage hint. However, there is no explicit statement of when to retrieve history versus re-running a search, and no prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's added context is the real contribution: a credit cost (10 credits) and a precise inventory of returned fields, including the platform caveat that transcripts only apply to Meta. It does not cover failure modes for malformed or unsupported links.

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?

Two sentences, no filler: the return payload leads and the practical use plus cost follow. The parenthetical platform-URL block is long but each entry is load-bearing for input format.

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?

With no output schema, the description carries the burden of describing return contents and does so field by field, adds per-platform coverage and a cost signal, and gives input format examples. An agent has everything needed to decide to call it and construct the argument.

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 the schema already defines the single url parameter and the Meta ad ID alternative. The description adds value by supplying recognized link formats for Meta, Google, LinkedIn, and TikTok, which tells the agent what a valid input string actually looks like.

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?

Names a specific verb (read) and resource (an ad's full creative) and enumerates exactly what is returned: every version, CTA, destination, days running, and the Meta video transcript. The requirement of an ad-library link implicitly separates it from search_ads/advertiser_ads, but no sibling is named explicitly.

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?

'Use it to break down the hook, script and offer' gives a concrete use case and implies the tool is downstream of a discovery step, since it needs a library URL. It stops short of stating when not to use it or naming search_ads as the way to obtain that URL.

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

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

Goes well beyond readOnlyHint/openWorldHint: discloses that results are persisted to the user's history, that the call costs 20 credits with a 2-credit cached rate for posts read in the last 6 hours, and that transcripts fall back to automatic audio transcription when native captions are absent. That cost/caching/fallback information is exactly what an agent needs before invoking.

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?

One dense paragraph that front-loads the verb and platform list, then outputs, then usage trigger, then cost. Every clause carries information, though the parenthetical output enumeration is heavy and the cost note would read better as a trailing sentence than nested in a parenthesis.

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?

No output schema exists, so the description correctly carries the burden of describing return contents, and it does so thoroughly. Minor gap: no note on failure behavior for unsupported or private links, which matters for an openWorld tool scraping external platforms.

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 url, niche and include_images are already documented and the schema even carries the default for include_images. The description adds no semantics for niche (fit score) or include_images beyond confirming images are returned, so the schema is doing the heavy lifting — baseline 3.

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?

States a specific verb and resource ("Reads any post by its link") and immediately enumerates the supported platforms and the exact artifacts returned (transcript, slide text, comments, metrics, mind map, Viral Score). An agent can tell this apart from a generic fetch 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?

Explicitly names the triggering conditions: the user pastes a post link, or asks to summarize, understand, study or compare a post. However, it never mentions the closest-looking siblings (analyze_post, analyze_creator, transcribe_video, read_ad), so an agent must infer the boundary itself.

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

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

Beyond the readOnlyHint/openWorldHint annotations it adds context an agent cannot get elsewhere: billing cost of 4 credits per network, that only active ads are returned, and the ranking heuristic (30+ days running or 3+ variations = strong winning-ad signal). That ranking and cost disclosure materially change how an agent should budget and interpret results.

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?

Information is front-loaded: what it searches, what it returns, how it is ranked, then use cases and cost. It is dense but every clause carries content; the enumeration of return fields makes one sentence long but is not padding.

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?

With no output schema, the description appropriately enumerates the returned fields and the sort order. Remaining gaps are modest but real: result volume/pagination behavior and the 40-item limit are not addressed, so an agent cannot predict how many ads come back per network.

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 already 80%, so the schema carries most parameter meaning. The description still adds value by tying 'per network' cost to the platforms array (adding networks multiplies credits) and by framing the query as a topic/product/keyword. It doesn't clarify limit behavior or the meaning of country=ALL beyond what the schema says.

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 a concrete verb and resource ('Active ads about a topic in the public ad libraries of Meta, TikTok and LinkedIn') and enumerates what is returned (copy, headline, CTA, landing page, format, placements, days running, variations). It is clearly a keyword/topic search over ad libraries, which implicitly separates it from advertiser-scoped or single-ad siblings, but it never names those siblings explicitly.

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?

It states intended scenarios directly: 'what is trending in X ads', creative research and offers, and it discloses a transactional condition ('Costs 4 credits per network'). There is no explicit when-not guidance or pointer to alternatives such as advertiser_ads or read_ad for narrower lookups.

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

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

Beyond readOnlyHint/openWorldHint it discloses exact-phrase matching semantics, per-network coverage caveats, that results never include the author, the full result field set, gating on paid plans with an upgrade-link response on Free, and precise credit pricing including the worked example for the default configuration. This is the kind of cost and coverage disclosure an agent needs before spending credits.

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?

One dense paragraph with no wasted sentences and the differentiation front-loaded; every clause carries factual weight (networks, fields, pricing). It would scan better as short labeled lines given the number of facts, but the content is not padded.

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 7-parameter, no-output-schema, multi-network search tool, the description covers purpose, alternatives, per-network limits, return fields, author exclusion, plan gating, and cost model — everything needed to invoke it correctly and predict the response shape.

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% with inline enum descriptions, so baseline is 3; the description adds meaning the schema does not — that the default platform set is Reddit only, that 'comments' means replies on X, and that limit drives per-page credit cost (default costs 10–25). It stops short of mapping each parameter individually, hence 4 rather than 5.

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?

States a specific verb and resource — monitors mentions of a brand/competitor/product/topic — and immediately contrasts with the named sibling search_viral_content (trending, sorted by reach) versus exact-phrase matching here. An agent can pick between the two without opening either 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?

Explicitly names the alternative and the condition that selects it ('unlike search_viral_content, which finds what is trending and sorts by reach'). It also specifies which networks support what (YouTube comments unsearchable, LinkedIn returns under errors at no cost) and the paid-plan prerequisite, so the agent knows when the call will and won't yield data.

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

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

Annotations already mark it readOnly and openWorld, and the description adds important behavior beyond that: credit costs per network, higher costs for x and instagram_carousel, default networks, and the special instagram_carousel process of finding authors by hashtag and reading their grid.

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 dense but front-loaded: purpose and ranking come first, followed by defaults, platform-specific usage, and costs. Every sentence adds operational information without repetition.

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 multi-network search tool with no output schema, the description covers ranking logic, default platforms, platform-specific use cases, and costs. It leaves the exact return structure and pagination behavior unstated, which is a minor remaining gap.

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 the baseline would be 3. The description adds meaningful semantics beyond the schema, especially platform-selection guidance and per-network credit costs, though it does not elaborate the other parameters beyond what the schema already documents.

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 states a specific verb and resource: it searches trending posts about a topic and ranks them by trend_score. It also specifies the ranking components and supported networks, so an agent can distinguish this from generic search or mention tools.

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?

It gives clear platform-selection guidance: use instagram_carousel for carousels/photos and reddit/threads for discussions or text, plus the default network set when platforms is omitted. It does not explicitly compare against siblings like trending_now or search_mentions, so it stops short of full alternative routing.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds meaningful behavioral context beyond the annotation: the data comes from shared memory, the call costs 1 credit, and the required content_id originates from read_post. It does not contradict the annotations.

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 three short sentences, front-loaded with the core purpose and followed by the required input and cost. Every sentence contributes operationally useful information with no filler.

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 simple read-only lookup, the description covers purpose, source, prerequisite parameter, and credit cost. But it omits limit behavior/result count and does not clarify the relationship to the find_similar_posts sibling, leaving some gaps.

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?

The description only reinforces content_id as coming from read_post, which the schema already states. It does not explain the optional limit parameter at all, leaving 50% schema description coverage uncompensated and omitting the result-count semantics an agent would need.

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 identifies a specific resource: posts similar to one already read, drawn from ViralRecast's shared memory. It also establishes the prerequisite of passing a content_id from read_post. However, it does not distinguish this from the similarly named sibling find_similar_posts, leaving some ambiguity.

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 implied through 'Pass the content_id returned by read_post,' which tells the agent this follows a prior read operation. But there is no explicit when-to-use guidance, no when-not guidance, and no comparison to alternatives such as find_similar_posts.

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

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

Beyond the annotations (readOnlyHint=false reflecting credit consumption, openWorldHint=true), the description discloses the pricing model and the refund-on-failure guarantee, which an agent needs before spending credits. It does not mention latency, length limits, or failure modes, so it is strong but not complete.

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?

A single front-loaded sentence delivering output shape, cost, and refund policy with zero filler.

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?

No output schema exists, and the description compensates by naming what comes back (transcript plus SRT/VTT links) and what it costs. Missing only edge-case behavior such as unsupported URLs or processing time for a 2-param, open-world 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 both url and language are already documented. The description only repeats the link notion ('by link') and says nothing about the language parameter's fallback behavior, so the baseline of 3 applies.

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?

States a specific verb and resource ('Full transcript of a video by link') plus the artifacts returned ('SRT/VTT links'), which clearly separates it from download_video or create_clips. It stops short of explicitly naming a sibling, so it is clear but not differentiating by contrast.

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 implied rather than stated: an agent infers 'use this when you have a video link and need text'. The credit cost (8 + 4/min) is a useful decision input, but no when-not conditions or alternatives (e.g., create_clips, analyze_post) are named.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds useful behavioral context by disclosing the 4-credit cost and the specific external feeds involved. It does not describe pagination or return behavior, but the cost disclosure is a meaningful addition beyond the annotations.

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 one tightly written sentence with the core scope front-loaded and the credit cost appended efficiently. Every clause earns its place, with no redundant restatement of the title or schema.

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 3-parameter, read-only trending-feed tool, the description covers purpose, platforms, no-topic scope, and cost. It does not explain output structure or pagination, but no output schema exists and the essential call context is present.

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 67%, with region and platform already documented in the schema, including defaults. The description does not add further meaning for limit, region, or platform beyond what the schema provides, so it meets the baseline for a partially documented 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 identifies a specific resource and scope: trending videos right now, without a topic, from TikTok or YouTube Shorts. It implicitly distinguishes itself from topic-based siblings such as search_viral_content by emphasizing 'without a topic,' though it does not name the alternative directly.

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 implies the tool is for no-topic trending feeds and notes the credit cost, which gives some usage context. However, it does not explicitly state when to use this instead of siblings like search_viral_content or similar_content, leaving the alternative path to inference.

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