Captapi

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

The description discloses cost (0 credits) and caching behavior (cache=true for free 24h hit), adding some transparency. However, it instructs to 'Pass cache=true' while the input schema has no parameters, creating a direct contradiction. This is misleading and undermines behavioral clarity, especially without annotations to fill the 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?

The description is short but not well-structured. It mixes output fields, cost, and caching in a single run-on sentence. While it is concise, the sequence is jumbled and the 'Pass cache=true' instruction is ambiguous. It could be reorganized for 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?

The description lists output fields (plan, credits, quota, renewsAt) but lacks context on return format, authentication requirements, error behavior, or how the cache feature works given the schema lacks the parameter. For a zero-param tool with no output schema, more detail is needed to fully understand the tool's 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?

With zero parameters, the baseline is 4, but the description introduces a 'cache' parameter not present in the schema. This is misleading and actively harms understanding of what arguments may be passed. Since the schema is empty and the description adds a nonexistent parameter, it fails to provide value and introduces confusion.

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 indicates the tool returns account balance information: plan type, subscription vs top-up credits, monthly quota, and renewsAt date. It effectively conveys the resource and fields, though it does not explicitly state 'get balance' or 'retrieve account balance.' It is distinguishable from siblings like usage and request history.

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 is provided on when to use this tool versus alternatives. It mentions cost (0 credits) and caching behavior but does not state prerequisites, typical use cases, or why one would call this over related account tools. The context is minimal and lacks explicit 'use when' instructions.

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 no annotations, the description carries the full burden. It usefully discloses zero cost, free failures/empty results, and cache behavior, but the claimed cache parameter does not exist in the schema. It also does not describe the shape of the returned daily usage data.

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 first sentence is front-loaded and clear, but 'Costs 0 credits' redundantly repeats the earlier '(0 credits)'. The invalid cache instruction adds confusion rather than value; two brief sentences still contain notable 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?

This is a simple one-parameter tool with no output schema, and the description covers cost, caching, and failure policy. However, the invalid cache reference makes the instructions internally inconsistent, and it does not clarify what fields each daily usage entry 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?

The schema documents 'days' well with default 30 and max 365, so the baseline is 3. However, the description invents a 'cache=true' parameter that the schema explicitly rejects via additionalProperties:false, creating harmful parameter confusion. It also adds no real meaning to the documented 'days' 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 opens with a specific verb+resource: 'Day-by-day credit usage for spend monitoring', which clearly distinguishes it from sibling tools like account_balance and account_request_history. The scope and free credit cost are immediately visible.

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

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

It provides some context ('for spend monitoring') but no explicit when-to-use vs alternatives or exclusions. More importantly, it instructs 'Pass cache=true' even though the input schema only includes 'days' and additionalProperties is false, so this guidance is misleading and would fail validation.

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?

No annotations are present, so the description carries the transparency burden. It usefully discloses that the call costs 0 credits, that empty results and failures are never charged, and that caching is fresh by default. The claim 'Pass cache=true' is not supported by the schema, which creates a transparency gap despite the useful cost-related 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 short, front-loaded, and easy to scan, with the most important facts in the first sentence. The only issue is the redundant mention of 0 credits twice, but overall it avoids unnecessary elaboration.

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 tool with two optional schema-described parameters, the description covers purpose, cost, failure behavior, and cache behavior. The unsupported cache parameter and lack of anything describing the ranked output structure or route identifier format leave some gaps, but the tool is mostly understandable.

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 input schema already has 100% coverage for days and limit, including defaults and ranges, so the description does not need to add param-level detail. However, the description explicitly instructs callers to pass cache=true, but no such parameter exists in the schema and additionalProperties is false; this actively misleads invocation.

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 says it returns a ranked list of Captapi routes by usage for the caller's key, which makes the purpose specific and distinct from sibling account tools like account_balance or account_daily_usage. It could be more explicit about what a 'route' is and how the ranking is ordered, but the core intent 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?

Usage is implied: use this tool to see which Captapi routes your key consumes most, especially when cost is a concern since it is free. However, there is no explicit guidance on when to choose this over account_daily_usage or account_request_history, and no when-not-to-use advice.

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

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

The description discloses cost behavior (0 credits, no charge for empty results/failures) and hints at a caching mechanism. However, it references a 'cache' parameter that does not exist in the schema (additionalProperties: false), which is misleading. It does not describe pagination details or error behavior beyond what the schema implies, but the cost transparency is valuable.

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 a single sentence that conveys multiple pieces of information (purpose, cost, cache behavior). It is concise but slightly dense and could be clearer with line breaks. Overall, it is efficient without unnecessary fluff.

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 provides some context by listing likely return fields (requestId, status, credits, cacheHit). It does not explain pagination beyond the schema's cursor description, nor does it clarify the cache behavior given the missing parameter. The description is adequate but leaves some ambiguity about the cache option and what exactly is returned.

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?

All six parameters are fully described in the schema (100% coverage), so the description does not need to repeat them. The description does not add any extra meaning to the parameters; it only mentions a non-existent 'cache' parameter, which does not help. Baseline is 3 given full schema 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 clearly states the tool's purpose: retrieving recent API requests for the user's key, listing key fields like requestId, status, credits, and cacheHit. It is distinct from sibling tools such as account_balance and account_daily_usage, which focus on balance and usage totals rather than individual request history.

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 provides some usage guidance, including that the tool costs 0 credits and that empty results/failures are never charged, which reassures the agent about cost. It also mentions a caching option ('Pass cache=true') but this parameter is not present in the schema, which could mislead. No explicit guidance on when to prefer this over alternatives is given, but its distinct purpose implies when it should be used.

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 no annotations, the description carries the full disclosure burden and does so well: it states the credit model (1 per 16 products), the failure/empty-result billing exemption, and that caching is opt-in with a 24h window and fresh-by-default behavior. It omits auth/permission requirements and rate limits, but the cost and cache semantics are unusually well covered.

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 resource identity before cost details, and every clause carries information (URL patterns, exclusion, pricing, cache). The heavy em-dash chaining makes it slightly dense to parse, but there is no padding.

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

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

For a five-parameter scraping tool with no annotations and no output schema, the description supplies purpose, an exclusion, return contents, pricing, failure billing, and cache behavior. Remaining gaps (auth prerequisites, pagination workflow expectations) are minor given the fully documented input schema.

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 schema itself already documents the billing math for `limit` and the cache semantics, so the description largely restates rather than extends it. Baseline 3 is appropriate — it adds no parameter meaning the agent cannot already read 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?

Names the precise resource (third-party seller storefronts at /sp?seller= or /s?me=), the payload it returns (ASIN, canonical /dp URLs, price, badges), and explicitly excludes the lookalike influencer /shop/{handle} route. An agent can distinguish this from any other shop-scraping sibling without opening a schema.

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

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

Gives clear context for use plus a real exclusion (not influencer /shop/ pages) and decision-relevant cost framing (default limit 20 = 2 credits, cache=true for a free hit). It stops short of naming an alternative sibling to use when the target is an influencer shop, so it is clear but not fully prescriptive.

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 no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses the credit cost per URL, states that empty results and failures are never charged, and explains the cache behavior including the default 'always fresh' mode. This goes well beyond what the input schema states.

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 uses three tight sentences, front-loading the core purpose before cost and caching details. Every sentence adds distinct information with no filler or repetition of the schema verbatim.

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

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

The tool is simple with only two parameters and no output schema, and the description covers purpose, input limits, platform scope, output row semantics, cost behavior, and cache behavior. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by clarifying the per-URL credit cost, the cache hit pricing, the unified metrics output shape, and the flexibility of mixing platforms. This is useful context beyond the schema's basic field descriptions.

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 opens with a specific verb and resource: 'Compare unified metrics across up to 10 URLs.' It clearly distinguishes this tool from single-URL analytics tools like analytics_post by emphasizing multi-URL comparison. The mention of each row being an analytics/post object further grounds what the tool returns.

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 clearly implies this tool is for comparing multiple URLs at once, and references Post Analytics to indicate platform scope. It does not explicitly say 'use analytics_post for a single URL' or list exclusion conditions, but the multi-URL comparison context gives an agent clear situational 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 no annotations, the description carries the burden and it delivers meaningful behavioral detail: 1-credit cost, no charge for empty results/failures, and cache behavior with a free 24h hit when cache=true. It does not describe what metrics are included or any rate limits, which keeps it from a 5.

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

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

The description is short and front-loaded with the core purpose. It loses a point because 'Costs 1 credit' repeats the parenthetical '(1 credit)' in the first 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?

For a two-parameter tool with no output schema, it covers cost, caching, and platform scope, but 'unified metrics' does not say what metrics are actually returned. An agent can invoke it correctly but may not know whether the response satisfies a request for specific data.

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 both url and cache are already fully documented, so the description adds only cost/cache context rather than parameter meaning. 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: returns unified metrics for a single post, video, or reel, with platform auto-detection. The schema's 'unlike single-platform endpoints' explicitly distinguishes it from the many platform-specific detail tools in the sibling list.

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 plus schema gives a clear use case: cross-platform URLs expected for unified metrics, as opposed to single-platform endpoints. It does not explicitly rule out alternatives like analytics_compare or platform-specific deep-dive tools, so it stops short of a full when/when-not decision rule.

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 no annotations, the description carries the behavioral disclosure burden and does so well: it discloses the 1-credit cost, that empty results and failures are never charged, and the free caching behavior. It does not mention rate limits or auth requirements, but for a read-only fetch tool the cost and caching transparency is substantial.

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 compact and front-loads the core purpose and return content. The cost information is slightly redundant ('(1 credit)' followed by 'Costs 1 credit'), and 'Post thread' is ambiguous as a verb phrase, but the overall structure 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?

The description covers the key invocation details: required URL, cache behavior, depth mapping, cost, failure billing, and the main returned fields. With no output schema, it gives enough return-content context for an agent to understand what the tool provides, though it could add explicit sibling differentiation.

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

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

Schema description coverage is 100%, so the schema already documents url, cache, and depth. The description adds some context around caching and cost, but it does not add meaningfully new parameter-level semantics beyond what the input schema already provides.

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 it returns a Bluesky post thread via getPostThread and lists the returned content: nested replies, facet links/mentions/hashtags, and rich author info. This distinguishes it from profile and user-post sibling tools, though the phrasing 'Post thread' is terse and could more explicitly say 'retrieve details for a single Bluesky post and its replies.'

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 clear operational guidance, such as using cache=true for a free 24h cache hit and defaulting to fresh fetches. However, it does not explicitly state when to choose this tool over alternatives like bluesky_profile or bluesky_user_posts, leaving usage context implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and does a solid job: it discloses the 1-credit cost, states that empty results and failures are never charged, and explains caching behavior (cache=true gives a free 24h hit; default is always fresh). It does not explicitly state read-only behavior, but that is reasonably implied by 'profile' retrieval. The billing and caching specifics add meaningful transparency beyond basic expectations.

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 compact and front-loads the profile contents, but it contains redundancy: '(1 credit)' appears in the first clause and 'Costs 1 credit' repeats the same information in the second sentence. The caching guidance is concise, but the duplication means not every sentence 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?

Given there is no output schema and no annotations, the description provides a good inventory of return fields, the credit cost, failure non-charging, and cache options. It doesn't cover rate limits or authentication, but for a straightforward profile fetch these may not be critical. The 'associated{}' and 'verification{}' notation is slightly cryptic but acceptable. Overall, it is reasonably complete for invoking the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds valuable semantic context: it clarifies that cache=true yields a free 24h cache hit, distinguishes this from default always-fresh behavior, and points to cacheMaxAge for 1d–30d freshness control. This goes beyond the schema's generic 'default TTL' and helps the agent make informed caching choices.

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

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

The description clearly identifies the resource as a Bluesky profile and lists the returned fields (handle, did, bio, counts, banner, verification{}, labels[], associated{}), so an agent knows exactly what the tool produces. It lacks an explicit verb like 'fetch' or 'get', but the resource and payload scope are clear. It doesn't explicitly distinguish from sibling tools like bluesky_user_posts, but the platform and 'profile' focus make the purpose reasonably distinct.

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 provides no guidance on when to use this tool versus alternative siblings such as bluesky_user_posts or bluesky_post_details. It does offer caching usage tips (cache=true for a free 24h cache hit, prefer cacheMaxAge for 1d–30d), but that is parameter handling rather than tool-selection guidance. No exclusions or alternative references are present.

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 no annotations provided, the description carries the full burden of behavioral disclosure, and it does a strong job: it reveals repost marking, embed types, opaque cursor semantics, credit costs per result, the fact that empty results and failures are not charged, and cache behavior. It does not cover every possible behavior like rate limits or explicit output shape, but the provided details add meaningful transparency.

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 extremely compact and front-loaded: it opens with the core resource and content type, then adds cost and caching details in short, scannable sentences. Every sentence contributes useful information 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?

Given six parameters, no output schema, and no annotations, the description is largely complete: it covers content, repost markers, embeds, cursor pagination, costs, failure billing, and cache behavior. It stops short of describing the exact response envelope or error format, which would make it fully complete in the absence of an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3 even without parameter detail in the description. The description adds some value by explaining the opaque cursor, cache hit behavior, and per-result billing, which relate to cursor, cache, and limit, but it does not need to restate the schema's already thorough parameter docs.

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

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

The description clearly identifies the resource as an 'Author feed' containing posts and reposts, with reposts marked via isRepost and various embed types. It differentiates from sibling tools like bluesky_profile and bluesky_post_details by emphasizing feed-level listing behavior, though it lacks an explicit verb like 'fetch' or 'list'.

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 context about caching and cost, but it does not explicitly state when to choose this tool over alternatives such as bluesky_profile or bluesky_post_details. Usage is only implied by the phrase 'Author feed' rather than explicitly routed with when-to-use or when-not-to-use 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does this well by stating the flat 2-credit cost, that empty results and failures are never charged, that cache=true yields a free 24h hit, and that breakdowns appear only when Meta publishes them. It omits auth and rate-limit details, but those are less critical for a single-ad lookup.

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 definition is short, front-loaded, and delivers the core purpose in the opening phrase. The only notable flaw is the redundant 'Flat 2 credits. Costs 2 credits.' which slightly weakens the otherwise tight structure.

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 two-parameter lookup endpoint with no annotations and no output schema, the description is nearly complete: it explains what is returned, how much it costs, when it is free, and how it differs from search. It lacks explicit output-format or auth notes, but those are not essential for invoking this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's cache guidance largely duplicates the schema's cache property description, and it adds no URL-format details beyond what the schema already provides for the url 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 operation: retrieve one Meta ad by ID. 'Same creative as search, plus delivery breakdowns' distinguishes it from the search and transcript sibling tools without relying on the tool name alone.

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?

Implies the tool is for a known Meta ad ID/URL and that it adds delivery breakdowns beyond search results, but it never explicitly says when to choose this over facebook_ad_library_search or facebook_ad_library_ad_transcript. The schema's cross-platform warning is a parameter constraint, not 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses credit costs (2 credits), that empty results and failures are never charged, and cache semantics (free 24-hour hit vs. always-fresh default). It does not cover rate limits or error types, but it transparently covers the most decision-relevant behaviors.

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

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

The description is three short sentences with no wasted words: the core output and caveat come first, followed by pricing and cache options. Every sentence earns its place and the most critical distinguishing fact (not a speech transcript) is fron-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?

For a simple two-parameter read tool with 100% schema coverage and no output schema, the description is sufficient. It states the output fields, pricing, cache behavior, and non-transcript nature, while the schema handles URL platform constraints. Nothing needed to invoke the tool correctly is missing.

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

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

The input schema already fully describes both parameters, including URL/ID format, platform matching, and cache behavior, so schema coverage is 100% and the baseline is 3. The description adds no significant parameter-level detail beyond what the schema provides; it only reinforces cost and cache semantics.

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 exactly what the tool returns — written creative copy from a Meta ad (headline, body, CTA, landing URL) — and explicitly separates it from a speech transcript, which is crucial given the tool's name contains 'transcript'. This scope is unambiguous and distinguishes it from transcript-style siblings like youtube_transcript or tiktok_transcript.

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 provides clear context for when to use it: for Meta ad written copy, not speech audio. It also gives practical invocation guidance such as platform-match requirements and cache behavior. It does not explicitly name an alternative tool like facebook_ad_library_ad_details, but the non-transcript clarification and cost/cache notes give sufficient routing information.

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 no annotations, the description carries the safety and cost burden well: it discloses the 2-credit price, that empty results and failures are never charged, and that cache=true yields a free 24h hit while the default is always-fresh. It stops short of describing auth requirements, rate limits, or failure modes beyond billing.

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

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

One dense sentence plus two short ones; the scope, defaults, and billing posture are front-loaded with no filler. 'Same envelope as /facebook/search' is compact but cryptic enough to cost a point on 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 9-parameter tool with no annotations and no output schema, the description covers cost and defaults but leaves the return shape and pagination behavior largely unaddressed, deferring to 'same envelope as /facebook/search.' Adequate but with real gaps for an agent assembling a correct 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 100%, so the schema already explains url formats, limit, cursor, status, country, sort_by, and the date window in detail. The description only echoes the defaults (active, top-by-impressions order, sort_by and date window) without adding syntax or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

The first clause states a specific resource and scope: ads from a single Meta page, with the default status and ordering named. It does not, however, distinguish itself from close siblings like facebook_ad_library_search, facebook_ad_library_search_companies, or facebook_ad_library_ad_details, and the reference to 'same envelope as /facebook/search' points at a route rather than a 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?

Usage is implied rather than stated: 'active by default' and the cache note suggest the common case, but there is no explicit when-to-use or when-not-to-use guidance against the sibling ad-library tools. The agent must infer that this is the per-advertiser listing endpoint rather than the keyword search endpoint.

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 no annotations, the description carries the full behavioral burden and does real work: it discloses the 2-credit cost, the no-charge-on-empty-or-failure policy, the 24h cache semantics and that the default bypasses cache, and that spend/impressions are only sometimes published. Not covered are auth requirements, rate limits, or error taxonomy beyond the free-failure rule.

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 front-loaded sentences: the operation and its filter surface first, then the cost/cache economics. Every clause carries information — no restatement of the title, 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 14-parameter tool with no annotations and no output schema, the description covers cost, caching, filter breadth and the data-availability caveat well. It stops short of telling the agent what a result record looks like or how nextCursor is returned, which is the main residual gap given the absent output schema.

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

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

Schema description coverage is 100%, so the schema already explains q, cursor, status, country, dates, platforms, media_type and trim. The description restates the same dimension list and adds only a small increment ("spend/impressions when Meta publishes them", the cache default), so the baseline 3 applies.

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

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

States a specific verb and resource ("Search Meta Ad Library by keyword") and enumerates the filter surface, so an agent immediately knows this is the keyword-search entry point for Meta ads. It does not name the closely related siblings (facebook_ad_library_company_ads, facebook_ad_library_search_companies) to disambiguate, which is the only thing keeping 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?

Usage guidance exists but is narrow: it tells you to pass cache=true for a free 24h hit and that defaults are always fresh, plus implicit economics (2 credits, free on empty/failure). There is no statement of when to prefer this over company_ads or ad_details lookups, so routing must be inferred from the tool name and the word "keyword".

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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses cost (2 credits), that empty results and failures are never charged, and the caching behavior (cache=true for free 24h hit). It does not mention rate limits or response format, but covers the key operational traits for a search tool.

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

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

The description is a single sentence that packs purpose, cost, failure policy, and caching into a front-loaded structure. It starts with the core function and adds key details without 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?

For a search tool with no output schema and no annotations, it covers cost, caching, and failure behavior. It does not detail response structure or rate limits, but these are minor given the tool's simplicity. The name-matching behavior is also hinted at in the schema, and the pageId vs profileId note adds context. Overall, it is adequate and nearly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the pageId vs profileId distinction for the q parameter, which clarifies the output semantics and is not present in the schema. It also reiterates cost and cache behavior, but those are operational rather than parameter-specific. The added pageId distinction justifies a 4.

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 Meta Ad Library pages by brand'. It distinguishes from siblings by noting 'pageId for company-ads (not profileId)', which separates it from generic search and profile-related tools. The purpose is unambiguous and clearly tied to company-brand pages.

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 clear context: it is for brand/company pages and returns pageId for company-ads rather than profileId. This implies when to use it over profile-focused tools, but it does not explicitly name alternatives or state exclusions, so guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful non-obvious operational details: the 2-credit cost, that empty results and failures are not charged, and that cache=true provides a free 24-hour hit. However, it does not state whether the operation is read-only, what side effects exist, or any rate-limit or authentication considerations.

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 dense, with each sentence delivering distinct operational facts about cost, failure billing, and caching. The only waste is the redundant 'Comment Replies' at the start, but overall the structure is efficient and to the point.

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 fetch-replies tool, the schema covers parameters and the description covers credits and caching. However, there is no output schema and the description does not clarify the return shape, pagination, or how the results relate to the provided commentId, so some important context is missing.

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

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

Schema description coverage is 100%, so the parameters are already well-documented in the input schema. The description adds no new semantic meaning about the parameters beyond echoing the cache option, so the baseline score of 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 opens with 'Comment Replies', which merely restates the tool name rather than stating an action such as 'Fetch' or 'List'. It does not explicitly identify the resource or distinguish this from facebook_comments or the sibling comment-reply tools for other platforms.

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 is given about when to choose this tool over alternatives like facebook_comments or youtube_comment_replies. The description focuses on credits and caching, not on the conditions that should lead an agent to select this endpoint.

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 no annotations, the description carries the full burden and does disclose meaningful behavioral traits: cost per call (2 credits), free on empty/failure, cache behavior (default fresh, 24h hit with cache=true), and the conditional presence of reactions.like ('when mixed'). However, it omits other behavioral details such as whether only top-level comments are returned, pagination behavior, auth requirements, or rate limits.

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 two compact sentences with no fluff; the first sentence front-loads the resource and key output fields, the second packs cost and cache behavior. Every clause earns its place and the wording is dense but readable.

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

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

Given there is no output schema and no annotations, the description should clarify the response shape and usage scope, but it only lists a few fields and omits whether the result is an array, how pagination works, and the difference from comment replies. The schema enriches some context (URL can be a post or Reel, feedbackId from details), so it is adequate but not 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 description coverage is 100%, with all four parameters (url, cache, limit, feedbackId) already documented in the input schema. The description mostly duplicates the cache behavior ('Pass cache=true') and adds cost/cache side effects, but offers no new parameter semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

The description clearly identifies the resource as 'Facebook post comments' and enumerates the exact fields returned (reactionCount, reactions.like when mixed, author.id pfbid, replyCount), which makes the tool's function unambiguous. However, it lacks an explicit verb like 'retrieves' or 'lists' and does not distinguish itself from the sibling facebook_comment_replies within the description text itself.

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 provides conditional guidance only for caching ('Pass cache=true for a free 24h cache hit') and cost behavior, not for tool selection. It never states when to use facebook_comments versus facebook_comment_replies, facebook_details, or other platform-comment tools like youtube_comments or tiktok_comments.

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 no annotations, the description must carry full behavioral disclosure, and it does so by stating the 2-credit cost, the no-charge policy for empty/failed results, the free 24h cache behavior versus default fresh fetch, and the caveat that some fields appear only 'when Facebook exposes them.' It doesn't discuss rate limits or auth, but the public-URL constraint is in the schema, and the disclosed items go well beyond a bare description.

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 lead with the resource and returned fields, then cover cost, charge policy, and caching. No filler or repetition; each sentence adds information. The only slight cryptic element is 'video{} playback', but it conveys the object shape without bloat.

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?

Without an output schema, the description supplies the key return categories and the variability caveat ('when Facebook exposes them'), plus cost and caching behavior. It doesn't cover every edge case (e.g., private posts, redirects), but for a 2-parameter tool with a well-documented schema this is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents both url and cache. The description's cache statement ('Pass cache=true for a free 24h cache hit (default always fresh)') restates the schema's default-false semantics, adding no new meaning. Baseline of 3 is appropriate because the description doesn't need to compensate.

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

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

The description identifies the target resource ('Facebook post or Reel') and enumerates returned content (caption, engagement, author id, video{} playback, music), distinguishing it from sibling Facebook tools like facebook_comments or facebook_page_details. However, there is no explicit verb like 'retrieves' or 'fetches', so the action is inferred 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?

The description implies the use case — call when you need details of a single Facebook post or Reel — but it never names alternative tools or conditions for choosing between them (e.g., facebook_comments for comments, facebook_profile_posts for a user's posts). The only guidance present is about not passing cross-platform URLs, which is a parameter constraint in the schema rather than tool-selection advice.

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 no annotations, the description carries the full behavioral burden and covers several operational traits: costs 2 credits, free 24h cache hits with cache=true, and no charge for empty results or failures. It also notes attendance is only returned 'when exposed,' setting expectations about field availability. It does not mention rate limits, auth, or private-event restrictions, but the core cost/failure behavior is disclosed.

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 sentences, front-loaded with the tool's purpose followed by cost and caching. No filler or redundancy; every sentence 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 two-parameter lookup with no output schema, the description is nearly complete: it names returned fields, cost model, and cache behavior. The only notable gap is explicit routing guidance among Facebook sibling tools, but that is more about tool selection than invocation context.

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%, with both url and cache fully documented. The description's cache note ('free 24h cache hit... default always fresh') largely mirrors the schema and adds no new parameter semantics beyond what is already structured.

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 uses a specific verb ('Get') and resource ('Facebook event') and enumerates the exact data fields returned: title, local start/end, timezone, place, host id, and attendance. This clearly differentiates it from sibling tools like facebook_event_search or facebook_profile_events.

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 when an agent has a Facebook event URL, and the schema's url parameter reinforces the platform-match constraint. However, it never explicitly names alternatives like facebook_event_search or states when not to use this tool, so guidance is only implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and delivers meaningful behavioral disclosures: '2 credits', 'Empty results and failures are never charged', and 'Pass cache=true for a free 24h cache hit (default always fresh)'. This is valuable economic and caching context. It does not cover rate limits, latency, or fetch-path behavior, but the disclosed traits are substantive.

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 compact and front-loads purpose before cost and cache details, which is good structure. However, '2 credits. Costs 2 credits.' is a direct duplication of the same information — a sentence that fails to earn its place and indicates sloppy editing.

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 moderate-complexity tool (7 params, all schema-documented), the description plus schema cover purpose, result content, cost, cache, and failure-charge policy reasonably well. Gaps remain: no explicit sibling routing, no output schema to describe return shape beyond a partial hint, and no operational limits like rate ceilings. Adequate but not 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 description coverage is 100%, so the baseline is 3 and the schema already documents all seven parameters. The description adds only marginal reinforcement — it restates cache behavior ('Pass cache=true for a free 24h cache hit') and references 'local startDate/timezone' which maps to the to/from filters, but adds no new format or syntax details beyond the schema.

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

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

The description states a specific verb and resource — 'Search Facebook events' — with a clear scope: 'by topic and city'. It further specifies result content ('local startDate/timezone, venue'), which lets an agent distinguish this from facebook_event_details (single-event retrieval) and facebook_profile_events (profile-scoped events) without opening either schema.

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

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

Usage context is implied by the scope phrase 'Search Facebook events by topic and city' — an agent can infer this is the tool for topic/city-based event discovery. However, there are no explicit alternatives, exclusions, or when-not-to-use conditions, and several closely related siblings (facebook_event_details, facebook_profile_events) are not mentioned.

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

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

With no annotations, the description carries the full disclosure burden and does well on the billing side: 1 credit per post, ~20 credits per call, empty results and failures never charged, and cache=true yielding a free 24h hit while default is always fresh. It does not cover auth requirements, rate limits, or pagination behavior, so it is not fully transparent.

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 resource and returned fields, then the cost model, in four compact clauses. Minor redundancy: '1 credit per post' and 'Costs ~20 credits (1/result)' say the same thing twice, which is the only wasted space.

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 annotations and no output schema, the description covers the critical unknowns an agent needs: what it returns, what it costs, and how caching affects both latency and price. Only secondary concerns like auth, rate limits, and pagination depth are unaddressed, and truncation is already handled in the schema.

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

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

Schema description coverage is 100%, so the schema already documents url, cache, limit, and sortBy fully, including billing and truncation behavior. The description largely restates the cost-per-result and cache semantics without adding syntax or format detail beyond the schema; baseline 3 is correct.

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

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

States a specific verb+resource combination ('Newest posts from a public Facebook group') and enumerates the returned fields (caption, author, engagement, sortBy). It distinguishes itself from profile/page post endpoints only implicitly via 'group', leaving the explicit alternative (facebook_profile_posts) to the schema rather than the description.

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 no when-to-use or when-not-to-use guidance and never names a sibling tool as an alternative. The routing rule ('profile/page URLs ... use /v1/facebook/profile-posts') lives only in the url schema field, so an agent reading the description alone gets no 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?

With no annotations provided, the description carries the full burden and discloses meaningful operational behavior: the exact credit cost, that empty results and failures are not charged, and that cache=true provides a free 24h cache hit. It does not explicitly state read-only semantics or rate limits, but the billing and caching details are unusually specific and valuable.

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 compact and front-loads the resource and key fields before moving to cost and caching details. The phrase 'coords (2 credits)' is slightly cryptic, but the overall structure is efficient and each sentence contributes 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 simple two-parameter tool with no output schema, the description lists the expected return fields and covers billing, failure charging, and cache behavior. It could be more explicit about URL input and error details, but the schema covers the URL and the description mentions failures.

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 input schema already provides 100% parameter coverage, including URL platform matching and cache behavior. The description mostly reiterates the cache parameter and cost, adding no new semantic meaning beyond what the schema already documents.

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

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

The description identifies a Marketplace listing and enumerates its returned fields (title, priceAmount, status, seller, condition, coords), making it clear this is an item-detail endpoint. It lacks an explicit verb like 'fetch' or 'get', but the resource scope is unambiguous and distinguishable from the marketplace search 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?

The description implies usage with a specific Marketplace item URL and touches on cache usage, but it never explicitly contrasts this tool with facebook_marketplace_search or facebook_marketplace_location_search. The intended use case is inferable from the required URL and the term 'Marketplace listing', but no direct guidance is 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?

With no annotations provided, the description carries full behavioral disclosure burden. It explicitly states the flat 2-credit cost, that empty results and failures are never charged, and the cache semantics (cache=true gives a free 24h hit, default is always fresh). These are the key behavioral traits an agent needs to make cost-aware decisions, and they are communicated clearly.

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-loads the purpose and output. However, it contains a redundant duplicate: 'Flat 2 credits. Costs 2 credits.' — the same fact stated twice in adjacent fragments. Otherwise every sentence earns its place, covering output, cost, failure pricing, and cache behavior.

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 3-parameter tool with no output schema, the description covers purpose, cost, caching, and a partial output shape (id + lat/lng). It is complete enough for an agent to call the tool correctly. It could be stronger by describing the response structure in more detail, but the minimal output hint is sufficient for this use 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 description coverage is 100%, so the baseline is 3. The description adds no new parameter meaning beyond the schema: it repeats the cache cost/behavior already documented in the schema and does not add details for 'q' or 'limit'. The useful cost-on-failure note is behavioral rather than parameter-specific.

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 opens with a specific verb and resource: 'Disambiguate city names into Marketplace hubs — id + lat/lng.' This clearly distinguishes the tool from siblings like facebook_marketplace_search and facebook_marketplace_item, which handle listings rather than location resolution. It also names the key output fields, leaving no ambiguity about what the tool produces.

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 intended use case is implied by 'Disambiguate city names into Marketplace hubs' — an agent can infer it should be called when a city string needs resolving to a hub ID. However, it never explicitly states when to prefer this over the sibling search tools, nor does it mention any exclusions or preconditions. The guidance is present but left 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?

With no annotations at all, the description carries the full burden and does it well: it discloses the 2-credit cost, that empty results and failures are never billed, that cache hits are free for 24h, and that the cursor is opaque and endpoint-issued. It omits rate limits, auth requirements, and the response envelope shape, which keeps it below 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?

Dense and front-loaded, leading with what the tool does before costs. It wastes a sentence on redundancy — "(2 credits). Costs 2 credits." repeats the same fact — which prevents a 5.

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 16-parameter paid tool with no annotations and no output schema, the description covers pricing and the cache lever but says nothing about what comes back (nextCursor, rows, filters echo, isLocal flags beyond a passing mention). The schema handles inputs thoroughly, but the return contract is left undescribed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little meaning — keyword+city intent, the local/shipsOutsideRadius distinction, and cache semantics — but the per-parameter pricing tiers, radius increments, and enum values are already fully documented 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 plus scope: "Search Marketplace by keyword + city" with filters, local/shipping flags, and cursor paging. It clearly separates this from a single-item lookup like facebook_marketplace_item, but never names a sibling explicitly, so differentiation is inferred 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?

The description gives operational guidance on cache=true versus fresh fetches and says empty results and failures are free, which steers invocation. It does not say when to prefer facebook_marketplace_item (item detail) or facebook_marketplace_location_search (resolve a city), so the choice between marketplace siblings is left to the agent.

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 no annotations provided, the description carries the full burden of disclosing behavior. It usefully discloses the 2-credit cost, that empty results and failures are never charged, and the cache behavior with cache=true. This goes beyond surface-level purpose and gives an agent actionable operational expectations, though it does not discuss rate limits or error response specifics.

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 a compact two-sentence structure: the first sentence conveys purpose and key output fields, and the second covers cost and caching. There is no filler or redundant elaboration; every clause contributes 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?

The tool is simple, has only two well-documented parameters, and no output schema, so the description's listing of returned fields partially compensates. It also covers costing and cache behavior, which are important operational details. It could be more complete by clarifying the shape of the response or handling of missing pages, but overall it is sufficient for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents both url and cache parameters well. The description restates the cache behavior already present in the schema, adding no meaningful new parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly identifies the resource as a Facebook page profile and lists specific returned data like likes vs followers, talkingAbout, category, website, and public email. However, it lacks an explicit verb like 'retrieves' or 'returns', and it does not explicitly differentiate itself from the similar sibling facebook_details.

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 no guidance on when to use this tool versus alternatives such as facebook_details or facebook_summarize. It mentions cache usage and credit cost, but offers no selection criteria or exclusions to help route an agent to the correct endpoint.

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 no annotations, the description carries the full burden and does a solid job: it discloses the 2-credit cost, that empty results and failures are never charged, and the cache semantics (free 24h hit, default always fresh). These are meaningful behavioral details beyond the basic 'list' action, though it does not cover rate limits or detailed return structure.

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 the core purpose, but it redundantly states '2 credits. Costs 2 credits.' and largely repeats the schema's cache explanation. The redundancy makes it less crisp than it could be.

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

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

Together with the fully described schema, the description is nearly complete: it covers the purpose, output fields, cost, cache behavior, and failure charging. The main gap is lack of sibling routing context, which is already accounted for in usage_guidelines; nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, with detailed descriptions for url, cache, and limit, so the baseline applies. The description only restates cache behavior and credit cost already present in the schema, adding no new parameter-level meaning.

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 opens with a specific verb and resource — 'List a Facebook Page's events' — and adds the distinguishing output fields (local startDate, timezone, venue). This makes it clearly distinguishable from siblings like facebook_event_search (general event search) and facebook_event_details (details of a single 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?

The description implies a use case (listing events for a specific Facebook page) but provides no explicit when-to-use guidance or named alternatives. It does not tell the agent to prefer this tool over facebook_event_search or facebook_event_details, nor does it state any 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?

With no annotations provided, the description carries the full burden and does well: it discloses the 2-credit cost, that empty results and failures are never charged, the 24h cache behavior, and clarifies that accessibilityCaption is alt-text 'not a post caption'—a valuable disambiguation. It lacks only minor context such as rate limits or authentication needs, but the cost/cache/failure disclosures are strong for a public data-fetch tool.

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

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

Four short sentences, each earning its place: purpose/output, cost, failure billing policy, and cache behavior. The core purpose is front-loaded first, and there is zero filler or repetition beyond what a standalone description legitimately needs.

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

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

For a 3-parameter tool with 100% schema coverage and no annotations, the description covers the important operational facts: cost, non-charging of failures, cache semantics, and the key return field (accessibilityCaption). The absence of an output schema is a structural gap, but the description partially compensates by naming the return fields. Minor omissions like pagination behavior or error semantics are acceptable given the schema's rich limit parameter explanation.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's cache and credit mentions largely restate what the schema's cache and limit descriptions already say ('0 credits on hit', 'Flat 2 credits per call'). The accessibilityCaption note is output semantics rather than parameter meaning, so the description adds little beyond the schema 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 clearly identifies the resource—'Photo grid from a Facebook Page'—and specifies the output contents (image URL plus accessibilityCaption). It is easily distinguished from siblings like facebook_profile_posts, facebook_profile_reels, and facebook_details because it is the only photos-oriented Facebook tool. However, it lacks an explicit verb ('Retrieves'/'Fetches'), phrased as a noun phrase rather than a specific verb+resource construction.

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 context is implied by the unique 'photo grid' purpose, and operational guidance is given ('Pass cache=true for a free 24h cache hit'). However, it does not explicitly state when to prefer this tool over any Facebook sibling, nor name alternatives or exclusions. The schema's URL note adds cross-platform constraints, but the description itself provides no tool-selection routing among the large sibling set.

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 no annotations provided, the description carries the behavioral burden. It discloses several non-obvious traits: the 2-credit cost, free 24h cache hits, no charge for empty results or failures, and the 60s deadline. This is valuable context beyond the schema. The cryptic 'listingHits / timings.phase' fragment is unexplained, preventing a perfect score.

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-loads the core purpose, but the phrase 'listingHits / timings.phase; 60s deadline, failures 0 credits' is dense, jargon-heavy, and poorly structured. It could convey the same operational facts more clearly, so it does not reach the level of a tightly written 4 or 5.

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?

The description covers cost, caching, and failure policy, but with no output schema and no sibling differentiation it leaves significant gaps: what fields the response contains, how this endpoint relates to Reels-only or page-details endpoints, and when to prefer it over facebook_profile_reels or facebook_page_details. For an agent choosing among many Facebook tools, this is insufficient.

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 schema already documents url, cache, and limit in substantial detail, including timing caps and truncation behavior. The description mostly repeats the cache guidance and does not add meaningful parameter semantics beyond what the schema provides, so the 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 opens with a clear verb and resource: 'Latest posts and Reels from a Facebook page.' This accurately states what the tool returns. It does not explicitly differentiate it from sibling tools like facebook_profile_reels or facebook_page_details, 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 guidance on when to use this tool instead of related siblings such as facebook_profile_reels, facebook_profile_events, or facebook_page_details. The cache and credit guidance is operationally useful, but it does not help an agent decide between this tool and its alternatives.

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 no annotations provided, the description carries full behavioral burden and excels: it discloses ordering behavior, exclusion of archive padding, credit cost, no-charge policies for empty results/failures, and cache semantics. All of these are concrete behavioral traits beyond the annotation-free 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?

The description is two sentences with zero filler. The core purpose and output characteristics are front-loaded, followed by cost and cache guidance. 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 simple list tool with 3 fully documented parameters and no output schema, the description is complete: it covers what data is returned, the ordering, filtering behavior, cost, failure handling, and cache options. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents url, cache, and limit parameters. The description reinforces the cache behavior ('free 24h cache hit' and 'default always fresh') but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource and scope: 'Latest Facebook page Reels' with the exact metrics returned (views, likes, comments, shares) and ordering ('newest-first'). It distinguishes itself from sibling profile tools like facebook_profile_posts or instagram_channel_reels by naming 'Facebook page Reels' as the specific target.

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 provides clear context for when to use the tool: for the latest Facebook page Reels, with explicit ordering and no archive padding. It also gives actionable guidance on cache usage ('Pass cache=true for a free 24h cache hit'). It does not explicitly name alternatives or when-not-to-use scenarios, but the context is unambiguous enough for an agent to select this tool correctly.

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 no annotations provided, the description carries the full behavioral disclosure burden and does so well for billing and caching: it states the 4-credit cost, that empty results and failures are free, and that cache=true yields a free 24-hour hit with a default of always fresh. This meaningfully informs the agent about side effects and costs, though it omits rate limits, auth, or response-shape 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?

The description is very short and contains no wasted words; the two sentences deliver the cost and cache facts efficiently. The awkward opening 'Summarizer' is a structural weakness, but overall conciseness is strong.

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?

The tool has no annotations and no output schema, so the description needs to specify what the tool does, what it returns, and when to select it. It does none of those things. The schema documents the parameters well, but the core purpose and selection context are missing, leaving an agent to rely on the tool name.

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 input schema already has 100% parameter coverage with detailed descriptions for both url and cache, including the cross-platform URL restriction and cache semantics. The description adds little beyond repeating the freshness default and attaching a cost implication to cache hits, so schema carries the load and the description is adequate but not additive.

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 opens with 'Summarizer' but never states what is summarized — no mention of Facebook, videos, posts, or any other resource. This is effectively a tautology of the tool name 'facebook_summarize'; the actual purpose must be inferred from the name and input schema rather than the description.

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 operational guidance about caching and cost, but it does not say when to use this tool versus sibling alternatives like facebook_details, facebook_comments, or video_summarize. There is no when-to-use or when-not-to-use framing 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?

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the 90-event ceiling, credit costs, free failures/empty results, and cache behavior. It does not describe sorting, return structure, or whether authentication is needed, but the core operational behavior is clearly exposed.

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 compact, front-loaded with the core purpose, and every clause earns its place: typed payload, ceiling, credits, failure charging, and cache behavior. There is no filler or repetition beyond what the context requires.

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

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

Given the moderate parameter complexity and absence of an output schema, the description is mostly complete: it explains what events are returned, gives payload examples, notes the ceiling, and covers costs and caching. It could be slightly stronger by outlining the response shape or pagination contract, but the essential operational details are 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 coverage is 100%, so the schema already documents all four parameters thoroughly. The description mostly restates what the schema says (limit's 90 max, cache being free, 24h cache), adding little new semantic meaning beyond emphasizing the overall ceiling and billing context.

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

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

The description clearly identifies the resource: GitHub public events with typed payload examples (Push commits/ref, PR/issue action). It is distinguishable from sibling tools like github_repositories or github_contributions, though it lacks an explicit verb like 'list' or 'retrieve' and does not name alternatives.

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 'Public events' implies this tool is for GitHub user activity feeds, and the payload examples narrow the use case. However, there is no explicit guidance on when to choose this instead of related GitHub tools such as github_contributions, github_repositories, or github_user.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important execution traits: a 2-credit cost, no charge for empty results or failures, default fresh fetch behavior, and the availability of a free cached response. The 'today grace' note hints at streak calculation nuance, though it is not fully explained.

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 compact and front-loaded with the core purpose. However, 'longestStreak (2 credits)' followed by 'Costs 2 credits' creates minor ambiguity about whether the 2 credits refers to the longestStreak field or the entire call, which costs a little 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 simple two-parameter tool, the description covers the essential operational context: cost, caching, failure charging policy, and a rough sketch of the return shape. It does not explicitly route the agent to a sibling for profile data or describe all output details in the absence of an output schema, but the needed info for a correct call 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 coverage is 100%, so the baseline is 3. The description reiterates the cache parameter's behavior ('cache=true for a free 24h cache hit') and mentions username indirectly through the tool's purpose, but it does not add meaningful detail beyond what the input schema already documents.

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

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

The description opens with a specific noun phrase 'GitHub contribution graph' and enumerates the output fields (sorted days[], currentStreak, longestStreak), making it clear this is about contribution history statistics. This distinguishes it from sibling tools like github_user, github_repositories, or github_activity, even without naming 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?

The description gives actionable usage guidance about cost and caching: using cache=true for a free 24-hour hit, and noting that empty results/failures are never charged. It does not explicitly compare to alternative GitHub tools or state when not to use it, so it misses the top score but provides clear operational 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?

With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses cost per result, approximate total cost, the 24h cache behavior, and that empty results and failures are never charged. It does not address auth or rate limits, but the cost and failure semantics are unusually explicit and valuable.

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

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

Every sentence earns its place: result shape, pricing and pagination warning, and cache/failure billing. The description is compact, front-loaded with the core purpose, and contains 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?

Despite having no annotations and no output schema, the description gives the agent the essential return fields, cost expectations, pagination caution, and cache behavior. It could be slightly more explicit that the response is a list for the specified username, but combined with the schema it leaves few gaps.

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

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

The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds useful pricing context for cache, limit, and paging, but it does not add new semantic meaning beyond what the schema already provides.

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

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

The description identifies the resource as follower cards and lists the returned fields, making it clear this tool returns followers for a GitHub user. It lacks an explicit verb like 'list' or 'get', and it does not explicitly distinguish itself from github_following, but the resource and output shape are 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?

The description implies usage context: pass a username, control cost with limit, and use cache=true for free repeated calls. It warns that large accounts are expensive to page fully, but it never explicitly says when to prefer this tool over alternatives like github_following or github_user, nor does it state 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds useful details about caching (cache=true for free 24h hit, default fresh) and billing behavior (empty results and failures not charged). However, it does not disclose output shape, pagination behavior beyond schema, rate limits, or whether the operation is read-only, though that is mildly implied.

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-loads the core purpose. There is some minor redundancy in the pricing statements ('same card and ~0.1/row pricing' followed by 'Costs ~3 credits (0.1/result)'), but the overall length is appropriate and every sentence contributes 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 simple list tool with a complete schema, the description is mostly adequate but leaves gaps: it does not mention what the response contains beyond 'accounts', lacks an alternative differentiation, and with no output schema, an agent might benefit from a note about pagination or result structure. The cost and cache details are helpful but not sufficient for full context.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not add new parameter semantics beyond what the schema already provides; it only reinforces the cache behavior already described 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 the resource clearly: 'Accounts a user follows,' which unambiguously identifies the following list. It does not use an explicit verb like 'list' or 'return', and while it mentions followers for pricing, it does not explicitly contrast itself with the github_followers sibling tool.

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

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

No guidance is given on when to use this tool versus alternatives. The only reference to followers is about pricing, not about choosing between github_followers and github_following. An agent is left to infer the use case from the tool name and description.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses credit costs, free caching semantics, no-charge on empty/failed results, opaque cursor behavior, and state echo. It does not mention auth requirements or error shape, but the important operational behaviors are covered.

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 tightly packed and front-loaded: the action and resource come first, followed by return hints, cost, and caching. Every sentence earns its place and there is no redundant restatement of schema fields.

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, the description communicates the essential return fields, pagination cursor behavior, cost model, and cache behavior. It could be more explicit about response envelope or error handling, but the information needed to invoke it correctly 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 coverage is 100%, setting the baseline at 3. The description adds value beyond the schema by clarifying that the cursor is an opaque GitHub Link token, that state is echoed as data.state, that cache=true yields a free 24h hit, and that billing is per result.

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?

Description opens with a specific verb and resource: "List repo PRs", and enumerates the key returned fields (draft, labels, author{}, head/base, cursor). This clearly distinguishes it from sibling GitHub tools like github_activity or github_repositories, which target different resource types.

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 context: call it when you need pull requests for a repository, with cache and state options detailed. It does not explicitly name alternatives or say when not to use it, so guidance is adequate but leaves 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?

With no annotations present, the description carries the full burden and delivers: cost model ('~12 credits (0.4/result)'), billing policy ('Empty results and failures are never charged'), cache semantics ('cache=true for a free 24h cache hit (default always fresh)'), and opaque-cursor pagination. This far exceeds typical transparency for a read tool.

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

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

Purpose is front-loaded in the first sentence, followed by cost, billing policy, and cache option — every sentence earns its place. A minor flaw: the per-item rate is stated twice ('~0.4/repo' and '0.4/result'), a small redundancy in an otherwise dense description.

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

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

For a 7-parameter tool with no annotations and no output schema, the description covers the unusual operational aspects (cost, empty/failure billing, cache, cursor) while the schema covers all parameter semantics. The remaining gap is the response shape, partially mitigated by schema hints like 'from a previous nextCursor' and 'Echoed as data.sort'.

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 schema itself is unusually rich (defaults, option lists, the 'Not stars' caveat, 'Not a bare page number' cursor warning, 'Echoed as data.*'). The tool description only references sort/direction/type and cache=true at a high level, adding no incremental parameter meaning beyond 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?

States a specific verb ('List') and a specific resource ('a user's repos'), with qualifying dimensions 'sort/direction/type'. The plural resource distinctly separates it from close siblings like github_repository (single repo) and github_trending_repositories (not user-scoped), so an agent can distinguish it 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?

The description gives clear operational context — caching, costs, cursor pagination — but never addresses when to pick this over alternatives. Among ~150 siblings, github_repository (singular) is an obvious alternative for one repo's details, yet no when/when-not or alternative routing is given; usage is only implied by the name and 'List a user's repos'.

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 no annotations provided, the description carries the disclosure burden. It usefully discloses the 1-credit cost, that empty results and failures are never charged, cache behavior, and a clarification that 'watchers' means real subscribers. This is substantive behavioral context beyond what the schema alone provides.

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-loads the returned fields before moving to cost and cache behavior. There is minor redundancy: 'parent when fork (1 credit)' followed by 'Costs 1 credit' re-states the credit cost. Overall, it is compact and scannable.

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 single-repository lookup with a well-documented input schema, the description covers the resource, key returned values, cost, failure policy, and caching. It does not explain how it relates to sibling GitHub tools, but the core information needed to invoke the tool correctly 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 100%, so the baseline is 3. Both parameters are already well documented in the schema, and the description does not meaningfully expand on the repo or cache parameters; it mainly restates cache cost behavior already present 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 names a specific resource ('GitHub repo') and enumerates the data fields it returns (stars, real watchers, openIssuesAndPrs, license, parent when fork), making the purpose reasonably clear. However, there is no explicit verb like 'retrieves' or 'fetches,' and it does not distinguish itself from the sibling github_repositories, 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 gives operational guidance about cost and cache usage ('Pass cache=true for a free 24h cache hit (default always fresh)'), but it never states when to use this tool versus alternatives such as github_repositories, github_user, or github_activity. No prerequisites, exclusions, or selection criteria are provided.

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 no annotations provided, the description carries the full behavioral burden and does meaningfully disclose cost (2 credits), free handling of empty results/failures, and cache semantics with a fresh-by-default policy. It does not cover rate limits or response shape, but it adds substantial non-obvious behavioral context beyond the basic operation.

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 compact and front-loaded with the endpoint and key semantics, followed by billing/cache caveats. It is slightly redundant in stating the 2-credit cost twice, but it remains efficient and scannable.

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, fully optional-parameter fetch tool, the description covers the source, return content, pricing, failure charging, and caching behavior. It lacks an explicit output shape, but the 'popularRepo + followers' mention gives the agent enough context to understand what will be returned.

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

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

Schema coverage is 100%, so the schema already documents cache, limit, since, and language thoroughly. The description reinforces cache behavior and the trending-window concept but adds little parameter meaning beyond what the schema provides.

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

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

The description clearly identifies the resource (github.com/trending/developers) and the core output concept: windowed ranks with popularRepo + followers. It distinguishes this from sibling github_trending_repositories by name and content, though it lacks an explicit imperative verb like 'Get' or 'List'.

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 it (when you need trending developers, optionally filtered by since window or language), and the since/language parameters provide usage context. However, it does not explicitly state when not to use it or name an alternative such as github_trending_repositories.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently covers cost (2 credits), free cache hits, the fact that empty results and failures are never charged, and the default fresh-fetch behavior. It does not describe output shape or failure response details, but the cost/caching disclosure goes well beyond the 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?

The description is compact and front-loaded with the core purpose, followed by cost, cache, and failure-billing behavior. There is minor redundancy: '2 credits' appears twice ('(2 credits)' and 'Costs 2 credits'), which wastes a few words but does not meaningfully hurt comprehension.

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 parameter-light read tool with full schema coverage, the description covers the key dimensions: purpose, ranking metric, windows, language option, cost, caching, and failure billing. No output schema exists, but the description conveys that it returns repos ranked by starsGained, which is enough for basic invocation; output-shape details are a minor but not critical gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter context beyond the schema: cost tied to limit, cache parameter behavior (0 credits on hit), accepted since windows, and language path semantics, plus the important 'not all-time stars' distinction.

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 explicitly identifies the resource (github.com/trending) and defines the core ranking criterion: repos ranked by starsGained over daily/weekly/monthly windows, not all-time stars. Though there is no imperative verb, the agent can unambiguously understand what this tool returns and distinguish it from all-time repository listing 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?

The description gives clear context for when to use this tool: when trending ranking by starsGained is desired, with an explicit exclusion of all-time star rankings. It also gives concrete cache-usage guidance (cache=true for a free hit, default always fresh). It does not explicitly name a sibling alternative or state when not to use it, so it stops short of the strongest 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 no annotations, the description carries the full burden and discloses genuinely useful behaviors beyond the schema: the 1-credit cost, that empty results and failures are never charged, and the 24h cache semantics with default-always-fresh. Rate limits and error handling are not covered, but the cost/cache/billing disclosure is substantive and well beyond what structured fields provide.

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

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

Four compact sentences with the purpose front-loaded and no filler. Minor redundancy: '1 credit' appears in both the first sentence ('followers (1 credit)') and the second sentence ('Costs 1 credit'), which is the only wasted increment.

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 2-parameter read tool with no annotations and no output schema, the description covers the core facts needed to invoke it correctly: returned fields, cost, cache behavior, and the billing-on-failure policy. Missing only explicit sibling routing and error behavior details, which are minor for a simple profile fetch.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cost context to cache=true (free on hit, fresh by default) that goes slightly beyond the schema's cache description, but it adds nothing material for username beyond what the schema already provides ('GitHub username or profile URL'). The schema does the heavy lifting here.

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

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

The description states a specific resource (GitHub public profile) and enumerates the returned fields (login, type User|Organization, email when public, followers), which distinguishes it from sibling GitHub tools like github_followers, github_repositories, and github_activity. An agent can infer what data it returns without opening the schema.

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

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

The field listing implies when to use this tool — when a user's profile identity, type, email, or follower count is needed — but it never names an alternative or states exclusions. With many github_* siblings present, explicit routing guidance would materially help selection, so the guidance stays at the implied level.

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 no annotations, the description carries the full burden of behavioral disclosure and does so thoroughly. It reveals credit costs, cache-hit pricing, that empty results and failures are never charged, that commercial ads omit spend/impression ranges, and defines isActive precisely in terms of lastShown within 7 UTC days.

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 high-value information: data availability caveat, isActive definition, credit cost, and cache behavior. There is no filler or repetition.

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

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

For a simple single-ad lookup with a 3-parameter schema, the description plus schema is nearly complete: the required ID, optional country, cache behavior, cost, and key output caveats are all covered. It could be more explicit about the response shape, but that gap is minor given the tool name and the first sentence.

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

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

Schema coverage is 100%, so creative_id, country, and cache are already well documented. The description adds some color about cost and cache behavior, but it largely restates what the schema already conveys, so the baseline of 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 tool name strongly implies this returns details for a single Google Ad Library ad, and the description reinforces that with creative lookups, spend/impression ranges, and isActive semantics. However, it never states an explicit verb like 'retrieves' or 'returns', and it does not differentiate itself from the close siblings google_ad_library_advertiser_search or google_ad_library_company_ads.

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 provides useful operational guidance around credits, caching, and charge behavior, but it gives no guidance on when to choose this tool over alternative Google Ad Library tools. There are no explicit when/when-not conditions or named alternatives, which is the core of this dimension.

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 no annotations provided, the description carries the burden of behavioral disclosure. It discloses credit costs, that empty results and failures are never charged, that results are ranked, and the caching behavior. These are meaningful operational behaviors beyond the input schema, though it does not describe the shape of the returned entities.

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 compact and front-loads the core purpose before the cost and caching details. Minor redundancy exists between '1 credit when found' and 'Costs 1 credit', but the overall structure is efficient and scannable.

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 4-parameter search tool with no output schema, the description provides the essential operational context: purpose, credit implications, caching, and failure charging. It does not detail the exact return shape, but 'ranked multi-result' plus the schema's parameter documentation is sufficient for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it explains ranking behavior with examples (US prefers Inc. over SRL), clarifies cache-hit pricing, and warns that non-ISO country codes cause a definitive 400 INVALID_COUNTRY error. This supplements the parameter definitions usefully.

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 a specific action ('Find') on a specific resource ('Google Ads Transparency ... entities') and indicates multi-result ranking. It does not explicitly distinguish itself from siblings like google_ad_library_company_ads, but the tool name and q parameter make the advertiser-search purpose 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?

The description gives useful operational context such as credit costs and cache behavior, and implies use for searching advertising entities. However, it does not explicitly state when to choose this tool over alternatives like google_ad_library_company_ads or google_ad_library_ad_details, nor does it mention 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?

With no annotations, the description carries the full burden — and it excels. It explicitly discloses credit costs (2 credits), the no-charge policy for empty results and failures, caching behavior (cache=true for a free 24h hit, default fresh), the spend/impression data-availability limitation, and precise isActive semantics (lastShown within 7 UTC days). This is rich behavioral context beyond what annotations would supply.

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 dense sentences with zero filler, front-loaded with the most decision-relevant caveat (spend/impressions only for election ads). Every sentence earns its place: field semantics, credit cost, charge exemption, and caching behavior are each covered in minimal words. The credit cost is conveyed in seven 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?

For a complex tool with 10 parameters, no output schema, and no annotations, the description covers the critical behavioral ground: costs, cache, data availability, and isActive meaning. Remaining gaps are an explicit statement of what the tool returns and routing against siblings, but the extraordinarily detailed schema compensates for much of that, leaving the definition nearly 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 description coverage is 100%, so the baseline is 3. The tool description adds no parameter-level meaning itself, but it doesn't need to — the schema already documents every parameter in detail, including the country soft filter, the 400 INVALID_COUNTRY failure mode, the 'all'-only topic constraint, and the region/country alias. The schema does the heavy lifting here.

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

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

The description never explicitly states the core function — listing a company's ads from the Google Ad Library. It opens with data-availability caveats (spend/impressions only for election ads) and behavioral notes (isActive, credits, cache), so an agent must infer the verb+resource from the tool name and schema. The resource is identifiable, but the primary purpose is implied rather than stated, making it vague for a 10-parameter tool.

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

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

No guidance on when to use this tool versus alternatives. The sibling list includes google_ad_library_ad_details, google_ad_library_advertiser_search, and facebook_ad_library_company_ads, and the description never distinguishes this tool from them or states conditions for choosing it. The closest hint is the schema's 'Prefer AR… from advertiser-search' in the advertiser parameter, but the tool-level description itself gives no routing or exclusion 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 no annotations, the description carries the full burden and does much of it: flat 2-credit pricing, failures and empty results never charged, cache semantics (default always fresh), and the explicit 'No emails' data limitation. It stops short of stating rate limits, auth requirements, or result-shape caveats beyond the field list.

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 and compact, with the field list first and the pricing/caching caveats after. It wastes a bit of space by stating pricing twice ('Flat 2 credits' then 'Costs 2 credits') in the same short paragraph.

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 6-parameter search tool with 100% schema coverage, no output schema, and no annotations, the description covers the key unknowns: cost model, failure billing, cache behavior, and available output fields. Only deeper operational details (limits on result quality, rate limits) are absent, which is minor here.

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

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

Schema description coverage is 100%, so all six parameters are already documented (q, cache, limit, language, location, locationCode). The description only restates the cache default and adds the 'no emails' constraint, adding little meaning beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb+resource ('Local businesses from a Maps search') and enumerates the returned fields (name, address, phone, website, rating, hours, place id), so an agent knows exactly what it gets. No sibling tool covers Maps/local business lookup, so differentiation is not required.

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 description (business lookup by keyword/location), and it does give one conditional instruction — pass cache=true for a free 24h hit. But there is no explicit when-to-use vs alternatives, no prerequisites, and no statement of when not to use 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?

With no annotations provided, the description carries the full behavioral burden, and it does substantial work: it discloses credit cost ('Costs 1 credit'), billing on failure ('Empty results and failures are never charged'), caching semantics ('free 24h cache hit'), and the default freshness policy. These are genuine behavioral traits that neither the schema nor annotations convey. It stops short of disclosing auth requirements or rate limits, which keeps it from a 5.

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

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

Four compact sentences, each earning its place: purpose, schema alignment, cost, failure billing, and caching. The purpose is front-loaded before the operational details. The parenthetical field list '(followers, externalUrl, businessAddress)' is slightly heavy but serves as a useful stand-in for a missing output schema, so it earns its keep.

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 tool with one required parameter and no output schema, the description compensates well: it covers input formats, output shape via the Channel Details alignment, cost, caching, and failure policy — a strong amount of context. The notable gap is sibling routing: among ~15 Instagram tools, an agent is not told when to choose this over instagram_details, instagram_channel_details, or instagram_profile_search, which is a real completeness risk in this large sibling set.

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

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

Schema description coverage is 100%, and each parameter is already well documented: userId lists all accepted formats and the 400 WRONG_ID_TYPE caveat, cache explains the default-false behavior, and cacheMaxAge enumerates allowed TTLs. The description adds only marginal value — the word 'free' for cache hits and a restatement of the default-fresh behavior — which matches the baseline 3 for high schema 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 opening phrase 'Instagram profile by user ID or @handle' names a clear resource and the accepted input modes, so an agent knows what this fetch does. The 'camelCase schema aligned with Channel Details' clause adds output-shape context that helps distinguish it from search-oriented siblings like instagram_profile_search. However, it never explicitly says why an agent would pick this over instagram_details or instagram_channel_details, so sibling differentiation is only 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?

The description gives operational guidance — 'Pass cache=true for a free 24h cache hit (default always fresh)' and 'Empty results and failures are never charged' — which helps an agent decide how to invoke it cost-effectively. But there is no explicit when-to-use versus the many overlapping Instagram siblings (instagram_details, instagram_channel_details, instagram_channel_posts), and no named alternatives or exclusions. Usage context is present but routing guidance is left 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?

With no annotations, the description carries the full transparency burden and does substantial work: it discloses cost ('Costs 1 credit'), the no-charge policy for empty/failed results, the default-fresh behavior versus the free 24h cache hit, and approximate/null-filled values in the output. It could additionally cover rate limits or auth requirements, but for a read-only stats endpoint this is well above the minimum.

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 compact: four short sentences, with the purpose front-loaded before operational details. Every sentence earns its place (purpose/output shape, cost, failure policy, caching). The first sentence is dense to the point of being slightly cryptic, but there is 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?

Given there is no output schema and no annotations, the description partially compensates by listing key output fields and operational behavior (cost, cache, failure charges). However, it leaves gaps: no explanation of what 'approx flags' or the full fixed key set means, no sibling differentiation among Instagram profile tools, and no error/rate-limit context. It is adequate but not 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 description coverage is 100%, so the baseline is 3 and the schema already handles url/cache/cacheMaxAge semantics. The description adds a small extra detail for cache ('free 24h cache hit (default always fresh)') beyond the schema, but contributes nothing for url or cacheMaxAge. No compensation beyond baseline is needed.

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

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

The description clearly identifies the resource (Instagram profile) and the delivered data type ('profile stats'), and adds concrete output detail ('fbid, bioLinks, isBusinessAccount, approx flags'). However, it uses no explicit verb ('fetch'/'get'), and the cryptic phrase 'fixed key set (null fillers)' muddies exactly what is returned. It also does not differentiate from the overlapping siblings instagram_basic_profile and instagram_details.

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 about when to choose this tool over instagram_basic_profile, instagram_details, or other Instagram siblings, which is a real gap given their overlapping scope. The operational notes about cost and caching are useful but are not tool-selection guidance. Usage is only implied: use it when you need Instagram profile stats.

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 no annotations provided, the description carries the full behavioral disclosure burden and does well: it states the profile must be public, explains credit cost per result, notes that empty results/failures are never charged, and clarifies cache behavior and default freshness. This goes beyond the schema's parameter-level descriptions and gives an agent realistic expectations for cost 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 only three sentences, front-loads the core function and key output fields, and then packs billing and cache behavior into the remaining sentences. Every sentence earns its place; there is no filler, redundancy, or unnecessary detail.

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

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

Given there is no output schema and no annotations, the description compensates well by naming important return fields, stating the public-profile requirement, and covering cost/failure/cache behavior. It also relies appropriately on the schema for parameter details like pagination and URL format. Minor gaps remain around the exact response envelope and how failures manifest, but the essential context for calling the tool 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 coverage is 100%, so the baseline is 3, and the description adds value on top by explaining cost implications (~6 credits, 0.3/result) and the free cache-hit benefit. This helps an agent reason about limit and cache parameter trade-offs. It does not redundantly restate the parameter descriptions, so it earns a point above 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 clearly states the tool returns 'Latest posts from a public Instagram profile' and highlights key response fields (carousel children[], mediaCount, user{}). It is specific enough about the endpoint's resource and output. However, it does not explicitly contrast with closely related siblings like instagram_channel_reels or instagram_tagged_posts, so it stops short of perfect differentiation.

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 conveys when the tool is appropriate by focusing on 'latest posts' and 'in one call', and it gives operational guidance about caching and billing. But it does not explicitly state when to use this tool versus alternatives or mention exclusion cases, such as 'use instagram_tagged_posts for tagged content'. Thus guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of disclosure, and it excels: it explains the credit cost formula (ceil(n×0.3), ~6 credits at default), pagination contract (nextCursor + hasMore), cache behavior (cache=true for free 24h hit, default fresh), and a no-charge policy for empty results and failures. This is far more transparent than typical tool descriptions.

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

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

The description is dense and informative, front-loading the core purpose. However, 'costs ~6 credits (0.3/result)' restates the earlier 'ceil(n×0.3) credits' formula, introducing slight redundancy. Still, every other clause earns its place, so it remains well-structured.

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 annotations and no output schema, the description provides a remarkably complete picture: cost, caching, pagination, resolve behavior, and failure charging. The only notable gap is the lack of any description of the returned reels data shape, which is partially mitigated by the mention of nextCursor and hasMore.

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

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

Schema description coverage is 100%, and each parameter (url, cache, limit, cursor, userId) is already well documented in the schema. The description adds some context around cost per result and the resolve-skip optimization, but these mostly reinforce the schema rather than add new semantic meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('Latest Reels') and a specific resource ('from a public Instagram profile'), making the tool's function immediately clear. It distinguishes this from sibling reels tools like instagram_trending_reels and instagram_reels_search by anchoring to a specific profile's channel.

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 context by saying 'from a public Instagram profile', but it never explicitly states when to choose this tool over alternatives like instagram_reels_search or instagram_channel_posts, nor does it mention exclusions or prerequisites beyond 'public'. The guidance is clear but not directly comparative.

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?

No annotations are supplied, so the description carries the full burden of behavioral disclosure. It discloses cost (~45 credits, 0.9/result), no charge on empty/failed results, cache behavior, and a specific failure mode (503 SESSION_UNAVAILABLE for a logged-out 2-row preview of a larger thread at 0 credits). This goes well beyond what the input schema or name alone convey.

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

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

The description is compact and front-loaded: the core resource appears first, followed by short, dense operational caveats. The phrase about the 'logged-out 2-row preview... 503 SESSION_UNAVAILABLE' is cryptic, but the overall text is efficient rather than 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 four-parameter, read-style endpoint with no output schema and no annotations, the description covers the main invocation concerns: session/error behavior, caching, cost, and pagination context. It does not describe the response shape, but the fully documented schema reduces that burden.

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

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

Schema description coverage is 100%, so the schema already documents url, cache, limit, and cursor, including defaults, minimums, and the nextCursor format. The description reinforces cache and billing behavior but does not add new meaning to any individual parameter beyond what the schema provides.

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

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

The description identifies the resource ('Instagram comments') and the pagination mode ('Session-paged'), and the schema's URL parameter clarifies that it operates on Instagram post/reel URLs. It does not open with an explicit verb phrase like 'Retrieves comments for...' and it does not differentiate against sibling tools, but the tool name plus schema make the operation 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 gives actionable call guidance: pass cache=true for a free 24h cache hit, default is always fresh, and empty/failed calls are not charged. It does not name alternative endpoints or explicit exclusions, but within the Instagram sibling set there is no direct comments alternative, so the context provided is sufficient.

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 no annotations provided, the description carries the full behavioral burden. It discloses the 1-credit cost, that empty results and failures are never charged, and the free 24h cache-hit behavior with fresh-by-default semantics. It does not mention auth, rate limits, or error formats, but for a simple read endpoint this is solidly transparent.

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 two sentences with no filler. It front-loads the action and returned data, then packs cost, failure policy, and cache behavior into the second sentence. 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 simple 2-parameter read tool with no output schema, the description compensates by listing the expected return fields and operational details like credits and caching. It is sufficient for an agent to call correctly, though it could go further by naming sibling alternatives for disambiguation.

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 schema already thoroughly documents both url and cache semantics. The description repeats the cache behavior but adds no new parameter-level meaning beyond what the schema provides, so the baseline of 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?

Description uses a specific verb and resource: 'Get an Instagram post, Reel or carousel' and lists concrete return fields (caption, likes, comments, views, media URLs, author, per-slide children). This clearly distinguishes it from sibling endpoints like instagram_basic_profile, instagram_channel_posts, or instagram_embed.

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 this tool by scoping it to posts, Reels, and carousels, and it gives useful cache usage guidance. However, it never explicitly names alternatives or states when to prefer a sibling tool such as instagram_comments or instagram_channel_posts, so usage context is implied rather than explicitly routed.

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 no annotations, the description carries full behavioral burden and does so well. It discloses the 1-credit cost, that empty/failed results are not charged, the 24-hour cache behavior, and that the default is always fresh. This is valuable operational context beyond what the schema states.

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 no fluff. The purpose comes first, followed by cost, failure policy, and caching behavior. 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 low-complexity tool with two simple parameters and no output schema, the description plus schema fully covers what the tool does, how to use it, what it returns, and its operational behavior around credits and caching. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so both url and cache are already well documented. The description reinforces the cache default and cost implications, but adds no new meaning about the parameters themselves 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 identifies a specific deliverable: a classic Instagram embed snippet using blockquote.instagram-media and embed.js, to be dropped into a page. This distinguishes it from the many Instagram data-fetching siblings like instagram_details or instagram_channel_posts.

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

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

It clearly conveys the use case: generate an HTML embed snippet for a page, with an optional cache=true path for free cached results. It doesn't explicitly compare against sibling alternatives, but no sibling serves the same embed purpose, so the context is clear without 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?

With no annotations, the description carries the full burden, and it does disclose genuinely useful traits: flat 2-credit cost, no charge on empty results or failures, and a cache toggle with a 24h window and fresh-by-default semantics. However, it omits return format, pagination, auth requirements, and rate limits, and 'native grid first, fallback path' is opaque about what data actually comes back.

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 short and mostly front-loaded, but 'Flat 2 credits. Costs 2 credits.' is a verbatim restatement of the same fact, and the telegraphic fragments ('Max 50.', 'default always fresh') trade clarity for brevity.

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 and no annotations, the description covers the cost/caching profile reasonably but says nothing about what a result contains or how results are shaped. It is adequate on billing behavior and thin on everything else.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description's 'Max 50' and cache line largely restate schema content, and mediaType is not addressed at all, so the baseline 3 applies.

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

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

The name is unambiguous, but the description itself opens with jargon ('Hashtag Explore: native grid first, fallback path only on miss') that describes implementation sourcing rather than what the tool returns. It never plainly states it searches Instagram posts by hashtag, and it does not distinguish itself from near-siblings like instagram_reels_search or instagram_tagged_posts.

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

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

There is no when-to-use guidance and no exclusions. The 'fallback path only on miss' line describes internal behavior, not a condition under which the agent should choose this tool over tiktok_search_by_hashtag or instagram_profile_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?

With no annotations, the description carries the disclosure burden and covers pricing (flat 1 credit), cache behavior (cache=true free 24h hit, default fresh), and the guarantee that empty results/failures aren't charged. It doesn't discuss rate limits or auth, but for a simple public read tool the key operational behavior is disclosed.

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-loads the core purpose before pricing/caching details. The only blemish is redundancy—'Flat 1 credit. Costs 1 credit.'—which keeps it from top marks.

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 low-complexity tool with fully documented schema, the description covers what the tool returns, cost, cache, and failure charging. It could be more complete by explicitly noting the relationship to instagram_highlights_details, but nothing essential is missing for an agent to call it correctly.

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

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

The schema already documents all three parameters at 100% coverage. The description adds value beyond the schema by explaining the cache parameter's effect and the default freshness behavior, which is directly actionable for invocation.

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 and returned fields (id, title, cover, owner) clearly, and 'for a public profile' sets scope. However it lacks an explicit verb and does not directly distinguish itself from the sibling instagram_highlights_details, 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 this is for retrieving a profile's highlight albums and gives clear context (public profile, cache behavior), but it never states when to choose this tool over the similar instagram_highlights_details or other Instagram tools. No exclusions or alternatives are mentioned.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does well by covering credit cost, the free 24h cache behavior, the default fresh-fetch behavior, and the policy that empty results and failures are not charged. It does not state read-only status or rate limits, but the read nature is clear from the described output.

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 the main purpose, but 'Flat 1 credit. Costs 1 credit.' is redundant repetition. The cache guidance also largely duplicates the schema, so not every phrase 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 two-parameter read operation with no output schema, the description is reasonably complete: it states the input source context via the schema, the returned fields, pricing, cache options, and failure/empty-result charging behavior. It could mention how to obtain the highlight id more directly, but the schema already references /v1/instagram/highlights.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description mostly restates the cache behavior already present in the schema, adding no significant new parameter semantics 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 identifies the resource: items inside one Instagram Story Highlight album, and names the returned data (media URLs, type, takenAt). The word 'one' distinguishes it from the sibling tool instagram_highlights, which lists highlight albums themselves.

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 is given about when to use this tool versus alternatives such as instagram_highlights. The cache parameter is explained, but tool-selection context is absent.

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 no annotations, the description carries the full burden and does disclose real behavioral traits: 1-credit cost, no charge on empty results or failures, and 24h cache-hit behavior. It omits auth/permission requirements and any rate-limit detail, but the billing and caching disclosures are genuinely useful 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?

Four tight clauses, front-loaded with the resolution purpose and followed by cost and cache notes; little waste. Minor redundancy: the cache sentence restates what the 'cache' schema property already says.

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 usefully previews the return payload (id, bio, links, stats) and covers cost and caching. For a simple 2-parameter read tool this is nearly sufficient; the only soft spot is the ambiguous default-freshness claim and no auth context.

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

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

Schema coverage is 100%, so the schema already documents 'q' normalization rules and the 'cache' flag, setting the baseline at 3. The description adds the cache-hit cost (0 credits) but its parenthetical '(default always fresh)' is confusing against the schema's 'Default true', muddying rather than clarifying the default behavior.

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 ('Resolve') and resource ('one public Instagram profile') and enumerates the returned fields (stable id, bio, links, stats). It also draws an explicit boundary with the parenthetical '(not niche discovery)', which separates it from hashtag/keyword discovery siblings. It stops short of naming or contrasting the closest siblings (instagram_basic_profile, instagram_details), so sibling differentiation is only partial.

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 '(not niche discovery)' note and the credit/cache economics imply when this cheap direct-resolution call is preferable, but no alternative tool is named and no when-not condition beyond 'not niche discovery' is stated. An agent must infer whether to use this versus instagram_basic_profile or instagram_details.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this well by revealing the credit cost (~28 credits, 1.4/result), the no-charge policy for empty/failed results, and the cache behavior (cache=true gives a free 24h hit). It does not mention rate limits or authentication, but the key operational traits are disclosed.

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 compact and front-loaded with the core value proposition; every sentence carries purpose or operational information. The only weakness is the cryptic 'rich music{}' notation, which is not as self-explanatory as the rest of the 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 compensates reasonably by naming expected response fields (isTrendingInClips, trendRank, rich music) and explaining cost and cache behavior. It does not fully define the shape or nesting of returned objects, but combined with a fully documented input schema it is adequate for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces cache semantics and billing per result, but those details are already present in the schema, and it adds no new parameter-level meaning beyond what the schema provides.

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 that the tool tells whether an Instagram sound is trending and returns reels using that sound, plus trend-related fields (isTrendingInClips, trendRank, rich music). The action is implied rather than expressed as a direct verb like 'fetch', but the resource and purpose are clear enough to distinguish it from generic reels search 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?

The opening question 'Is this Instagram sound trending?' implies the main use case, and the cost/cache details add useful decision context. However, it never explicitly says when to choose this tool over related siblings such as instagram_trending_reels, instagram_reels_search, or tiktok_music_posts, nor does it state any 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?

With no annotations, the description carries the full burden and does genuinely useful work: flat 2 credits, empty results and failures never charged, cache=true for a free 24h hit with default always-fresh, and an internal fallback path. It omits auth requirements, rate limits, and pagination/return behavior, but the cost and caching disclosure is strong and non-obvious.

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 text is short but poorly structured and partly redundant: 'Flat 2 credits. Costs 2 credits.' says the same thing twice, and the purpose is buried behind obscure implementation jargon instead of being 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?

For a 4-parameter, fully documented search tool with no output schema and no annotations, the pricing/caching context is covered but the description stops short of what the tool returns, auth needs, or how it differs from the many overlapping Instagram reel/tag siblings.

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

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

Schema coverage is 100%, so the schema already documents q, cache, limit (default 20, max 50) and datePosted with a full enum. The description restates 'Max 50' and the cache semantics but adds no syntax or format detail beyond the schema, 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?

The description never states the verb+resource (e.g. 'search Instagram reels matching a hashtag'); it opens with implementation detail ('Native tag feed first, slower fallback paths on a miss') and then pivots entirely to pricing. An agent must infer the tool's function from the name alone, and nothing distinguishes it from siblings like instagram_hashtag_search, instagram_tagged_posts, or instagram_trending_reels.

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 guidance and no alternatives named. 'Native tag feed first, slower fallback paths on a miss' is internal execution detail, not agent-facing selection criteria, and it does not help choose between this tool and instagram_hashtag_search or instagram_reels_by_audio_id.

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