TrueScrape

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

Annotations already cover readOnly/openWorld, so the description's real contribution is the credit cost ('Costs 3 credits') and the disclosure of what the payload contains, which helps an agent decide whether to spend. It stops short of noting rate limits, caching behavior (relevant given the cache_max_age param), or result volume.

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 with the core scope front-loaded. The second sentence slightly restates the first ('All seller offers for a product' / 'Every offer on an Amazon listing') rather than adding new information, costing a little density but nothing harmful.

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 listing the returned fields, and it discloses the credit cost — the two things an agent most needs. Missing only practical invocation details such as pagination or how many offers typically come back.

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 80%, so parameters like asin, tld and the condition enum are already documented in the schema. The description adds only that condition is a dimension of each offer, not how the condition parameter filters results — 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?

The description names the resource and its scope explicitly: 'All seller offers for a product' with the returned fields enumerated (price, seller, condition, Prime eligibility, shipping). This separates it from amazon_product (product details) at a conceptual level, though it never names that sibling to make the split airtight.

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 phrase 'all seller offers for a product' hints you use it when you need competing seller pricing rather than catalog data. There is no explicit 'use this instead of amazon_product when...' statement, and the credit cost is stated without guidance on when that trade-off is worth it.

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 safety (readOnlyHint) and open-world scope, so the bar is lower. The description still adds real value beyond them by disclosing the 3-credit cost and clarifying that the data is public and includes an inline review sample. It omits caching semantics, which matters given the cache_max_age parameter.

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 the resource and return fields, with the cost appended as a discrete operational note. Nothing is redundant with the name or 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?

For a read-only lookup with no output schema, listing the returned fields is genuinely useful and covers the main information need. The gap is the undescribed cache_max_age parameter and the absence of any note on failure modes for invalid ASINs or unavailable marketplaces.

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%, with asin and tld well documented in the schema, so the baseline is 3. The description adds no parameter-level meaning at all — nothing about how the marketplace TLD interacts with country_code, and nothing at all about cache_max_age, which the schema leaves undescribed.

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 (retrieves) and resource (one Amazon listing) and enumerates exactly what is returned: title, brand, price, availability, rating, specifications, review sample. The phrase 'one Amazon listing' implicitly separates it from search-style siblings, but it never names amazon_search or amazon_offers to make the distinction 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?

Usage is only implied: the required ASIN signals this is a lookup-by-identifier tool rather than a discovery tool, and the credit cost gives a rough sense of expense. There is no explicit when-to-use guidance and no statement of when to prefer amazon_offers or amazon_search instead.

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 the safety profile (readOnlyHint, openWorldHint), but the description adds a genuinely non-obvious operational fact: each call costs 3 credits. It does not disclose result counts, rate limits, or whether results are scraped/cached at call time, 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 short sentences with the substantive content front-loaded; the credit cost is surfaced immediately. The leading fragment 'Search results.' largely restates the title and is the only wasted text.

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 does a reasonable job listing returned fields, and the credit cost is disclosed. But it omits pagination behavior despite a 'page' param, does not say how many results per page come back, and gives no guidance on tld versus country_code — gaps an agent would hit on the first call.

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 60%, with tld, query, and country_code documented in-schema while page and cache_max_age are bare. The description adds no parameter meaning beyond restating that a query drives the search, so the baseline 3 for partial coverage 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 ('Public Amazon search results for a query') and enumerates the per-item fields returned (position, price, rating, badges), which implicitly separates it from amazon_product/amazon_offers. It does not explicitly name or contrast with those siblings, so it stops 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?

There is no explicit when-to-use statement or named alternative, so the agent must infer from the return fields that this is the discovery/listing tool and that amazon_product or amazon_offers handle detail lookups. Usage 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 only say readOnly and openWorld; the description adds substantive behavior the agent could not otherwise know: continuation pages return feed only, all identity fields are null from page two onward, ASINs are limited to the first screenful while itemCount is the true total, and each call costs 1 credit. These are exactly the non-obvious traits that would otherwise cause misinterpretation of 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?

Front-loaded with the purpose in one sentence, then pagination, then the continuation-page caveat and credit cost — every sentence carries distinct information. Slightly dense run-on phrasing in the parenthetical field listing costs it the top mark, but there is 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 does the heavy lifting of describing the return shape (lists, videos, photos, ASINs vs itemCount) and pagination semantics. The only real gap is the undefined `cache_max_age` parameter and the absence of any error/failure behavior.

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 67%, and the description adds the response-side field name (`pagination.cursor`) plus the constraint that the same shop URL must accompany the token — information that is not inferable without an output schema. It does not explain `cache_max_age` at all, leaving one of three parameters undocumented in both places.

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 creator's public Amazon storefront) and enumerates exactly what it returns: profile name, exposed product links, idea lists with itemCount, shoppable videos and photos. This clearly separates it from siblings like amazon_product, amazon_search and amazon_offers, which return catalog objects rather than a storefront feed.

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 first request needs no pageToken" and "Pass `pagination.cursor` back as `pageToken`, unchanged, with the same shop URL" give explicit operational guidance for the paginated flow. It never names a sibling alternative or a when-not-to-use case (e.g. versus amazon_product for a single ASIN), 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real value beyond that: a cost signal ('Costs 1 credit') and the fact that track listing and copyright are nested in `raw`. It stops short of describing pagination, error behavior, or failure modes for invalid ids.

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 compact sentences, front-loaded with the resource and its fields, then the raw-data caveat, then the cost. No wasted words.

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 burden of describing return shape, listing top-level fields and explaining what lives in `raw`. The phantom `include_raw` parameter is the only inconsistency that leaves an agent uncertain about how to obtain the track listing.

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 references `include_raw=true`, but no such parameter exists in the input schema — a mismatch that could send an agent looking for a nonexistent argument. Meanwhile `cache_max_age` (the other 50% of schema coverage) is undocumented in both schema and description, so the description does not compensate for the coverage gap.

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 enumerates the returned fields (artist, release date, genre, artwork, runtime), which is far more than a restatement of the title. It does not explicitly distinguish itself from close siblings like appleMusic_track or appleMusic_artist, though 'Album' is a reasonably distinct noun.

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 you call this when you have an album id or URL. The one genuine usage hint is the conditional 'behind include_raw=true' for track listings, but there is no explicit when-not or 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?

Adds real context beyond the readOnlyHint/openWorldHint annotations: it discloses that follower and play counts are null rather than guessed, and that each call costs 1 credit. This tells the agent what data is unavailable and the cost, which the annotations do not cover.

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 front-loaded sentences: purpose first, then contents, then caveats. Each carries information; no filler. Slightly compressed purpose but efficient overall.

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 describes return contents (bio, image, banner, genre) and the null-field behavior, which is enough to set expectations. The only gap is the undocumented cache_max_age parameter.

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 50%; the required 'id' parameter is already well-documented in the schema (id or URL form). The other parameter, cache_max_age, is undocumented in both schema and description, so the description fails to close the remaining gap.

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 clear resource ('Public Apple Music artist page') and enumerates the content returned: editorial bio, artist image, banner, and genre. The resource distinction from album/track siblings is implicit in the content list, though it doesn't name an alternative tool 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?

No explicit when-to-use or when-not-to-use guidance, and no reference to a sibling such as appleMusic_search for resolving an id. The only usage-adjacent note is 'Costs 1 credit,' which flags cost but not selection context.

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, but the description adds useful behavioral context: tracks and albums are returned as posts, artists as creators, and each call costs 1 credit. 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 short and front-loaded with purpose and return-shape information. The opening "Search." is redundant with the title, but the remaining sentences are efficient.

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 search tool with no output schema, the description adequately covers purpose, return shape, and cost. It leaves some schema-level details like limit and caching to the input schema, which is reasonable given annotation coverage.

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 60%, so some parameter meaning is already documented. The description mentions track/album/artist categories matching the type enum, but adds no detail on query, limit, country, or cache_max_age 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 gives a specific verb and resource: "Search the Apple Music catalogue for tracks, albums or artists." It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools like appleMusic_track or appleMusic_artist.

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 usage by saying it searches the catalogue for tracks, albums, or artists, but it gives no explicit when-to-use guidance or alternatives. It does not mention when to use appleMusic_album, appleMusic_artist, or appleMusic_track instead.

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 and openWorld, so the bar is lower, and the description still adds two things they do not: that only public track data is returned and that each call costs 1 credit. It also discloses the response fields, which matters because there is no output schema.

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, purpose front-loaded and the field list plus the credit cost appended. Nothing is redundant or 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?

With no output schema and no annotations covering return shape, the field enumeration and credit cost make the tool callable without opening anything else. The only real hole is the unexplained cache_max_age parameter, which is minor for a read-only lookup.

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 says nothing about parameters; the 'id' formats (numeric id, /song/ URL, album URL with ?i=) are documented only in the schema. With just 50% schema coverage, the second parameter (cache_max_age) is undocumented in both places, so the description does not compensate for the gap.

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 ('Track details') and enumerates the concrete fields returned (artist, album, duration, genre, release date, preview URL), which unambiguously separates it from appleMusic_album, appleMusic_artist and appleMusic_search. It stops short of naming a sibling, so it is clear but not maximally differentiated.

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: an agent can infer this is the detail lookup once a track id is known, but the description never says when to prefer it over appleMusic_search or how to obtain the id first. No exclusions or prerequisites are given.

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 context: the data is from a 'public' channel, the cost is 1 credit, and it lists which fields come back. It does not mention any failure mode for unknown/private channels or what happens on cache hits, leaving behavioral coverage partial.

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 the purpose, then the returned fields, then the cost. Every sentence carries information an agent can use, with no filler. Slightly telegraphic, and the field enumeration could be compressed, but it is efficient.

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's list of returned fields is genuinely valuable and largely fills the return-value gap. However, the undocumented cache_max_age parameter and the total absence of usage/alternative guidance leave the definition only adequate for a read-only profile tool with many sibling channel tools.

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 50%: the 'channel' parameter is well documented in the schema (id, name, or URL), but cache_max_age is undocumented in both schema and description. The description says nothing about any parameter, so it fails to compensate for the coverage gap at this complexity level.

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+resource combination: fetching a public BitChute channel profile. It enumerates the returned fields (name, description, subscribers, video count, views, creation date), which sharpens the purpose beyond the title 'bitchute: Channel profile'. It does not explicitly contrast with the sibling bitchute_channelVideos, but the field list makes the profile-vs-videos distinction clear enough.

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 when-to-use or when-not-to-use guidance, and no sibling alternative is named. An agent must infer from the tool name that this is for metadata rather than a channel's video listings, which bitchute_channelVideos covers. The 'Costs 1 credit' line is a cost note, not usage 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?

With readOnly/openWorld annotations already covering the safety profile, the description adds real operational context: page size (50), ordering (newest first), cursor-based pagination, explicit absence of likes/comments, and a 1-credit cost. That cost and pagination detail is exactly the kind of thing annotations cannot express.

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, zero filler, with the core scope front-loaded and secondary facts (pagination, cost, missing fields) following in descending importance.

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 characterizes the return set (public videos, newest first, 50/page, view counts, no likes or comments) so an agent knows what it gets. The one gap is `cache_max_age`, which is unexplained anywhere and could matter for repeated calls.

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 67% and the schema already documents both `channel` (with id/name/URL forms) and `cursor` in detail. The description's 'Pass the cursor from the previous response to page' restates the schema rather than extending it, and `cache_max_age` is left undocumented in both places.

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 ('A BitChute channel's public videos') plus concrete scope details: newest first, 50 per page, with view counts. It partially distinguishes itself from the sibling bitchute_video by noting likes are absent, though it never contrasts with bitchute_channel or bitchute_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?

It does route the agent elsewhere for engagement data ('Likes and comment counts are not in the list; bitchute.video has likes'), which is a genuine alternative pointer. However, there is no guidance on when to use this versus bitchute_channel (channel metadata) or bitchute_search, and no exclusions or prerequisites 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 substantive context beyond the annotations: page size (50 per page), fields returned (view counts, uploading channel), and cost (1 credit). That cost and result-shape info is genuinely useful and cannot be inferred from readOnlyHint/openWorldHint. It doesn't cover rate limits or error 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?

Three short sentences, front-loaded with purpose then scope then result shape and cost. No filler or repetition; every clause 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?

Covers what an agent needs to interpret results (page size, view counts, channel) without an output schema, which is helpful. However, for a 4-param tool with half the parameters undescribed, the definition leaves real gaps around sorting behavior and caching.

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 only 50% schema coverage, the description should compensate but adds no parameter info at all. 'sort' (enum new/old/views) and 'cache_max_age' are undocumented in both schema and description, leaving two of four parameters without any semantic guidance.

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 videos') and pins the platform ('Public BitChute video search'), distinguishing it from siblings like bitchute_video and bitchute_channelVideos. Slightly redundant between 'Search videos' and 'video search', but the scope is clear.

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?

No explicit when-to-use or when-not guidance, and no reference to alternatives such as bitchute_channelVideos when browsing a known channel, or bitchute_video when fetching a known video. Usage is only implied by the word 'search' and 'Public'.

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, and the description adds genuinely non-obvious behavior: dislikes are only available in `raw`, `commentCount` is always null, and the call costs 1 credit. The cost and null-field disclosures are exactly the kind of context an agent cannot get from the schema, though the privacy/'public only' failure mode is left unstated.

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 the identity of the resource, then field list, then quirks and cost. Every clause carries a distinct fact (raw dislikes, null commentCount, credit cost) 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 usefully enumerates the returned fields and flags the two anomalies an agent would otherwise misread. Remaining gap is minor: nothing about error/not-found behavior or what `raw` contains structurally.

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 50%: `url` is documented in the schema (URL or bare video id) but `cache_max_age` is undocumented in both schema and description. The description adds no parameter-level meaning at all, so it does not compensate for the coverage gap.

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 single public BitChute video) and enumerates the returned fields, so an agent knows this is the single-video lookup rather than a search or channel listing. It never names the sibling it contrasts with (bitchute_search, bitchute_channelVideos), so differentiation is inferred from the field list rather than stated.

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: 'A public BitChute video' plus a required url/id parameter signals 'call this when you already have a video reference.' There is no explicit when-to-use, no exclusion of search/channel tools, and no note about behavior when the video is private or removed.

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 safety profile is covered. The description adds genuinely useful context — the resource is public (no auth implied) and 'Costs 1 credit' discloses a metering constraint — but it does not describe caching behavior, error cases, or pagination.

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 that front-load purpose and follow with payload and cost. The bare 'Post.' opener is slightly redundant with the title but the remaining text 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?

For a simple 2-param read tool this covers purpose, returned content, and cost. With no output schema, the return description is helpful, but the undocumented cache_max_age parameter leaves a gap an agent would need 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 only 50%: 'url' is documented in the schema but 'cache_max_age' is undocumented in both schema and description. The description adds no parameter meaning, so it fails to compensate for the uncovered optional parameter.

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 payload: 'A single public Bluesky post with like, reply, repost and quote counts, plus any attached images or video.' The word 'single' distinguishes it in scope from list-oriented siblings like bluesky_userPosts, 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?

There is no when-to-use/when-not guidance and no named alternative. The 'single post' phrasing implies this is for one post rather than a feed, but the agent must infer that bluesky_userPosts or bluesky_profile are the alternatives for listing.

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 safety is covered; the description adds a genuinely useful operational fact not present in structured data — the 1-credit cost. It omits what happens on an invalid/suspended handle and does not explain that results may be cached.

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 with the returned-data inventory front-loaded and the cost appended. The only waste is the redundant 'Profile.' opener.

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, and the description compensates by listing the returned fields; cost is disclosed and the identifier formats come from the schema. The remaining gap is caching/staleness behavior tied to cache_max_age, which an agent would want before spending a credit.

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 handle formats are documented entirely in the schema, so the description contributes nothing there. More importantly, cache_max_age has no schema description and the description never mentions caching at all, leaving a parameter completely unexplained across both sources.

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 second sentence names the resource (public profile for a Bluesky account) and enumerates the returned fields, which clearly separates it from bluesky_post and bluesky_userPosts. The leading word 'Profile.' merely restates the title and adds nothing, but the substance is specific and accurate.

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 field list signals 'use this when you need follower counts, bio, avatar, verification', which implicitly routes away from the post-oriented siblings. There is no explicit when-to-use, when-not-to-use, or named alternative.

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 safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the default exclusion of reposts with a rationale, and a stated cost of 1 credit. It stops short of describing result shape or pagination 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?

Four short sentences, front-loaded with the core purpose and no filler. The opening 'User posts.' duplicates the title and could be dropped, but the remaining content is dense and 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?

With no output schema, the description carries the burden of describing what comes back, and it does not — no indication of post fields, media handling, or how pagination terminates. Annotations and the schema cover safety and half the parameters, so this is adequate but with a clear gap for a listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60% — handle, cursor and include_reposts are documented in the schema. The description usefully explains the *why* behind include_reposts defaulting to false, but says nothing about count, cache_max_age, or the format of the cursor value, leaving part of the coverage gap unfilled.

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: 'Recent public posts from a Bluesky account, newest first.' An agent can distinguish this listing tool from the single-post sibling bluesky_post, though no sibling is named explicitly. The leading fragment 'User posts.' merely restates the title and adds 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?

Usage is only implied — fetch a feed of an account's own writing. There is no explicit when-to-use versus bluesky_post, bluesky_profile, or other userPosts siblings, and no stated preconditions (e.g., private/suspended accounts).

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one piece of non-schema information — 'Free' (presumably no credit cost) — but never says the deletion is permanent or whether existing delivered items are retained.

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, front-loaded sentences with no waste. However, 'Free.' is an unqualified fragment — it does not say free of what (credits, quota) — so brevity comes at some cost to clarity.

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 destructive tool the structured fields carry most of the burden: annotations flag destructiveness, the schema explains the ID source. Still, an agent about to perform an irreversible cancellation would benefit from knowing it is permanent and what 'Free' refers to.

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 is documented as 'subscriptionId from create_watch or list_watches,' which is more useful than anything in the description. The description contributes nothing about the parameter, 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 ('Delete a watch'), which is unambiguous against the sibling create_watch and list_watches. It does not explicitly name those siblings, 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?

No indication of when to cancel versus leave a watch in place, no prerequisites, and no reference to create_watch/list_watches as the source of the identifier or as the re-creation path. The agent must infer the workflow entirely.

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 behavior beyond annotations: per-check billing at the endpoint's own credit cost, refunds on failure or empty result, and that creating a watch is free. Annotations (readOnlyHint=false, destructiveHint=false, openWorld=false→openWorld=true) cover safety but not the cost/refund model, which is the key operational trait 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?

Two sentences, zero waste, with the core action and the cost implication front-loaded. Every clause 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?

For a 4-param scheduled-watch tool with no output schema, the description plus rich schema give an agent everything needed to invoke it, and the cost model fills a real gap. Minor omission of what the webhook POST payload looks like could matter but is secondary.

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 deletion-sensitive details (endpoint restrictions, interval bounds and defaulting behavior) are already documented in the schema, so the description only needs to point at webhook_url delivery which it does. 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 chain (check on a schedule, POST to webhook_url when data changes) against a specific resource (endpoint), so it is instantly distinguishable from companion tools like list_watches and cancel_watch and from direct endpoint calls.

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 usage (polls on a schedule, notifies via webhook) but offers no explicit when-to-use vs. a direct one-off endpoint call, nor any exclusion of the non-watchable search/trending endpoints at the description level (that constraint lives in the endpoint schema).

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 read-only/open-world, but the description adds genuinely non-structured context: the data is public (no auth implied) and the call costs 1 credit, which matters for budget-aware agents. It also discloses what the payload contains, useful since no output schema exists.

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: what it is, what you get, what it costs. Front-loaded with the identity and 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?

With no output schema, the field enumeration carries the return-value burden well, and credit cost is disclosed. Missing only edge-case behavior (invalid handle, not-found response) for full completeness on a single-object lookup.

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 says nothing about the handle or cache_max_age parameters, but the schema fully documents the required handle with three accepted formats. At 50% schema coverage the optional cache_max_age is undocumented everywhere, which is the main residual gap.

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 resource precisely (a Dailymotion channel's public profile) and enumerates the returned fields, which cleanly separates it from dailymotion_channelVideos or dailymotion_video. It never names those siblings explicitly, so differentiation is inferred from the field list rather than stated.

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 the resource: fetch a channel's profile when you need channel-level stats. There is no explicit when-to-use, when-not, or pointer to the sibling tools for videos or search, which an agent in this 200-tool catalog would benefit from.

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 the read-only/open-world profile, yet the description adds real behavioral detail: newest-first ordering, 50 per page, pagination back to the first upload, and a 1-credit cost. This is meaningful context beyond the annotations, though it says nothing about truncation or error 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?

Four short sentences, each carrying distinct information — scope, ordering, page size, pagination instruction, and cost — with no filler and the key scope statement front-loaded.

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 essentials (list of uploads, ordering, page size, cursor to continue) and the credit cost. The only gap is the undocumented cache_max_age parameter, which is minor for a listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%; the cursor explanation in the description largely restates the schema's own cursor description, and handle is only explained in the schema. The undocumented cache_max_age parameter gets no help from the description. 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?

The description states a specific verb and resource — a Dailymotion channel's public uploads — which is clearly distinct from dailymotion_video or dailymotion_search. It doesn't explicitly name sibling tools, but the scope ('channel's uploads') makes the resource 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?

It tells the agent how to page ('pass the cursor from the previous response'), which implies usage for exhaustive listing, but it never says when to pick this over dailymotion_channel or dailymotion_search, nor any prerequisites about the handle.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-derivable behavior: 50 results per page, a hard 1,000-result ceiling that terminates paging, and a 1-credit cost. The credit cost and hard cap are exactly the kind of operational facts 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?

Four short sentences, each carrying distinct information: what it does, page size, the hard result ceiling, and cost. The action is front-loaded and there is no filler or restatement of the name.

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 covers the pagination lifecycle (page size, termination point) and the credit cost, which is what an agent needs to plan iteration. It does not hint at the shape of returned records at all, but for a search tool with a fully enumerated query param, that is a minor omission.

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 75%, near the threshold where the schema does the heavy lifting, and 'cursor' is already explained as 'pagination.cursor from the previous response'. The description never clarifies how the stated 50-per-page interacts with cursor paging, and 'cache_max_age' has no description anywhere, so the description does not compensate for the gap. Baseline 3 fits.

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 ('Search videos') and scopes it to 'Public Dailymotion video search', which separates it from the many other *_search siblings in the toolset. It stops short of naming the within-platform alternatives (dailymotion_channel, dailymotion_video), but the platform+action pairing 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?

Usage is only implied: an agent infers you call this to find Dailymotion videos by keyword. There is no explicit when-to-use/when-not, and no guidance on when to pick this over dailymotion_channelVideos or a different platform's search. The pagination ceiling is informative but is 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 cover read-only and open-world safety, and the description adds real behavior on top: language fallback when the requested track is absent, the fact that most tracks are auto-generated, and a 1-credit cost. It does not say what happens when a video has no captions at all, which is the notable remaining gap.

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 short sentences, front-loaded with what is returned, then fallback semantics, then provenance and cost. The opening 'Video transcript.' fragment is mildly redundant with the second sentence, but nothing else 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 usefully characterizes the return value (text block plus timed cues), the language resolution rule, and the credit cost. The only material omission is the undocumented cache_max_age parameter and the no-captions-available case.

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 67%, so the baseline is 3. The description does add genuine meaning for the language parameter by explaining the fallback to the first track, but cache_max_age is undocumented in both schema and description and goes unaddressed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource (a Dailymotion video's captions) and states the return shape (one text block plus timed cues), which is more than the title restated. It distinguishes itself implicitly from dailymotion_video by focusing on captions, though it never names that sibling 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 ('video transcript' for a Dailymotion URL) and the credit cost gives a helpful signal about when it is worth calling, but there is no explicit statement of when to use this over dailymotion_video or dailymotion_search, and no exclusion or prerequisite conditions.

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, but the description adds non-obvious value: no public comments so commentCount is null, and a 1-credit cost. That's real behavior an agent couldn't derive from annotations. Return fields aren't covered, but with an undocumented openWorld read that gap is modest.

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: purpose first, field list second, then the two caveats (null comments, credit cost). No filler, and the most surprising fact (null commentCount) is called out.

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 lists return fields and explains why commentCount is null, plus the cost. The only meaningful gap is the unaddressed cache_max_age parameter, which leaves one behavior unexplained.

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 50%: `url` is well documented with accepted id and URL formats, but `cache_max_age` is undocumented in both schema and description, and the description adds nothing about it. Baseline 3 is appropriate given the schema already carries the strong url guidance.

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 (fetch details) and resource (a Dailymotion video) and enumerates the fields returned, so it clearly differs from dailymotion_transcript and dailymotion_channel. However, it doesn't explicitly contrast with siblings like dailymotion_search, which also surfaces video data.

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 (look up one video's metadata by id/URL), but there's no explicit statement of when to choose this over dailymotion_search or dailymotion_transcript, nor any exclusions or prerequisites. The reader must infer the 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds meaningful context beyond that: the returned field set, that tracks come back with the album, paging behavior, and a 1-credit cost. The cost note and pagination hint are genuinely additive.

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 short sentences, front-loaded with the core purpose and return fields, followed by pagination and cost. No filler; each 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 does the work of listing returned fields and discloses paging and cost, which is enough to call it correctly. The only gap is the unexplained cache_max_age parameter, a minor omission for a 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 covers id and cursor (67%), and the description reinforces cursor's role ('page the tracks') but adds little syntax beyond the schema's own 'pagination.cursor from previous response'. cache_max_age is undocumented in both schema and description, so 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 the resource (a Deezer album) and enumerates the concrete fields returned (title, artist, label, UPC, release date, fans, tracks), which lets an agent distinguish it from deezer_artist, deezer_track, or deezer_search. It doesn't explicitly name a sibling to differ from, so not 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?

The only usage guidance is 'Pass `cursor` to page the tracks of a long album,' which implies repeated calls for large albums. There is no statement of when to prefer this over deezer_artistAlbums or deezer_search, leaving 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?

Adds real value beyond the annotations by disclosing a cost of 1 credit and by enumerating the returned fields, which matters since there is no output schema. It doesn't cover failure modes (invalid id, rate limits), but for a read-only open-world profile lookup it is well above baseline.

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 with the resource identity front-loaded and zero filler. The field enumeration and cost note both earn their place; only the fragment style slightly reduces 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?

Annotations cover the read-only/open-world safety profile, and the field list substitutes partly for the missing output schema. However, the undocumented cache_max_age parameter and the absence of any guidance on sourcing the required id leave a noticeable 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?

At 50% schema coverage, the description must compensate for undocumented parameters, and it does not. There is no mention of the required 'id' format or of the 'cache_max_age' parameter, which is entirely undocumented in both the schema and the description.

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 (Deezer artist profile) and enumerates the fields returned (name, fans, album count, picture, link), which distinguishes it from deezer_artistAlbums and deezer_artistTopTracks that cover adjacent data. It doesn't explicitly name those siblings, but the field list makes the boundary inferable.

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?

No guidance on when to use this versus the other deezer_* sibling tools (artistAlbums, artistTopTracks, search), and no mention of how to obtain the required id. Usage is only implied by the tool name and field list.

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 the safety profile (readOnlyHint=true, openWorldHint=true). The description adds two genuinely useful facts beyond them: `likeCount` is the release's fan count and the call costs 1 credit. It does not explain pagination behavior despite a cursor param, so it earns partial credit only.

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, front-loaded sentences with minimal waste and the core purpose up first. Slightly terse in that `likeCount` is the only return field called out, but nothing is 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 read-only list tool with no output schema, the definition covers purpose, one return field, and cost, but omits pagination semantics and the meaning of `limit`/`cache_max_age`. It is adequate but not complete for a 4-param paged endpoint.

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 50%: `id` and `cursor` are documented in the schema, but `limit` (default 25) and `cache_max_age` are described nowhere. The description adds no parameter meaning to compensate for the gap, leaving two params opaque.

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: an artist's albums, singles and EPs on Deezer, tied to a Deezer artist id. It is clearly distinct from deezer_artist (artist info) and deezer_artistTopTracks (top tracks) by naming the collection it returns, though it never explicitly says 'list all releases for an artist' or names those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use statement and no alternatives are named. The scope detail ('albums, singles and EPs') implies coverage, but an agent gets no guidance on choosing this vs deezer_artist, deezer_artistTopTracks, or deezer_album.

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 this is a read-only, open-world lookup, so the bar is lower. The description usefully adds result ordering ('most popular first') and a credit cost/rate-limit style signal, but says nothing about pagination behavior even though a cursor parameter exists.

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 purpose, followed by ordering semantics and cost. Every sentence carries information an agent cannot get from the structured fields alone.

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 read-only lookup with no output schema, the description covers purpose, ordering, and cost but omits pagination and limit semantics on a 4-parameter tool with half of the parameters undocumented. It is adequate to start calling the tool, but not sufficient to invoke it correctly with limit/cursor on repeat calls.

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 only 50% schema description coverage, the description must compensate for the gap. It adds nothing about id format beyond the schema, nothing about what limit bounds/means (default 25, max?), nothing about cursor semantics, and nothing about cache_max_age — all 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?

States a specific verb+resource ('Artist top tracks') and clarifies it means an artist's most popular tracks on Deezer, so an agent can tell it apart from deezer_artist or deezer_artistAlbums. It stops short of explicitly naming those siblings or stating what it excludes.

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 resource name: call it when you need an artist's ranked popular tracks and you already have an artist id. The 'Costs 1 credit' note gives cost context, but there is no explicit when-to-use/when-not guidance or mention of alternatives like deezer_track or deezer_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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety/scope profile is covered. The description usefully adds the credit cost, which is not in the schema or annotations, but says nothing about result freshness, pagination, or how cache_max_age affects 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 the resource and followed by the credit cost. The leading 'Charts.' echoes the title and could be dropped, but the rest is efficient and free of 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 and three undocumented parameters, the description should do more, particularly for cache_max_age and for what a chart entry contains (rank, position, streaming data?). It is adequate to identify the tool but leaves gaps an agent needs when constructing a call.

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 carry parameter meaning, and it does not: it repeats the enum values for 'type' (which the enum already conveys) and says nothing about 'limit' or the opaque 'cache_max_age' string parameter. An agent has no way to know what cache_max_age accepts or how limit interacts with charts.

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 the resource (Deezer charts) and enumerates the entity kinds covered (tracks, albums, artists, playlists, podcasts), which is a concrete verb+resource statement. It does not explicitly distinguish itself from siblings like deezer_search or deezer_artistTopTracks, so the agent must infer that this returns global charts rather than per-artist or keyword-based 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?

Usage is implied by the word 'global top' charts, but there is no explicit when-to-use guidance and no mention of when to prefer deezer_search or deezer_artistTopTracks instead. The 'Costs 1 credit' note gives a cost signal but is not usage 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds two genuinely useful behavioral facts not in structured data: only public playlists are readable, and each call 'Costs 1 credit' (a rate/cost constraint). It does not mention pagination termination or what a truncated track list looks like, so it adds value but not rich 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?

Three short sentences, front-loaded with the resource and the returned fields, with the paging hint and cost note trailing. The opening fragment 'Playlist contents.' duplicates the title slightly, but nothing is 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?

With no output schema, the description correctly fills that gap by enumerating the returned fields, and it explains pagination via `cursor`. What remains thin is routing guidance versus sibling playlist tools and any mention of `cache_max_age`, but for a one-required-param read tool it is close to 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 67%; `id` and `cursor` are documented in the schema and the description reinforces cursor usage by tying it to paging long track lists. The third parameter, `cache_max_age`, is undocumented in both the schema and the description, which is a small but real gap. Baseline 3 fits given the schema does most of the work.

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 concrete resource and enumerates exactly what is returned (title, owner, description, cover, track count, fans, tracks), so an agent knows this is a playlist-detail fetch rather than a search. It stops short of naming how it differs from sibling deezer_userPlaylists or deezer_search, which is the only thing separating it from 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?

The only usage signal is 'Pass `cursor` to page the tracks of a long playlist,' which is a pagination hint rather than a when-to-use rule. Nothing tells the agent when to choose this over deezer_userPlaylists (listing a user's playlists) or deezer_search (finding a playlist by name), so selection must be inferred.

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 and open-world behavior, but the description adds real context beyond them: the credit cost per call, and the fact that postCount is always null because Deezer exposes no episode count — a concrete trap an agent would otherwise misread as missing data. It does not cover error cases (invalid id, out-of-credits) or auth needs.

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 short sentences with the payload summary front-loaded and the null caveat plus cost at the end. Sentence one duplicates the title, which is minor waste, but nothing else is 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?

With no output schema, the field enumeration plus the postCount explanation carries the return-shape burden adequately, and the credit cost is stated. What remains thin is the missing link to deezer_podcastEpisodes and any explanation of cache_max_age, which leaves real gaps for a two-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%: `id` is documented in the schema as a numeric Deezer podcast id, but `cache_max_age` has no description anywhere. The description mentions no parameters at all, so it does nothing to compensate for the undocumented cache control.

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?

"Podcast details" names the resource and adds the concrete payload fields (title, description, artwork, fans), so an agent knows what it gets back. It never distinguishes itself from the adjacent deezer_podcastEpisodes or spotify_podcast, so the sibling boundary is left implicit.

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 statement of when to use this versus deezer_podcastEpisodes (episode listing) or deezer_search (discovery), and no guidance on where a valid podcast id comes from. Usage is only inferable from the tool name.

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 and open-world behavior, while the description adds two meaningful traits beyond them: episodes are returned newest first and the call costs 1 credit. It still omits pagination behavior beyond the cursor field and does not describe rate or limit characteristics.

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 the resource and ordering. The opening 'Podcast episodes' slightly duplicates the title, but the description is otherwise tight and efficient.

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 endpoint, the description gives the core context: which podcast, ordering, and credit cost. However, with no output schema and missing documentation for limit and cache_max_age, an agent lacks enough detail about page size and caching behavior.

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 adds almost no parameter meaning beyond what is already in the schema: the required id is described there as a numeric Deezer podcast id, and cursor is schema-documented. The limit and cache_max_age parameters remain unexplained in both schema and description, and the description does not compensate for the 50% coverage gap.

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 the specific resource ('A Deezer podcast's episodes') and result ordering ('newest first'), so an agent can tell this lists episodes for a given podcast id. It does not explicitly differentiate from the nearby deezer_podcast metadata tool, which keeps it below 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?

The description says what the tool returns but gives no guidance on when to use it instead of alternatives such as deezer_podcast or deezer_search. 'Costs 1 credit' is useful context, but it is not 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds one genuinely non-structured fact — each call costs 1 credit — which is valuable for a metered agent. It stops there: no mention of pagination (despite a cursor param) or result ordering, so coverage is partial rather than rich.

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 that front-load the action and add the credit cost. The only waste is the bare leading 'Search.' which merely restates the title before the substantive 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 and only 40% parameter coverage, the description needs to carry more: pagination via cursor, semantics of limit, what cache_max_age controls, and defaults are all left unexplained. For a 5-parameter search tool this leaves an agent guessing on how to page and how many results it will get.

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 40%, so the description should compensate, but it doesn't. It restates the entity types already captured by the enum and says nothing about 'limit' (result count, max?), 'cache_max_age', or the default type=track behavior, leaving over half the parameters undocumented.

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 Deezer's catalogue, with the five entity types it can return. It is distinguishable from Deezer's by-ID siblings (deezer_track, deezer_album) as the lookup entry point, but it never differentiates itself from other music search tools such as spotify_search or appleMusic_search beyond the platform named in the tool name.

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 search-then-detail workflow by naming the entity types, and the credit cost hints at a metered operation. But it never states when to use this versus deezer_album/deezer_artist (i.e. search first, then fetch details by ID), nor any exclusions or ranking behavior.

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 safety profile is covered. The description adds genuinely non-structured information: the operation 'Costs 1 credit', which matters for an agent deciding whether to spend a call. It does not explain the caching behavior behind cache_max_age.

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, purpose first, returned fields second, cost last. No filler; every clause carries information an agent can use.

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 tool with no output schema, listing the returned fields is a useful substitute for a response spec. The gap is the undocumented cache_max_age parameter, whose effect on behavior and cost is left entirely unexplained.

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 50%: 'id' is documented as a numeric Deezer track id, but 'cache_max_age' has no schema description and the description says nothing about it either. The description adds no parameter meaning beyond what the schema already carries.

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 (track details) and enumerates exactly what a Deezer track record contains (title, artist, artwork, duration, release date, ISRC, tempo). It is clearly a single-object lookup, distinct from deezer_search or deezer_artistTopTracks, 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: it takes a numeric id, so an agent infers this is the fetch-by-id step after a deezer_search. However, there is no explicit 'use this when...' or 'do not use for...' statement, and no mention of where to obtain the required id.

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. The description usefully adds that only public playlists are returned and that the call costs 1 credit, but it does not describe pagination behavior or return shape.

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 resource scope. The first sentence, 'User playlists', largely restates the tool name/title, so it is concise but not maximally efficient.

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 endpoint, the description identifies what is fetched and notes the credit cost and public-only scope. However, with no output schema and incomplete parameter coverage, it omits useful context about pagination and the undocumented limit/cache_max_age parameters.

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 50%: id and cursor are documented in the schema, while limit and cache_max_age are not. The description does not compensate by explaining any parameter, only implying that id identifies the Deezer user.

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 the specific resource and scope: a Deezer user's public playlists. It is clear enough to distinguish from retrieving a single playlist, but it does not explicitly name a sibling or use a verb like 'list' to make the action fully 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?

There is no guidance on when to use this tool versus alternatives such as deezer_playlist or deezer_search. The context is implied only by 'A Deezer user's public playlists'; no exclusions or prerequisites are given.

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 safety is covered; the description's real contribution is the cost disclosure ('Costs 1 credit') and the note that reviews are only an 'inline sample'. It says nothing about failure modes for invalid IDs, marketplace/redirect behavior, or latency/rate limits, which would matter for a credit-metered 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?

Three short sentences, front-loaded with what the tool returns, then cost, then input rule. 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 does the right thing by listing returned fields and flagging that reviews are partial. But for a 5-parameter, credit-costing tool it leaves the identifier-selection fallback, the three secondary parameters, and error behavior undocumented.

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 60%. The description's 'either product_id or url' is genuine added value because the schema marks neither as required and never states the alternatives are interchangeable. However, tld, country_code and cache_max_age receive no mention anywhere in the description, leaving a real gap.

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 ('Public details for an eBay listing') and enumerates the payload (title, price, condition, seller, sample reviews), so an agent knows exactly what it retrieves. It does not name ebay_search or explain why a single-listing lookup differs from a search result, so sibling differentiation is left implicit.

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?

'Pass either `product_id` or `url`' gives the minimum routing rule for inputs, which is more than nothing. But there is no guidance on when to use this instead of ebay_search, no preconditions, and no statement about what happens when neither identifier is supplied (schema marks zero required params).

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 safety profile is covered. The description adds genuinely useful non-schema context by disclosing the cost ('Costs 1 credit'), but says nothing about pagination limits, result caps, or rate limiting 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?

Three short sentences, front-loaded with the core action, and no wasted words. The cost disclosure is placed last where it belongs.

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 11 parameters, no output schema, and under half of the schema documented, the description should explain what the result set looks like and how the undocumented parameters behave. Neither 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 only 45% across 11 parameters, and several key params (page, seller_id, country_code, cache_max_age, items_per_page) have no description anywhere. The description only generically alludes to 'filters and sort orders' and does not compensate for the documentation gap.

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 eBay listings) and narrows scope to public search results using eBay's own filters and sort orders. It does not explicitly distinguish itself from the sibling ebay_product tool, but the intent 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?

Usage is implied by the name and the phrase 'for a query', but there is no statement of when to prefer this over ebay_product or any other marketplace search, and no prerequisites or exclusions are given.

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 the non-obvious fallback resolution path, the country dependency of that scan, and the 1-credit cost — real behavioral context. It stops short of saying what happens when neither lookup succeeds (empty result vs. error).

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, none wasted: identity, the fallback rule, then cost. The most decision-relevant constraint (archive id may not be directly addressable) is front-loaded after the purpose.

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 return-value burden, and 'Ad details' gives little sense of the payload shape. Otherwise it covers the identifier semantics, the fallback, and cost adequately for a 4-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 coverage is 75%, so baseline is 3; the description adds genuine meaning for page_id by explaining it enables the archive-scan fallback rather than just being 'the advertiser's page id'. country and cache_max_age are left entirely to the schema, and the URL form of id is only in 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 ('Ad details') plus scope ('one ad from the Meta Ad Library by its archive id'), which cleanly distinguishes it from the plural facebook_adLibrarySearch and facebook_pageAds siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the key conditional: when Meta has no addressable archive node, pass page_id to trigger an archive scan. It gives clear context for the fallback and the cost, though it never states when to prefer a sibling search tool or when the call will fail outright.

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 safety (readOnlyHint, openWorldHint), and the description adds real context beyond them: the 1-credit cost, that results are derived from an underlying ad search rather than a native advertiser index, and that ranking is by number of ads run. It does not disclose caching behavior despite exposing cache_max_age, 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?

Three tight sentences: purpose first, then result shape and the downstream page_id, then derivation/ranking, then cost. Every sentence adds a distinct fact 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 read-only search tool, the description supplies purpose, output shape, the key field an agent needs elsewhere, ranking semantics, and cost — the practical gaps left are minor enum defaults the schema already encodes.

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 40%, so the description must carry weight; it clarifies that the query matches both advertiser names and ad copy and that the sample size drives advertiser breadth, but status, country, and cache_max_age get no explanation anywhere. Partial compensation only.

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 advertisers running ads') and immediately qualifies the output as 'distinct advertisers whose ads match a search term' ranked by ad volume. This is clearly distinguishable from siblings like facebook_adLibrarySearch (returns ads) and facebook_pageAds (takes a page_id), which the description explicitly links to.

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 strongly: use this when you need advertisers matching a term, and it names the downstream consumer (/v1/facebook/ad-library/page-ads) that needs the returned page_id, which routes the agent correctly. It stops short of explicitly saying when to prefer facebook_adLibrarySearch instead, so no 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 and openWorldHint, yet the description adds real value: 2-credit cost, results returned in the Library's own ordering rather than relevance, and the caveat that spend/impression ranges only populate for political/issue ads under certain deployment configurations. That deployment caveat is a genuinely non-obvious behavioral trait.

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 compact sentences, front-loaded with the capability before the caveats. No padding, though the 'where the deployment reads the Graph Ad Library API' clause is dense and slows scanning.

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 13-parameter search tool with no output schema, the description covers result ordering, the hasMore/cursor pagination contract, field-availability gaps, and cost — everything an agent needs before invoking. Remaining parameter details are adequately handled by the 85% schema coverage.

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 85%, so the schema documents nearly every parameter with enums and defaults. The description's only parameter-adjacent content (political ads unlocking spend data) restates the ad_type schema text, and no light is shed on the undocumented cache_max_age.

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 ('Search the Meta Ad Library') and enumerates the surfaces covered (Facebook, Instagram, Messenger, Threads ads). It does not explicitly differentiate from near siblings like facebook_ad, facebook_adLibraryAdvertisers, or facebook_pageAds, so it stops 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?

No guidance on when to pick this over facebook_adLibraryAdvertisers, facebook_pageAds, or tiktok_adLibrarySearch — the agent must infer from names alone. The only operational note is the credit cost, which addresses economics rather than 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?

Goes well beyond the readOnly/openWorld annotations by disclosing the data source (`source: "captions"`), the exact failure mode and status code for uncaptioned videos, and the billing rule (1 credit, only charged when a transcript is actually returned). Missing only details like whether cached results still cost a credit or how long transcripts can be.

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 scope and ID/URL constraint are front-loaded and no sentence is filler; the credit rule and the 501 caveat each earn their place. The opening fragment 'Ad video transcript.' duplicates the title and the ID/URL exclusivity is stated once at the end rather than with the other parameter details, but overall it is tight.

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 4-parameter tool with no output schema, the description covers the selection constraint, cost and failure path, which is the important part. But with `cache_max_age` undocumented anywhere and no hint about the shape of a returned transcript (plain text vs. timestamped segments), an agent still has to guess at both caching behavior and 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?

Schema coverage is 75%, so the baseline is a 3, and the description does add one genuinely new constraint not expressible in the schema: 'Pass exactly one of `id` or `url`' (mutual exclusivity). However, it adds nothing about `language` or the entirely undocumented `cache_max_age` parameter, so the coverage gap is only partly compensated.

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: 'Retrieves a transcript for a single Facebook Ad Library video ad by ID or URL', and narrows the mechanism to Facebook's published caption track. This clearly separates it from facebook_ad (ad metadata) and from post/reel transcript siblings on other platforms, though it never names those alternatives 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?

Gives a concrete when-not condition: ad videos without captions return `not_configured` (501) and are not charged, so the agent knows this tool silently fails for that class of input. It does not route the agent to any sibling (e.g. facebook_ad to first confirm the ad is a video) or state prerequisites, so it stops short of full when/when-not/alternatives 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?

Goes well beyond readOnlyHint/openWorldHint: discloses that only the first server-rendered page is returned, that pagination.hasMore can be true with no cursor available to fetch more, that listing entries lack host and description, that ordering is Facebook's own ranking, and that each call costs 1 credit. These are exactly the operational constraints 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?

Five tight sentences, front-loaded with what the tool returns, followed by filter semantics, page limits, and cost. No filler or repetition 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?

For a read-only, no-output-schema listing endpoint, the description covers the meaningful unknowns: what the feed is, what fields are absent, pagination limits, ordering nondeterminism, and cost. An agent could invoke it correctly without further exploration.

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 67%, and the description adds real meaning for `time` beyond the schema's 'Defaults to all upcoming' by explaining the resulting ordering and scope. It also restates the accepted `url` forms (Explore URL or bare slug/id pair). `cache_max_age` remains undocumented in both schema and description, keeping it below a 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 with scope: 'Public events Facebook is suggesting for a city, from its Events Explore feed,' backed by a concrete example URL. The agent can tell this apart from facebook_event (detail view) because the description explicitly says host/description only exist on /v1/facebook/event.

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 when to use the `time` filter versus omitting it ('without it Facebook returns whatever it has queued as upcoming, in whatever order it ranks them') and routes the agent to the event-detail endpoint for host/description. It does not mention facebook_eventsSearch or facebook_profileEvents as alternatives for keyword or per-profile event lookups, so the sibling routing is incomplete.

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 genuinely non-structured context: results are ten per page, pagination is cursor-based, the post must be public, and the call costs 1 credit. The opening 'Replies to a comment' is momentarily ambiguous (posting vs. retrieving) but is resolved by the per-page detail.

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 short sentences, front-loaded with the action, followed by prerequisites, pagination, and cost. Minor redundancy in restating cursor as pagination.cursor, but nothing wasteful.

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 return-shape burden and does so adequately by stating page size and cursor reuse. The only gap is cache_max_age, which is unexplained in both schema and description, and no explicit statement of what a reply record contains.

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%, so most parameters are already documented. The description adds provenance for comment_id (any `id` from /v1/facebook/post-comments) which is real value beyond 'Numeric comment id', but it says nothing about cache_max_age, the one parameter undocumented in 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 ('Replies to a comment ... under one comment on a public Facebook post'), which is enough for an agent to identify the operation. It implicitly separates itself from facebook_postComments by pointing at that endpoint as the id source, though it never names the sibling outright.

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 concrete prerequisite workflow: obtain the comment id from /v1/facebook/post-comments, then call this tool, then follow pagination.cursor. It does not explicitly state exclusions (e.g., private posts) beyond 'public Facebook post', but the usage context is clear.

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 and openWorld; the description adds meaningful context beyond them: 'public' events only and an explicit '1 credit' cost, plus the breadth of returned data. It omits error behavior and the cache_max_age effect.

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 field enumeration, and trailing cost note — no wasted text. Efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description enumerates the returned fields, states the credit cost, and notes public-only scope. It leaves the cache_max_age behavior unexplained but is otherwise adequate for a simple 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?

With only 50% schema coverage, the description should compensate but adds no meaning for url or cache_max_age. It only says the resource is a 'public Facebook event'; cache_max_age is undocumented in both schema and description.

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 states it returns full details for a single public Facebook event and enumerates the returned fields (description, times, venue, host, ticket price). However, it never names the sibling distinction from facebook_eventsSearch or facebook_cityEvents, which an agent must infer.

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?

'Full details for one public Facebook event' implies retrieval-by-identifier usage after discovery, but there is no explicit when-to-use vs. search/cityEvents guidance and no exclusions. The agent must infer the workflow.

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 that this is a safe read-only, open-world operation. The description adds meaningful behavioral context beyond annotations: results are ranked and location-biased, the same query may return different sets across calls, and each call costs 1 credit. 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 short and front-loaded, leading with the core action and following with important behavioral caveats. There is minor redundancy between 'Search public events' and 'Public Facebook events matching a search term,' but no major waste.

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 discovery search tool with no output schema, the description explains non-determinism and credit cost, which are important. However, it does not describe the result shape, pagination behavior, or what fields an agent should expect from returned events.

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 schema documents the required query parameter with an example, but cache_max_age is undocumented, leaving schema coverage at 50%. The description adds no parameter guidance at all, so it does not compensate for the undocumented cache_max_age parameter.

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: search public Facebook events matching a search term. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings such as facebook_event, facebook_cityEvents, or facebook_profileEvents.

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 gives useful usage context by saying results are discovery-oriented rather than an enumerable list, implying it should not be used for exhaustive retrieval. However, it does not explicitly say when to use this tool versus related event tools or what alternatives exist.

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; the description adds valuable context: credit cost, field mappings into followerCount/category, and the fact that member counts may be rounded with raw.memberCountIsApproximate. It stops short of failure/privacy behavior and cache semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with 'Public group info' and then spends its sentences on useful output mappings and cost, not filler. It is appropriately sized for a no-output-schema 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?

For a simple read-only lookup with annotations and an input schema, the description covers the key returned fields, the rounding quirk, and cost. It is only incomplete on cache behavior and non-public/error cases.

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 schema documents url but not cache_max_age, and the description contains no input-parameter guidance at all. With 50% schema coverage, the opaque cache_max_age parameter is not compensated for by the description.

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 resource and enumerates the fields returned (name, member count, privacy setting, description) and restricts it to public Facebook groups. That is enough to distinguish it from facebook_groupPosts and other Facebook profile/page 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 establishes the scope (public groups) but gives no explicit when-to-use guidance, prerequisites, or named alternatives such as facebook_groupPosts for posts. Usage is only implied by the purpose.

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 data richness (reaction/comment/share counts, conditionally rendered), a rendering cap on logged-out visitors, empty results for private groups, the no-login policy, and the 1-credit cost. This is exactly the behavioral context an agent needs.

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 definition, then layers in limits and cost. Four sentences with little waste, though the page-posts comparison is slightly tangential.

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 tool with no output schema, it adequately describes returned data, rendering limits, failure modes (private groups), and cost. The only missing piece is meaning for the undocumented cache_max_age parameter.

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 url parameter already has a schema description ('Group URL, group id, or group slug'), and the prose adds nothing more. The cache_max_age parameter has no schema description and is not explained in the description, so at 50% coverage this leaves a real gap unaddressed.

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: recent posts from a public Facebook group. It distinguishes scope (public only) and references the analogous /v1/facebook/page-posts limit. It doesn't explicitly contrast with facebook_group or other siblings, but the resource 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?

It conveys key constraints (public only, private groups return empty) that effectively say when this will or won't work. However, it doesn't name alternatives such as facebook_group for group details or what to do for private content, leaving routing 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 already cover the safe-read and open-world profile, but the description adds genuinely useful context the agent could not get from them: seller identity is never returned because Facebook hides it from logged-out visitors, only public listings are accessible, and each call costs 1 credit. That is real disclosure beyond structured data, though scope/rate behavior is otherwise unspecified.

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 the identity of the tool and followed immediately by the returned fields, then the seller caveat and cost. No filler and no repetition 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?

There is no output schema, so enumerating the returned fields is necessary and done well, and the seller-identity exclusion plus credit cost round out the picture. The one hole is 'cache_max_age', undocumented anywhere, which leaves an agent guessing about a supported parameter.

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 50%: the 'url' parameter is documented in the schema, while 'cache_max_age' is undocumented in both schema and description. The description adds no parameter-level detail (accepted ID formats, cache semantics) to compensate for that gap, so it sits at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (a single public Facebook Marketplace listing) and enumerates exactly what is returned: title, description, price, location, delivery options, photos. It is distinguishable from facebook_marketplaceSearch by the singular 'one listing' framing, though it never names the sibling 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?

The phrasing 'One public Facebook Marketplace listing' implies this is a single-item detail lookup versus a search call, but there is no explicit statement of when to use this instead of facebook_marketplaceSearch or what input forms are acceptable beyond the schema. Usage is inferable, not 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 cover read-only and open-world, so the description earns credit for adding the 1-credit cost and for disclosing that results include neighbouring locations, not just the queried city. No mention of failure behavior when a place name is ambiguous or unmatched.

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 short sentences, front-loaded with the action, then the endpoint contract, then the rationale, then cost. Every sentence carries distinct 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?

With no output schema, the description usefully characterizes the return: location ids plus neighbouring locations. Cost is disclosed. The only real hole is the undocumented cache_max_age parameter, which leaves an agent guessing about a secondary option.

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 schema documents 'query' with an example, but 'cache_max_age' is undocumented in both schema and description at only 50% coverage. The description adds no parameter meaning beyond restating 'resolve a place name', so it does not compensate for the gap.

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 a Marketplace location') and goes further by naming exactly what the call produces ('Marketplace location ids /v1/facebook/marketplace/search accepts'). This makes it unmistakable versus facebook_marketplaceSearch, which consumes those ids rather than producing them.

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?

'Marketplace is city-scoped, so this is how you search a city you are not sitting in' gives a clear situational trigger and points at the consuming sibling. It stops short of an explicit sequencing instruction ('call this first, then pass ids to marketplaceSearch') and lists no exclusion conditions.

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 claim readOnly and openWorld; the description adds the non-obvious behavioral facts: results are non-deterministic absent `location`, the `location` value can come from a sibling endpoint, and each call costs 1 credit. Cost and determinism are exactly the traits structured fields don't carry, so this materially raises the bar.

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 short sentences, front-loaded with the purpose, then the caveat and cost. Nothing is repeated from the schema verbatim 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?

With 9 params and no output schema, the description compensates by describing the result shape and the location/determinism interaction. It stops short of covering `cache_max_age` or the sort/price-filter interplay, so it is strong but not fully closed.

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 89%, so baseline is 3; the description earns one more by explaining the consequence of omitting `location` and by pointing to /v1/facebook/marketplace/locations as the id source. It leaves `cache_max_age` (the one undocumented param) unexplained and doesn't clarify currency resolution for min/max price beyond the schema's "location's currency".

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 Marketplace listings") and immediately enumerates what comes back: price, condition flags, location, photos. That return-field list distinguishes it from facebook_marketplaceItem (single listing) and facebook_marketplaceLocations (id lookup) without needing to name them.

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 concrete conditional rule: without `location`, Facebook picks the city itself and "you do not control" it, so pass `location` for repeatable results. That is real guidance for a common failure mode, though it does not say when to prefer this over facebook_marketplaceItem for a known listing.

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 isn't carrying the safety burden, but it does add genuine operational context: the pagination caveat that cursor is only populated in Graph-API deployments while hasMore is the fallback signal, and an explicit 'Costs 2 credits.' Those are non-obvious behaviors an agent would otherwise discover only by trial.

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 short sentences, purpose front-loaded, then data source, then the sibling-positioning cue, then the two operational caveats (pagination and credit cost). Nothing is redundant and nothing is buried.

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 12-parameter read-only tool with no output schema, the description covers the two things the schema cannot: how pagination behaves across deployments and the credit cost. It does not flag that most filters are optional beyond page_id, but the required field is declared in the schema, so this 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 83%, so the schema already documents nearly every parameter (country requirement, political ad_type unlocking spend/impression fields, page_id accepting an Ad Library URL). The description adds only indirect cursor semantics tied to pagination and does not elaborate on limit, status, or date filters, so baseline 3 is right.

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 ads for one advertiser' / 'Ads a specific Facebook page is running or has run, from Meta's Ad Library,' and tags itself as the competitor-monitoring endpoint, which separates it from the keyword-oriented siblings like facebook_adLibrarySearch. It never names the nearest siblings (facebook_ad, facebook_adLibraryAdvertisers) explicitly, so differentiation is inferable rather than spelled out.

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 'This is the competitor-monitoring endpoint' implies a use case (watching a competitor's creative), but there is no explicit when-to-use/when-not or named alternative such as searching by keyword instead of by page. Guidance is implied, not 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 declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It adds valuable behavioral context: newest-first ordering, three posts per page, the specific fields returned (text, reaction/comment/share counts, timestamp), cursor-based pagination, and a credit cost. The only minor gap is lack of auth or error-behavior details.

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 four short sentences, front-loaded with the core purpose, then the return details, pagination hint, and cost. Every sentence earns its place with no redundancy or 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 read-only, open-world tool with no output schema, the description covers the essential return data, pagination, and cost. It doesn't explain cache_max_age or mention rate limiting beyond cost, but those are minor omissions given the overall clarity and the annotations already covering safety.

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 67% (2 of 3 parameters described). The description reinforces the cursor semantics ('Pass pagination.cursor back for the next three') and ties it to the page size, but it adds no extra meaning for the url parameter beyond its schema description and completely omits cache_max_age. This is adequate but leaves gaps.

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 (retrieves) and resource (public posts from a Facebook Page), and lists the returned fields. It implicitly distinguishes Page posts from group or profile posts via 'from a Facebook Page', but it never names a sibling tool as an alternative, 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?

The description implies when to use the tool ('Recent public posts from a Facebook Page'), but it gives no explicit when-not conditions or alternatives—such as directing group posts to facebook_groupPosts. The pagination instruction ('Pass pagination.cursor back') is usage guidance for repeat calls, not for 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?

Adds substantial traits beyond readOnlyHint/openWorldHint: reads the reels tab first, paginates ten at a time via pagination.cursor, falls back to the video grid (~20 entries with titles, views, durations) with no cursor, returns videos instead of erroring, and costs 1 credit. This is exactly the operational context annotations cannot carry.

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 core purpose, then pagination/fallback behavior, then item-keying and cost. Dense but every sentence carries information; the fallback sentence is long but 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?

With no output schema, the description usefully sketches the return shape (video-id-keyed items, titles, view counts, durations, pagination.cursor) and the fallback path. Only cache_max_age semantics are left unexplained, 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 coverage is 67%; url and cursor are already documented in the schema, and the description only restates cursor behavior. cache_max_age has no description in either place, so no compensation for the gap. 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: public videos and reels from a Facebook Page. This is clearly distinguishable from siblings like facebook_pagePosts or facebook_pageAds 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 gives context for when this applies (fetching a Page's reels/videos) and even pipeline guidance — items can be passed to /v1/facebook/post or /v1/facebook/post-transcript. It does not explicitly name when to prefer a sibling instead (e.g., pagePosts for text posts), which keeps it from 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?

Adds real context beyond the readOnly/openWorld annotations: the target must be a public post, the response carries text and engagement counts, and each call costs 1 credit. It does not explain caching behavior or what happens for private/deleted URLs.

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 returns, then the cost. No filler and nothing to trim.

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 annotations covering the safety profile and no output schema, the description supplies the essential shape of the result (text plus engagement counts) and the credit cost. The only meaningful gap is the undocumented cache_max_age parameter and its effect on freshness or pricing.

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 50%: url is documented, cache_max_age is not. The description reinforces that url is a full post/video/reel URL but adds nothing about cache_max_age, leaving half the parameters explained only by a bare schema entry. Baseline 3 given the partial coverage.

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 (one public Facebook post, video, or reel) fetched by URL and returned with text and engagement counts. It is distinguishable from facebook_pagePosts (lists) and facebook_postComments (replies), though it never names those siblings to sharpen the boundary.

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 public Facebook post... by URL' implies when it applies (single-item lookup by URL, public content only), but there is no explicit routing guidance such as using facebook_postTranscript for transcript or facebook_postComments for replies, and no stated 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?

Annotations only say readOnly/openWorld, but the description adds non-obvious behavior: non-chronological 'Most relevant' ordering, a truncated first page versus 10-comment subsequent pages, and a data-integrity caveat that likeCount is rounded in abbreviated form ('2.4K') at source. It also discloses the 1-credit cost.

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 purpose, then pagination, then counters, then caveats — no filler sentences. It is dense and longer than typical, but nearly every clause contributes 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?

No output schema, so the description carries the return contract and does so adequately (author, reaction count, reply count, ordering, rounding caveat). Only the cache_max_age parameter and exact response envelope remain undocumented.

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 67% schema coverage, the description usefully explains that cursor comes from a previous response's pagination.cursor and that the url must be a post/video/reel. The cache_max_age parameter is left unexplained in both schema and description, a minor gap.

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+resource (comments on a post) with scope qualifiers: top-level only, public posts, default 'Most relevant' ordering. It also names the sibling tools it is not (facebook_post for the total, facebook_commentReplies for replies), so an agent can discriminate without opening schemas.

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?

Explicit routing: use /v1/facebook/comment-replies for replies under a comment, and /v1/facebook/post for the full comment total. It also states the concrete pagination procedure (pass pagination.cursor back for the next ten after the ~2-comment first page).

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 important behavior: the source is Facebook's caption track, auto-generated captions may be used, uncaptioned videos return `not_configured` (501), that case is not charged, and successful calls cost 1 credit. This is unusually rich context for invocation and failure handling.

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 front-loaded with the core return type and then adds operational details. The opening 'Video transcript. Transcript for...' is slightly redundant, but overall it is compact and every other sentence provides useful 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?

For a transcript-fetching tool without an output schema, the description explains the return format, caption source, failure behavior, and billing. It is nearly complete, with the main remaining gap being semantics for the `language` and `cache_max_age` parameters.

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 67%, and the schema already documents `url` and `language`. The description reinforces that the URL must be a public Facebook video/reel URL, but it adds nothing about `language` or `cache_max_age`, so it does only partial work 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 clearly states the resource and return shape: a transcript for a public Facebook video or reel, as one text block plus timed cues. It is more specific than the title alone, but it does not explicitly differentiate itself from sibling transcript tools such as facebook_adTranscript or reddit_postTranscript.

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 usage context: works for public Facebook videos/reels that have a Facebook caption track, including auto-generated captions. It also states the key exclusion that videos without captions are not yet supported, though it does not name alternative transcript 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?

Annotations only declare readOnly and openWorld; the description goes well beyond them by disclosing credit pricing, the extra-credit cost of extra_fetch with a refund clause on unreadable fetches, and the data-quality caveat that followerCount may be rounded to ±500,000 with raw.followerCountIsApproximate as the discriminator. That is exactly the kind of behavioral 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?

Front-loaded with what the tool returns, then the caveats and cost model; sentences carry information rather than filler. It is dense and slightly long, but nearly every clause (rounding, refund, credit cost) 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?

With no output schema, the description does the work of naming returned fields (including the raw.* sub-fields) and the cost/refund behavior, which is enough for an agent to call it correctly. The only real gap is cache_max_age, undocumented anywhere, which slightly weakens completeness for a 3-parameter 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?

extra_fetch is explained in depth, including its cost model (1 extra credit per page, large additional fetch) and its effect on createdAt, adding real meaning beyond the schema's generic wording. url is only implied from 'Page URL, @handle, slug, or numeric page id', and cache_max_age is completely unaddressed in both schema and description, keeping this below 5 despite 67% coverage.

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 resource – a public Facebook Page profile – and enumerates the fields returned (name, category, follower/like counts, description, banner, outbound links), so the agent knows exactly what it gets. It doesn't explicitly contrast with siblings like facebook_pagePosts or facebook_profilePhotos, leaving that distinction to name 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?

There is no statement of when to use this tool versus the many sibling facebook_* tools (pagePosts, pageAds, profileEvents). The only conditional guidance is parameter-level ('Pass extra_fetch=true to also fill createdAt'), which is invocation guidance rather than tool-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 cover the safety profile (readOnlyHint, openWorldHint), and the description adds real behavioral context: result ordering (upcoming first, past included where listed), fixed page size of eight, cursor-based continuation, and a stated cost of 1 credit. Rate limits or failure modes for private/removed pages are not mentioned, 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?

Three short sentences, all load-bearing: what it returns, how it orders and paginates, and what it costs. The key scoping and ordering facts are front-loaded 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 steps in to describe the returned fields (start time, place, host, cover photo) and the pagination model, which is what an agent needs. The only gap is the undocumented cache_max_age parameter and no hint about empty results for pages without events.

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 reinforces cursor semantics ('pass pagination.cursor back for the next eight'), tying it to the page size rather than merely restating the schema. Url forms and cursor were already covered by the schema (67% coverage), but cache_max_age remains undocumented in both places, so it is not fully compensated.

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 and narrows scope: events hosted by a public Facebook Page, ordered upcoming-first. That distinguishes it in practice from facebook_event (a single event), facebook_eventsSearch (search) and facebook_cityEvents (city-based), though no sibling is named explicitly, so an agent must infer the boundary.

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 the 'public Facebook Page' scoping and the pagination instruction, but there is no explicit when-to-use / when-not guidance, e.g. no note that event *search* belongs to facebook_eventsSearch or that cities belong to facebook_cityEvents. The agent has to derive the routing itself.

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