Social Media Data API: Posts, Profiles, Comments, Search and Mentions

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

Adds real context beyond the annotations: reposts are excluded, next_cursor pages backward through the feed, and the call costs $0.01 via x402 with payment passed in _meta["x402/payment"]. That payment mechanics detail is exactly the kind of thing annotations cannot express. The only gap is no comment on rate limits or what 'not found / no match not charged' 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?

A single dense paragraph that is front-loaded with the purpose before moving to return fields and pricing. No sentence is wasted, though the pricing/payment clauses packed into the same breath make it slightly crowded.

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 return-value burden and does list returned fields (text, likes, replies, reposts, language, media, time, URL) plus pagination. The referenced 'shared social schema' is not defined anywhere, leaving a small ambiguity about the exact field 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%, so handle formats, limit range, and cursor semantics are already documented. The description restates the handle formats and says next_cursor pages back through the feed, adding modest confirmation but no new syntax or constraints beyond the schema. 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 a specific verb and resource: the latest public posts and replies of one Bluesky account, with an explicit exclusion (reposts left out) and a precise definition of what a handle may be. This distinguishes it from bluesky_profile (account metadata) and bluesky_search (cross-account search) without needing to open 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 implied rather than stated: 'one Bluesky account' suggests single-account feed browsing versus searching, but no sibling is named and no condition is given for choosing this over bluesky_search or bluesky_profile. The billing notes ('bad input is free') are policy, not selection guidance.

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 readOnly/openWorld, but the description adds substantial context beyond them: $0.01 per successful call, invalid input and not-found results are free, and payment is passed via _meta["x402/payment"] over USDC on Base. That is exactly the kind of cost and prerequisite disclosure an agent needs before invoking a paid tool.

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, front-loaded with the lookup scope and returned fields, then the commercial terms. Every clause carries information, though the pricing sentence is packed tightly and could be split for readability without loss.

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 usefully enumerates the returned fields and the 'shared social schema' convention, and it covers input forms and billing. It stops short of noting rate limits, caching, or what a 'no match' response looks like, which would matter for error handling.

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 parameter's description already spells out handle vs. did:plc/did:web vs. bsky.app URL. The description restates those accepted forms in prose without adding new syntax or defaults, so the schema does 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 ('Profile Lookup' of 'one public Bluesky account') and enumerates the returned fields (display name, bio, counts, verification, avatar, creation time, DID). The word 'one' plus the input forms (handle, DID, URL) clearly separates it from list/search siblings like bluesky_search and bluesky_posts.

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?

Implied usage is clear — fetch a single known account — and the pricing/charging rules help an agent decide whether to call. However, no sibling is named and there is no explicit when-not guidance (e.g., use bluesky_search when you only have a display name, or x_profile for the other network); the agent must infer 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?

Goes well beyond the annotations: discloses pricing ($0.01 per successful call), the x402/USDC-on-Base payment flow including the _meta["x402/payment"] key, that failed/no-match calls are uncharged, and that results are ordered newest-first with next_cursor for paging. For a paid, open-world search endpoint those are the behaviors an agent most needs before invoking it.

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 search capability and scope in the first sentence, then the return fields, then cost mechanics. The field enumeration is a long run-on ('text, author handle and display name, likes, replies, reposts, language, media links, time and URL'), but it earns its space given there is no output 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?

With no output schema, the description compensates by enumerating the returned fields and the pagination token, and it covers the payment requirement an agent must satisfy to succeed. Nothing material about calling this endpoint 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 description coverage is 100%, so the schema already explains q (search syntax), limit (1-25, default 25) and cursor. The description only adds that next_cursor from the response feeds the cursor parameter, otherwise restating the schema — baseline 3 is correct.

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 — 'find public Bluesky posts by keyword, phrase, hashtag or from:handle' — plus the transport (AT Protocol AppView) and ordering (newest first). The keyword-search framing implicitly separates it from the sibling bluesky_posts, though it never names that sibling as the non-search alternative.

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?

'Social listening on Bluesky for brands, products and topics' gives a clear usage context, and the note that bad input / no-match calls are free tells the agent when a call is cheap to attempt. It stops short of explicit when-not-to-use guidance or naming a competing tool such as bluesky_posts or social_search.

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 readOnly/openWorld annotations, the description discloses pricing ($0.02 per successful call), the x402 payment mechanism and its exact location (_meta["x402/payment"]), and the billing edge cases (bad input free, not-found/no-match not charged), plus pagination via next_cursor. These are exactly the non-obvious operational facts an agent needs before calling a paid endpoint.

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 purpose and platform scope, then return fields, use case, and payment terms — no filler sentences. The dense semicolon-chained clauses pack a lot per line, which is efficient if slightly compressed for a payment-critical instruction.

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 usefully enumerates returned fields and the pagination cursor, and it covers the payment requirement that would otherwise block a call. Minor gaps remain: no page size / result-count expectation, and no indication of what the keyword accepts (plain text vs. operators) beyond the 200-character limit.

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% and both parameters are already documented ('Search text (1-200 characters)' and 'next_cursor of the previous page'). The description's 'next_cursor gives the next page' merely restates the schema's cursor semantics, so it adds little beyond the baseline for a fully documented two-parameter 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?

States a specific verb and resource — search the public Meta Ad Library by keyword for ads on Facebook and Instagram — which immediately distinguishes it from the sibling platform searches (x_search, tiktok_search, social_search). It also enumerates what comes back per ad, so an agent knows what this tool yields, not just what it queries.

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 phrase 'Competitor ad research' implies the intended context, and the platform scope (Facebook/Instagram ads) implicitly separates it from the profile/posts siblings. However, there is no explicit when-to-use/when-not or a named alternative, so the agent must infer the routing boundary against tools like social_search or instagram_profile.

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 readOnly/openWorld annotations it discloses pricing ($0.01 per successful call), billing exceptions (bad input free, not-found/no-match not charged), and the x402 USDC-on-Base payment passed in _meta["x402/payment"]. Pagination via next_cursor and the per-hit field set are also described.

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 dense paragraph with the core purpose front-loaded and pricing/payment last, so no wasted lead-in. It is packed tightly enough that the use-case clause and field enumeration compete for attention.

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?

There is no output schema, so describing the per-hit fields and the next_cursor return value is necessary and done. Payment/auth mechanics and cost model are covered, leaving nothing an agent needs before invoking.

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% and documents q length, the story/comment enum, limit bounds and cursor semantics, so baseline is 3. The description adds only the 'next_cursor gives the next page' linkage between output and the cursor parameter, without format detail beyond the 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?

States a specific verb and resource: 'full-text search of Hacker News stories or comments' via Algolia, which separates it from most social siblings. It does not name the closest sibling (hackernews_thread) or contrast item lookup with search, so differentiation is implied rather than explicit.

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 a use context ('tech news, launches and developer discussion for market and competitor research') but no when-not guidance and no pointer to hackernews_thread for fetching a specific thread. An agent must infer that this is the discovery tool and the sibling is the detail tool.

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 cover safety (readOnly, openWorld), but the description adds real value beyond them: a hard 8-item page cap with cursor pagination, silent skipping of deleted/dead replies, plain-text normalization of item bodies, and the exact field set returned. It also discloses the billing model ($0.01 per successful call, not charged for misses) and the x402 payment mechanism, which no structured field carries.

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-loads the identity of the resource, then pagination, then returned fields, then pricing — a sensible order with little waste. The final pricing/payment sentence is dense and slightly run-on, but every clause carries 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?

With no output schema, the description compensates by enumerating the per-item fields (text, author, score, reply count, parent, time) and the shared social schema. Combined with pagination and charge semantics, nothing material is missing for correct invocation.

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 meaning the schema does not: a call returns at most 8 items regardless of the requested limit, with next_cursor paging the remainder. That clarifies the limit/cursor interaction and explains why reply counts may appear truncated.

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: fetch one Hacker News story or comment by id or news.ycombinator.com URL, together with its direct replies. The 'one item by id/URL' framing contrasts implicitly but clearly with the hackernews_search sibling, so an agent can pick 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?

Gives clear operational context: up to 8 replies per call, next_cursor to page, deleted and dead replies skipped. It stops short of explicitly naming hackernews_search as the alternative for lookups without an id, so routing is implied rather than stated.

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?

Adds substantial context the annotations do not carry: the price ($0.02 per successful call), the x402/USDC-on-Base payment mechanism with the exact _meta key, and a billing policy that free-of-charge conditions include bad input and not-found. This is exactly the kind of cost and side-effect information an agent needs before invoking a paid, non-idempotent 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-loads the resource and returned fields, then closes with pagination and pricing — a sensible order with no filler. It is dense, packed into a couple of long clauses, but every clause (fields, cursor, charge policy, payment channel) carries information.

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 compensates by enumerating the return fields and the shared social schema, and it covers pagination and payment end to end. An agent can call this correctly and anticipate the cost without consulting anything else.

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 schema, establishing a baseline of 3. The description reinforces that handle accepts a bare handle or a profile URL and that cursor walks the post feed, but adds no syntax or format detail beyond the 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?

States a specific verb and resource (fetch one public Instagram account by handle or URL) and enumerates exactly what is returned: profile fields, then recent posts and reels with their metrics, in the shared social schema. The platform name plus the field list makes it trivially distinguishable from x_profile, bluesky_profile, or linkedin_profile.

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: 'next_cursor pages through the full post feed' tells the agent how to paginate, and the handle/URL note tells it what input forms are accepted. There is no explicit when-to-use, when-not-to-use, or routing to an alternative (e.g. a search tool) for discovery-style queries.

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 readOnlyHint/openWorldHint annotations: it discloses the $0.02 per-successful-call price, the x402/USDC-on-Base payment mechanism and the exact _meta key, plus billing rules (bad input free, not-found not charged) and the refusal behavior for personal profiles. That is exactly the cost/auth context an agent needs before spending money.

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 dense paragraph that leads with the resource and scope, then pricing. The long field enumeration is useful for an agent with no output schema but is the one part that could be trimmed.

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?

Covers the input contract, the opt-in post feed with pagination, the field set that substitutes for a missing output schema, and the payment/auth and billing rules. Nothing essential to calling it correctly or safely 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 100%, so the schema already documents url, posts and cursor in comparable detail, and the description mostly restates them. The only added nuance is that posts triggers an extra vendor call and next_cursor pages the feed, which is already in the schema text, 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 a specific verb and resource ('one LinkedIn company page by URL or page name') and enumerates the returned fields (industry, size, HQ, specialties, logo, recent posts). It also explicitly excludes personal profiles, which cleanly separates it from the sibling linkedin_profile tool.

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 a clear use case ('B2B research'), states the company-pages-only constraint, and explains when to add posts=1. It never names linkedin_profile as the alternative for personal profiles, leaving the agent to infer the routing, so it stops short of a 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?

Beyond the annotations, it discloses billing semantics not captured anywhere in structured fields: bad input is free, not-found is uncharged, $0.02 per successful call, and payment passed via _meta["x402/payment"] over USDC on Base. It also pins the exact response payload, which is high-value disclosure for a metered read.

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?

Payload and scope are front-loaded before pricing details, and no sentence is wasted. The single dense colon-chained sentence for the return contract is slightly harder to parse than a short list would be.

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 specifies what comes back and what does not, plus the payment precondition required before a successful call. 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?

Only one parameter, and the schema already documents it at 100% coverage including the linkedin.com/in/<name> format, which the description essentially repeats. There is no added constraint detail (e.g. trailing slash, query strings, vanity-name edge cases), so this sits at the high-coverage 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?

It names a specific verb and resource ('one public LinkedIn profile by linkedin.com/in/ URL') and enumerates the returned fields (name, followers, about text, photo link). The '/in/' URL form also distinguishes it from the company-profile sibling without needing to name it.

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 what the tool will not return (experience, education, contact data), which implicitly scopes when to use it versus other lookups. However, it never names an alternative such as linkedin_company or people_search for those excluded needs, so routing is left partly to 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?

Annotations cover the safety profile, and the description goes well beyond them: it enumerates the returned fields per profile, notes next_cursor exists only on TikTok, and discloses pricing ($0.02 per successful call), the billing exclusions, and the x402/USDC-on-Base payment channel passed in _meta. That is exactly the operational context an agent cannot get from structured fields.

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 dense sentences, front-loaded with what is searched and what comes back, with pricing and payment last. The field enumeration ('handle, name, bio, followers, following, posts and verification') is a bit list-heavy but is load-bearing since no output schema exists.

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 compensates by listing return fields, and it covers pagination and payment. What is left unstated is rate limiting, auth requirements outside of payment, and error behavior beyond the billing carve-outs, so it is strong but not exhaustive.

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. The description does add one piece of meaning beyond the schema by scoping cursor/next_cursor to TikTok ('next_cursor on TikTok'), but q and platform semantics are left entirely to the 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?

Specific verb plus resource: 'search public TikTok, Instagram or Threads profiles by name or keyword', with an explicit scope qualifier ('unfiltered'). It distinguishes the tool as a cross-platform profile-level lookup, though it never names how it differs from siblings like social_search, tiktok_search, or instagram_profile, leaving some overlap to inference.

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 'unfiltered' label and the title hint that filtered alternatives exist elsewhere, but the description never states when to choose this over the many sibling search tools or what a cursor requires. Usage is implied rather than spelled out; only the billing conditions (bad input free, not-found uncharged) are explicit.

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 thread depth (3 reply levels), content exclusions (deleted and removed comments), pagination via next_cursor, and a full billing model: $0.02 per successful call, free on bad input, uncharged when not found, paid over x402 in _meta["x402/payment"]. That is exactly the cost and payment context 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?

One dense but well-ordered paragraph: resource and scope first, then return fields, then pagination, then billing. Every sentence carries information, though the billing clause makes it slightly packed for a single block.

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 supplies the return shape (text, author, upvotes, parent, subreddit, time, permalink in the shared social schema) plus pagination and cost, so an agent knows both what comes back and what it pays. Nothing material is missing for a 2-parameter read 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 the post (id/URL forms) and cursor parameters are already fully documented. The description only restates that post can be an id or URL and that next_cursor fetches more, adding no format detail beyond the schema; 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 a specific verb and resource: fetch one Reddit post by id or URL together with its comment thread. It also scopes the result (up to 3 reply levels, deleted/removed excluded), which makes it clearly distinct from reddit_search and youtube_comments without opening a 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 clear from the description: supply a post id or URL to get its thread, and pass next_cursor for further pages. It gives no explicit exclusions and does not name reddit_search as the alternative for finding posts, so the routing guidance is strong but not complete.

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 read-only and open-world, and the description goes well beyond them: exact cost ($0.02 per successful call), the x402 USDC-on-Base payment path via _meta["x402/payment"], and the billing rules that invalid input and no-match results are free. That is precisely the kind of non-schema, non-annotation context an agent needs before spending money.

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 capability and modes, then return payload, then cost. It is dense but every clause (fields, pagination, price, free-failure rules) carries operational weight; the payment mechanics sentence is long but necessary for a paid tool.

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 compensates by enumerating the returned per-post fields and the pagination cursor. Combined with full param coverage and explicit cost/payment handling, an agent has everything needed to call this 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 schema already documents q, subreddit and cursor with constraints. The description adds only that next_cursor feeds the next page, which is marginal beyond the schema's own 'next_cursor of the previous page' wording. 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?

Names a specific verb+resource (search public Reddit posts) and enumerates all three operating modes: keyword search, single-subreddit filter, and listing a subreddit's newest posts. It does not explicitly distinguish itself from siblings like reddit_comments or social_search, but the resource scope is unambiguous.

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 clear context for use ('Forum research and social listening') and the mode-selection logic ('give q, subreddit or both' / subreddit alone returns newest posts). It stops short of naming alternatives — e.g. when to use reddit_comments for threading or social_search for cross-platform — so there are no exclusions.

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 past the readOnly/openWorld annotations: it discloses result-eligibility filtering, the Threads no-follower-count and Instagram 10-result coverage limits, the returned fields, the not-charged cases, the $0.02 price, and the exact payment channel in _meta['x402/payment']. These are exactly the constraints an agent needs before spending money on a 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?

Every sentence carries a distinct payload: purpose, eligibility filter, platform caveats, return fields, billing rules, payment mechanics. Front-loaded with scope and no repetition of the tool title beyond the opening label.

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?

There is no output schema, yet the description enumerates the returned attributes (handle, name, bio, followers, following, posts, verification) and explains the filtered_out counter. Combined with the pricing and partial-coverage caveats, an agent has enough to call this correctly and predict the cost.

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 each parameter (q, platform, cursor) is already documented, so the description is not required to carry parameter detail. It adds only a hint that the cursor path is TikTok-specific and that q accepts a keyword — marginal value over the 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?

States a specific verb and resource ('find creator and brand accounts') plus the three platforms covered, and the account-centric framing clearly separates it from post/search siblings like tiktok_search or social_search. An agent can tell what it returns per account 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?

Implied when-to-use is clear (account lookup by name/keyword) and it discloses a significant eligibility rule: only verified or 10k+ follower accounts surface, with the rest counted in filtered_out. It never names a concrete alternative tool for the cases it excludes (e.g. fetching a known profile), so it stops short of full routing guidance.

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 only the last 20 posts are aggregated, that results are numeric only, that X depends on a key being enabled, and the full billing model (invalid input free, not-found uncharged, $0.02 per successful call via x402 USDC on Base with the _meta payment key). That payment and partial-failure-fee behavior is exactly the context an agent cannot get from the schema or 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?

Front-loads purpose and output scope, then payments, and no sentence is filler. The final pricing sentence is dense with x402/_meta detail but each clause is operationally necessary for a paid tool, so the length is justified though slightly packed.

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 return-shape burden and does so: it lists every returned metric and its averaging window, plus the null-return condition (not found / no match). Platform support, cost, and payment mechanics are all covered, leaving nothing an agent needs before calling.

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; the description adds real meaning beyond it by clarifying that the call targets exactly one account and by caveating that the 'x' enum value only works when its key is enabled — a constraint absent from the schema's flat enum list. Handle formatting is left to the schema, so it stops short of 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?

Names a specific resource (audience & engagement stats) for a specific scope (one account on TikTok/Instagram/YouTube/Threads, or X) and enumerates exactly what is returned: followers, following, posts, and average likes/comments/views over the last 20 posts plus engagement rate. The explicit negatives ('No follower names, no post text') separate it from follower-listing siblings like tiktok_followers and from post-content tools like x_posts.

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?

'Influencer vetting and benchmarking' gives a clear use context, and the 'numbers only / no follower names / no post text' framing implicitly steers agents to other tools for raw lists or content. What is missing is an explicit named alternative (e.g. social_accounts to resolve a handle, tiktok_followers for follower lists), so the routing guidance stops short of the top tier.

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 declare readOnly/openWorld/non-idempotent, and the description adds substantial context beyond them: source list, per-source pagination/truncation with coverage_from, suppression of days under 20 authors, pricing at $0.01 per successful call, x402 payment placement in _meta, and free bad input/not-found behavior. This is exactly the operational detail an agent needs before invoking a metered, source-limited aggregation tool.

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-loads the purpose and then packs source, truncation, suppression, and payment terms into dense clauses. It is longer than most definitions but every sentence carries operational information; minor tightening is possible but not required.

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 must convey return shape—and it does: daily counts, distinct authors, mean sentiment, top 10 terms, coverage_from truncation, and suppression rule. It also covers payment mechanics and source availability, leaving little an agent would need to infer.

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. The description restates the 1-7 day window and adds that days beyond a source's reach truncate via coverage_from, but does not add meaningful syntax or interpretation beyond the schema for q or days. Baseline 3 is appropriate.

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: daily mention counts, distinct authors, mean VADER sentiment, and top co-occurring terms for a brand/product/topic over 1-7 days. It clearly distinguishes itself from raw-post siblings like x_search, reddit_search, and bluesky_search by emphasizing 'aggregate only, no text, no authors.'

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 clear context: use for aggregate sentiment/mention trends across Bluesky, Hacker News, Reddit, and X rather than raw post retrieval. It doesn't explicitly name alternatives or exclusion cases, but the aggregate-only framing strongly implies when to use it instead of sibling search tools.

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?

Adds substantial context beyond the read-only/open-world annotations: partial failures are surfaced via platforms_missing and still charged, bad input is free, no-match is not charged, and the exact price plus x402 payment mechanism in _meta is given. These are the operational facts an agent needs before spending money.

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-loads the capability, then return shape, then failure/charging rules and price — every element earns its place. The single dense paragraph is slightly run-on, 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?

With no output schema, the description supplies the return shape (text, author, likes, replies, reposts, views, time, URL in a shared schema) plus pagination and partial-failure semantics. An agent has everything needed to call it 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 100%, so q, cursor, and platforms are already fully documented. The description reinforces that cursor continues every platform and platforms takes 1-3 values, but adds no syntax or format detail beyond the schema — 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 ('one keyword search on Reddit and TikTok, plus X ... run in parallel') and names the exact scope (1-3 platforms, shared schema). This clearly separates it from single-platform siblings like x_search, reddit_search, and tiktok_search.

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?

Explains the multi-platform batching behavior and that 1-3 platforms may be chosen, which implies when to use it over single-platform tools, and cursor behavior is described. It stops short of explicitly naming the single-platform alternatives or stating 'use those if you only need one source'.

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 readOnly/openWorld annotations by disclosing cost ($0.02 per successful call), the x402/USDC-on-Base payment channel and the exact _meta key, plus failure-billing rules (bad input free, not-found not charged). It does not say how many posts constitute 'recent', whether results paginate, or any rate limits, which keeps it from 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?

Two tight sentences, with purpose and return shape front-loaded before the commercial terms. Dense but every clause (fields returned, billing rules, payment path) conveys information an agent needs; nothing is 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 dutifully enumerates returned per-post fields (text, likes, replies, reposts, time, URL, author handle, verification) and the shared social schema. The main remaining gap is volume/freshness ('recent') and whether results paginate, so not quite complete.

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% and the schema description already explains the handle/URL format with @ optionality; the description repeats that same fact without adding format, normalization, or error semantics. Baseline 3 is appropriate when the schema carries the parameter detail.

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 ('recent public posts of one Threads account') with both accepted input forms, and the single-account scope clearly separates it from search siblings like social_search or x_search. An agent can pick it 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?

The phrase 'one Threads account by handle or threads.com URL' implicitly scopes usage to single-account lookups rather than keyword search, and the billing notes ('not found is not charged') imply this is a targeted fetch. It never names an alternative tool or states exclusions explicitly, so it stops short of a 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?

Goes well beyond the annotations by disclosing billing behavior (bad input free, not-found uncharged, $0.02 per successful call), the payment mechanism (x402 USDC on Base via _meta["x402/payment"]), and pagination semantics. This is exactly the auth/cost context annotations cannot convey.

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 dense sentences, front-loaded with what is returned, then cost. It is somewhat run-on (billing and payment details packed into one clause chain) but nothing is wasted.

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 describes the per-follower fields and the shared social schema, plus cost and cursor semantics. An agent has everything needed to call and budget for it 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 handle (with/without @, URL) and cursor are already documented in the schema. The description adds only the notion of next_cursor paging, which the schema repeats; 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 exact verb and resource: 'the public followers of one TikTok account by handle', which immediately separates it from tiktok_following (the reverse edge) and from tiktok_profile/videos. Pagination scope ('one page per call with next_cursor') is stated up front.

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 instructed: an agent can infer this is the followers-list tool, but there is no explicit 'use this when X, use tiktok_following when Y' or statement of prerequisites. Adequate but leaves direction/alternative selection to 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 readOnly/openWorld annotations: discloses pagination semantics, the 'public accounts only' visibility constraint, the exact per-item return fields, and full billing behavior (bad input free, not-found uncharged, $0.02 per successful call via x402 in _meta["x402/payment"]). That payment requirement is critical for correct invocation and is not in any structured field.

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 tight sentences: scope first, return shape second, cost/payment mechanics last. Every sentence carries information an agent would otherwise have to guess, 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?

With no output schema, the description still enumerates the per-account fields and the shared social schema, and it covers pagination and payment. Nothing an agent needs to call this 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 100% and both parameters are described in-schema, including accepted handle formats and that cursor is the previous page's next_cursor. The description only restates that same information, 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 a specific resource and direction: 'the public accounts one TikTok account follows, by handle.' That direction phrase is what separates it from the inverse tiktok_followers tool, though the sibling is never named, so the agent must infer the pairing.

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 by the stated purpose; there is no explicit when-to-use versus tiktok_followers, tiktok_search, or social_accounts, and no exclusions. The 'one page per call with next_cursor' note and payment terms help execution but not tool selection.

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 readOnly, openWorld, and non-idempotent behavior. The description adds substantial context beyond that: per-call price, x402 payment passed in _meta, no charge for bad input or no match, pagination via next_cursor, and returned fields.

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?

Purpose and return information are front-loaded. Pricing and payment details are packed into a long final sentence, but every element is relevant. It could be split for readability, yet it remains appropriately sized.

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 carries the return-value burden and does so: it lists fields, pagination, pricing, and failure charging. Missing only sibling routing, which is not essential to calling the tool 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 description coverage is 100%, so q and cursor are already documented. The description adds that q may be a keyword or hashtag and restates next_cursor, but does not add syntax or constraints beyond the schema. Baseline 3 is appropriate.

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: search public TikTok videos by keyword or hashtag. It is clear what the tool does, but it does not distinguish itself from siblings such as tiktok_videos, so it falls short of a 5.

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?

Mentions 'Trend and hashtag research' as an implied use case, but never names alternatives like tiktok_videos or explains when not to use this tool. Guidance is suggested rather than explicit.

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 cover read-only and open-world nature, and the description adds genuinely non-obvious behavior: per-call pricing ($0.02), x402/USDC payment passed in _meta, which failure cases are not billed, and pagination semantics. It stops short of describing rate limits or latency, and the 'idempotentHint: false' implication for cursor reuse is left implicit.

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 resource and scope are front-loaded, and the semicolon-separated clauses each carry distinct information (return fields, pagination, billing). It is dense but slightly overpacked, mixing retrieval behavior and payment mechanics in a single run-on sentence.

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 enumerates the returned fields (caption, plays, likes, comments, shares, language, cover, time, URL, creator name, verification, followers) and the pagination model, plus payment requirements. Only minor gaps remain, such as what happens when the cursor is stale or the exact shape of the next_cursor response.

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 both parameters described, so baseline is 3. The description's 'by handle or tiktok.com/@ URL' mostly restates the handle schema text, and it adds no format detail for cursor beyond the schema's 'next_cursor of the previous page.'

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 ('latest public videos of one TikTok account') and the accepted identifier forms, which cleanly separates it from siblings like tiktok_search, tiktok_followers and tiktok_following. An agent can pick this tool 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?

It implies usage via 'by handle or tiktok.com/@ URL' and explains that next_cursor pages back, but never names an alternative or states when this is preferred over tiktok_search. The billing rules ('bad input is free; not found or no match is not charged') hint at retry decisions but are not framed as guidance.

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 readOnly/openWorld annotations, it discloses pagination semantics (next_cursor gives the next page), the billing model ($0.02 per successful call via x402 USDC on Base with the payment passed in _meta["x402/payment"]), and the failure-charging policy (bad input free, not-found/empty uncharged). That is exactly the payment, cost and edge-case context the annotations cannot convey.

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, front-loaded with what is returned and in what order, followed by the cost/payment note. Dense and mostly waste-free, though the long enumerated field list is heavy for a single sentence.

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 compensates by enumerating the returned per-tweet fields, explaining pagination, and covering payment and billing edge cases. Nothing an agent needs in order to call this correctly and pay for it 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 100% and both parameters are already documented in the schema, including that handle accepts an optional @ or an x.com URL. The description restates that meaning and links next_cursor to the request's cursor field but adds no new constraints, 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?

The description names a specific verb and resource: the latest public tweets of one X account, addressed by handle or x.com URL, returned newest first. That scope separates it from x_search (keyword search) and x_profile (account metadata), though 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?

Usage is implied by 'one X (Twitter) account by handle or x.com URL', so an agent can infer this is a single-account timeline pull rather than a search. There is no explicit when-to-use / when-not guidance and no naming of x_search or x_profile as the alternative for other tasks.

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 cover the read-only/open-world profile, and the description adds genuinely non-obvious behavior: the $0.02 charge only on success, free bad input and not-found results, and the x402/USDC-on-Base payment passed via _meta["x402/payment"]. It omits things like latency or freshness of the data, keeping 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?

Purpose and target come first, followed by the returned fields, then the billing/error-cost rules – every clause carries information. The field list is long but earns its place because there is no output 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 one-parameter lookup with no output schema, the description supplies the return fields, cost model, charge conditions and the payment transport. Only minor gaps remain, such as failure modes beyond 'not found'.

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 handle parameter already documents accepting an @handle or x.com URL, so the description merely restates it. With the schema doing all the work, 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 a specific verb+resource ('X User Profile Lookup: one public X account by handle or x.com URL') and enumerates the exact fields returned, which distinguishes it from siblings like x_posts and x_search that operate on tweets rather than a single account.

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?

Makes clear the lookup is keyed on a handle or profile URL and that you get one account, not a search. It does not explicitly route the agent to a sibling (e.g., social_search or x_search) when only a display name is known, so the exclusion is implied rather than stated.

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 establish read-only, open-world, and non-idempotent behavior, but the description adds substantial operational context: newest-first ordering, pagination via next_cursor, detailed returned fields, and billing semantics including x402 payment and no charge for bad input or no matches. This is far beyond what the annotations provide.

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, beginning with the search operation and result ordering before covering return fields, pagination, use cases, and payment. Given the absence of an output schema and the importance of pricing/payment details, every section earns 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?

Even without an output schema, the description explains the returned tweet fields, parent_id semantics, and pagination through next_cursor. It also covers payment requirements and billing edge cases, making the definition complete enough for an agent to invoke it 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 both parameters are already documented in the input schema. The description reinforces that q is a keyword/phrase search and that cursor maps to the previous page's next_cursor, but it does not add significant syntax or constraint detail beyond the 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 states a specific verb and resource: searching public Twitter/X tweets by keyword or phrase, newest first. It also distinguishes the operation from profile or generic post-listing tools by focusing on keyword/phrase matching and public search results.

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 provides clear use contexts such as social listening, brand monitoring, and research. However, it does not explicitly name when to use this instead of nearby siblings like x_posts or social_search, so it lacks full alternative routing guidance.

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 readOnly/openWorld annotations it discloses unusually valuable operational facts: the cost ($0.02 per successful call), the payment mechanism (_meta["x402/payment"], USDC on Base), and the billing edge cases (bad input free, not-found/no-match not charged). It omits rate limits and whether disabled comments return an error or an empty set, 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?

It is a single dense paragraph that front-loads purpose, then return shape, use case, and finally pricing/payment. Every sentence carries information, though the packed semicolon-heavy style makes the payment requirement easy to skim past.

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?

There is no output schema, so the description compensates by enumerating the per-comment fields and the shared social schema, plus pagination via next_cursor. For a two-parameter read-only tool, an agent has everything needed to call it and interpret the result.

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?

With 100% schema description coverage, both parameters are already documented, including accepted URL forms. The description adds only that next_cursor maps to the cursor parameter for pagination, a marginal clarification over the schema's own wording — 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?

It states a specific verb and resource — the public comments on one YouTube video, addressed by id or URL — so the agent knows exactly what it retrieves. It does not explicitly contrast with the nearest sibling (youtube_transcript), but the resource difference is self-evident.

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?

"Audience feedback and sentiment research" implies a use context, and the pricing note hints that this is a paid call to spend deliberately. However, there is no explicit when-to-use / when-not guidance and it never names alternatives such as youtube_transcript or reddit_comments for adjacent needs.

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 readOnly/openWorld annotations by disclosing pricing ($0.02 per successful call), x402 payment mechanics via _meta["x402/payment"], what is not charged (missing captions, bad input, not found), and the shape of returned data (full text plus timed segments in milliseconds with caption language). These are substantive behavioral traits 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?

Front-loads the identity of the resource and then packs return contents and billing details into a tight paragraph. It is dense with no throwaway sentences, though the pricing and payment-mechanics clauses could be split for readability.

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 one parameter, no output schema, and annotations covering safety and open-world access, the description covers return contents, billing, and failure-charging behavior. It leaves minor gaps such as how caption language is selected when multiple captions exist, which keeps it from a 5.

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 already documents the video parameter, the 11-character id form, and accepted watch/shorts/live/youtu.be URL forms. The description largely repeats the same accepted input forms rather than adding new meaning, so 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 a specific verb and resource: retrieve the caption transcript of one YouTube video, with input accepted as id or URL. It is clearly distinguishable from the sibling youtube_comments tool because it names the transcript/captions artifact 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?

Provides clear context with 'Video to text for summaries and research' and scope of one video by id/URL. It does not name an alternative tool or give explicit when-not-to-use conditions, so it stops short of a 5.

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