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 provided, the description carries the full burden and excels: it discloses the credit cost, guarantees free empty/failure results, and explains the caching behavior (free 24h cache hit, default always fresh). This exceeds what the schema alone conveys.

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 sentences, zero fluff. The key identifying phrase 'Third-party seller storefronts' is front-loaded, and each subsequent sentence adds a distinct, useful fact (what's extracted, what's excluded, cost, caching). Perfect efficiency.

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 straightforward fetch tool with 5 well-documented params and no output schema, the description covers the essentials: purpose, exclusions, pricing, and caching. It omits response structure and rate limits, but the last sentence's cost/caching note plus the schema's full param docs make it adequately complete for an agent.

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% — every parameter (url, cache, limit, cursor, marketplace) has a descriptive schema entry. The description text adds no parameter-specific details beyond the schema, which is the expected baseline when schema is thorough.

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 'Third-party seller storefronts' and itemizes the URL patterns (/sp?seller= / /s?me=) plus content (ASIN + canonical /dp URLs, price, badges). It explicitly excludes influencer /shop/{handle} pages, cleanly distinguishing this tool's scope.

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

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

Provides clear when-not-to-use guidance ('Not influencer /shop/{handle}') and practical usage details about cost (1 credit) and caching (cache=true for free 24h hit). It doesn't name an alternative tool explicitly, but the exclusion is specific and actionable.

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?

Even without annotations, the description transparently discloses cost implications (1 credit/URL, no charge for empty results/failures) and caching options (cache=true for free 24h hit). It also hints at the return structure ('each row is the analytics/post object'). No contradictions with annotations (none provided).

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 concise and packed with essential information: purpose, cost, caching, and failure behavior. Every sentence contributes value, and the structure is clear and well-organized.

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 two parameters and no output schema, the description is sufficiently complete. It explains the return format (rows of analytics/post objects) and covers practical aspects like cost and caching. It could be slightly more detailed on exact response fields, but overall it meets the needs.

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 describes both parameters (urls and cache) with full coverage. The description adds meaningful context about cost per URL and cache semantics, which are not fully captured in the schema, thus enhancing parameter understanding.

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 primary function: comparing unified metrics across up to 10 URLs, with each row representing an analytics/post object. It distinguishes itself from single-post tools like analytics_post by focusing on multi-URL comparison.

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

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

The description provides usage context by explaining credit costs per URL and caching behavior. It implies a multi-URL scenario but does not explicitly contrast with alternatives like analytics_post; however, the cost and caching details offer practical guidance for when to use the tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful non-obvious behaviors: 1 credit cost, no charge for empty results/failures, and cache behavior with free 24h hits vs fresh default. It does not mention response format or rate limits, but the cost and failure/caching disclosures are substantial and go 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 short, front-loaded with the main purpose, and covers important operational details. It loses a point for slight redundancy: '(1 credit)' is immediately followed by 'Costs 1 credit', which is the same information stated twice.

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, the description covers the essential context: what it does, platform scope, cost, caching, and failure charging policy. It could mention what metrics are returned, but the schema and tool name make that reasonably inferable.

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 provides 100% coverage of both parameters, including detailed descriptions of URL scope and cache behavior. The description adds some cost context and reiterates caching, but it does not significantly enhance parameter understanding beyond what the schema already states.

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: 'Unified metrics for one post, video, or reel' with platform auto-detection. This distinguishes it from the many single-platform detail tools in the sibling list, which is a strong differentiation signal.

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 main description implies cross-platform use via 'platform auto-detected', and the URL parameter schema explicitly states 'cross-platform URLs are expected here (unlike single-platform endpoints)' and lists excluded platforms. This gives clear usage context and alternatives, though not a dedicated when-to-use/when-not-to-use section.

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 disclosure burden and does so well: it reveals credit cost (1 credit), cache behavior (24h cache, free hits, default fresh), and failure charging policy. It also describes what the response includes. Minor gaps remain around auth/rate limits, but this is solid coverage.

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, failure policy, and cache tip. It is slightly redundant with '1 credit' appearing twice, but every sentence earns its place and no irrelevant details are included.

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 absence of an output schema and annotations, the description adequately explains return contents, cost, caching, and failure charging. It lacks explicit mention of response envelope details or error cases beyond 'failures are never charged', but it is sufficient for a post-thread detail tool.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (url, cache, depth). The description adds no parameter-level meaning beyond what the schema already states, so it stays at the baseline 3.

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

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

The description clearly states the tool retrieves a Bluesky post thread via getPostThread, and enumerates specific return content (nested replies, facet links/mentions/hashtags, rich author). This distinguishes it from Bluesky siblings like profile or user-posts tools and from other platforms' post-details 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 provides useful cost and caching guidance ('Pass cache=true for a free 24h cache hit', 'Empty results and failures are never charged'), but it does not explicitly state when to choose this tool over alternatives like bluesky_user_posts or twitter_tweet_details. Usage context is implied rather than contrasted.

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 transparently states the credit cost, that failures/empty results are not charged, and explains the caching behavior (cache=true for 24h free hit, default fresh). It also notes the envelope includes cached fields on cache hits. This is solid disclosure for a read operation, though it doesn't discuss rate limits or error 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 extremely concise—two sentences that front-load the core purpose and then cover cost and caching. Every sentence is informative, with no filler. The structure is clear and easy to parse.

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

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

Given there is no output schema, the description compensates by listing the data fields returned. It also addresses cost, caching, and failure charges, which are essential for an agent deciding to invoke this tool. It does not mention rate limits or pagination, but these may not be relevant for a profile fetch. Overall, it provides sufficient context for a straightforward retrieval tool.

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

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

The input schema already provides detailed descriptions for all three parameters (url with platform-matching guidance, cache with default and cacheMaxAge with accepted values). The tool description adds the 'free 24h cache hit' detail and cost per call, which is useful but not directly about parameter meaning. Since schema coverage is 100%, the description adds only marginal value beyond the schema.

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

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

The description clearly states the tool fetches a Bluesky profile and lists the specific data fields (handle, did, bio, counts, banner, verification, labels, associated). This distinguishes it from sibling tools like bluesky_post_details or bluesky_user_posts, 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 explains the cost model, caching options, and failure handling, giving clear guidance on how to use the tool. However, it does not explicitly state when to prefer this tool over alternative profile tools for other platforms, though the tool name makes the platform obvious. No exclusions or alternative tool suggestions 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?

No annotations are provided, so the description carries the transparency burden. It discloses meaningful behavioral details: approximate cost (0.1/result), no charge on empty/failure, cache behavior and default freshness, repost marking, and embed categories. It does not mention authentication or return envelope details, but for a read-only feed tool the disclosed behavior is enough for selection and invocation.

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 sentence adds information: what is returned, how results are marked, costs, failure pricing, and caching behavior. There is no filler or unnecessary restatement of the tool name.

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

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

Given six parameters, no output schema, and no annotations, the description covers enough of the practical invocation context: pagination (opaque cursor), repost filtering semantics, embedded content types, billing behavior, and cache strategy. A fully explicit output shape would be better without an output schema, but the current description still provides substantial 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?

The input schema has 100% parameter description coverage, and each parameter already explains its behavior, constraints, and default. The prose adds little parameter-level semantics beyond reinforcing the cache behavior and repost/embed context, so the schema carries the weight and the description meets 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?

“Author feed — posts and reposts (isRepost marked), quote/external/images embeds” clearly identifies that the tool returns a Bluesky user’s feed with reposts and embeds. It is distinct from bluesky_profile and bluesky_post_details in practice, but the description does not explicitly name those alternatives, so differentiation is inferential rather than explicit.

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

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

The description gives operational guidance: pass cache=true for free 24h cache hits, and empty results/failures are never charged. However, it does not explicitly state when to choose this tool over sibling tools, nor does it give when-not-to-use guidance. The intended use case is implied by “author feed” but not stated as a clear 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?

No annotations provided, so description carries full burden. It discloses credit cost (flat 2, free cache hit), behavior on empty results/failures (never charged), and that delivery breakdowns depend on Meta publishing them. This is good transparency for a read-only lookup tool.

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

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

Front-loaded purpose, two clear sentences. Minor redundancy: credit cost stated twice.

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?

Single-item lookup with no output schema; description covers data returned (delivery breakdowns), cost behavior, cache behavior, and failure handling. Missing explicit mention of rate limits or auth, but adequate for the tool.

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

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

Schema already describes url params well (format, platform constraint). Description adds value by explaining cache=true behavior (free, 24h) and default always fresh. Slight redundancy with credit cost mention.

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 'One Meta ad by ID', clearly stating the tool fetches a single ad by identifier, distinct from search tools. It adds 'same creative as search — plus delivery breakdowns when Meta publishes them', which differentiates it from sibling search tools like facebook_ad_library_search. The verb+resource is specific and 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?

The description implies use case: retrieve a single ad by ID and get delivery breakdowns, which differentiates from search. It gives explicit guidance on cache usage ('Pass cache=true for a free 24h cache hit') and notes the flat credit cost. It doesn't explicitly say

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 transparency burden; it discloses the 2-credit cost, free cache hits, no charge for empty/failed calls, and Meta's lack of audio exposure. It does not cover auth, rate limits, or error/response details, but it is substantially transparent for a simple 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?

Three compact sentences front-load the purpose, then add cost and cache guidance. Every clause earns its place, and there is no redundant filler beyond the schema restatement.

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 read tool with no output schema, the description plus schema fully explains what is returned, what is not returned, cost, caching behavior, empty-result/failure policy, and URL platform constraints. No critical missing context remains.

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?

Input schema coverage is 100%, and both the url and cache parameters are already described thoroughly in the schema. The top-level description reinforces the same semantics (written copy fields and cache behavior) and adds billing context, but it does not add new parameter-level meaning 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 begins with the concrete deliverable ('Written creative copy from a Meta ad — headline, body, CTA, landing URL') and immediately corrects a likely misunderstanding ('Not a speech transcript'). This clearly distinguishes it from transcript tools and from ad-details siblings by naming the specific fields returned.

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 decision context: you request written ad copy, not a speech transcript, and you should pass cache=true for a free cached response. It also conveys billing behavior (2 credits, failures not charged) that helps an agent decide when to retry or cache. It names no explicit alternative sibling, so it stops short of a 5.

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

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

Mentions cost, caching, and that empty results/failures are not charged, which adds transparency about side effects. However, it does not disclose output format or any potential data limits beyond the cache parameter, leaving gaps.

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 brief and to the point, containing only essential cost and caching details without unnecessary fluff. It is well-structured for its limited scope.

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, the description does not cover what the response will contain or how to interpret results. It lacks contextual information about expected data structure, making it incomplete for full understanding.

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

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

The description adds little to the parameter meanings already provided in the schema. It only hints at cache behavior, but the schema already explains each parameter clearly, so the description contributes minimal additional value.

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 focuses on cost and caching rather than explicitly stating the tool's function. 'Company Ads' implies retrieval of company ads, but it lacks a clear verb like 'fetch' or 'retrieve', making the purpose ambiguous.

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

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

Provides guidance on cache usage (pass cache=true for free hit) but fails to mention when to use this tool versus sibling tools. Does not clarify use cases like retrieving all ads from a specific company or distinguishing from ad search tools.

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

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

No annotations are present, so the description carries the full burden for behavioral disclosure. It usefully reveals billing semantics (2 credits, empty/failure not charged) and cache behavior (cache=true free 24h hit, default fresh), which goes beyond the basic search description. However, it does not explicitly state read-only status, auth requirements, or rate limits, and it only hints at return-field availability (spend/impressions), leaving safety/completeness gaps.

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 that front-load the purpose and pack billing/cache details with no filler. Every sentence carries distinct information, earning 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?

The description covers the core behavior, filters, and billing/cache edge cases, which is substantial for a 14-parameter tool. The lack of an output schema means the return format (e.g., ad fields, pagination) is only partially implied via 'spend/impressions when Meta publishes them,' but the schema's rich parameter descriptions compensate. It is not missing any obvious non-parameter behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description maps prose terms (active/inactive, media type, date range, platforms, cursor) to parameters but adds little semantic depth beyond the schema's own descriptions. The `cache` behavior is reinforced but 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 opens with a specific verb and resource: 'Search Meta Ad Library by keyword', then enumerates key filters (active/inactive, media type, date range, platforms, cursor). It clearly targets the ad-search function but does not explicitly distinguish itself from sibling `facebook_ad_library_search_companies`, so it misses the 5-level bar for sibling 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?

No explicit when-to-use, exclusions, or alternatives are provided. The description notes cost and cache behavior but not for which scenarios to prefer this over `facebook_ad_library_search_companies` or `facebook_ad_library_company_ads`. This is effectively no 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 it does well: it discloses the 2-credit cost, that empty results and failures are not charged, and the 24h cache behavior. Also, the 'name-matched' comment clarifies how results are filtered. It does not mention rate limits, auth, or error structures, but the core operational behavior is 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 three tight sentences with no redundancy. It front-loads the most identifying action and resource, then adds distinguishing details, and ends with cost/cache context. 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 search tool with a fully self-documenting schema, the description adds key operational context including pricing, caching, and matching behavior. There is no output schema, but the description's mention of pageId and the schema's cache envelope details provide enough completeness. Minor gaps remain around explicit return structure, but overall it's adequate 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?

The schema provides 100% coverage of all four parameters, including detailed explanations for q, cache, limit, and country, so the baseline is 3. The description adds minimal parameter meaning beyond the schema—mostly restating cache behavior and introducing the pageId/pageId concept, which is more about output than input 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 opens with 'Find Meta Ad Library pages by brand,' clearly specifying the verb and resource. The phrase 'name-matched, pageId for company-ads (not profileId)' adds a precise scope that distinguishes it from sibling tools like facebook_ad_library_search and facebook_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 explains this is for brand/company searches and explicitly contrasts 'pageId for company-ads' with 'profileId,' giving the agent a strong cue about when to choose this tool. It also documents cost and cache behavior, providing practical usage context. It stops short of naming exact alternative tools or explicit exclusion criteria, hence not a 5.

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

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

With no annotations provided, the description must disclose behavior. It does mention the 2-credit cost, empty-result-no-charge policy, and cache=true behavior — useful operational transparency. But it omits crucial behavioral details like return format, error handling, pagination, and any rate limits. For a data-fetching endpoint in a social-media scraper API, knowing what the response contains (reply objects, author info, timestamps) is essential, yet absent.

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 (two sentences) but front-loads a fragment rather than a purpose statement. The cost/cache information is useful but arguably belongs in a usage note, not as the opening content. It is concise, but the space is allocated to billing details instead of core function—structurally acceptable but not optimally 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?

The tool has no output schema and sparse annotations, so the description should explain what is returned and what failure states look like. It omits any mention of the response format (e.g., list of reply objects, fields), pagination, and error behavior beyond 'failures are never charged.' For a data-fetching tool, this is a significant gap that leaves an agent guessing at return structure.

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

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

Schema covers 100% of parameters with clear descriptions typ. The description adds value for the 'cache' parameter (explicit free 24h hit wording) and the flat credit cost, but does not enrich other parameters beyond what the schema already provides. Given full schema coverage, baseline 3 is appropriate; no deduction or bonus is clearly warranted.

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 what the tool does. It opens with a noun phrase 'Comment Replies' and immediately pivots to costs/caching. The actual function (fetching replies to a comment) must be inferred from the tool name and parameter schema. A clear verb+object statement like 'Fetch replies to a Facebook comment' is absent, leaving purpose ambiguous for an agent without schema cross-referencing.

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 schema provides some contextual guidance: the url parameter explicitly warns against cross-platform URLs, and commentId is described as 'from the comments endpoint,' which hints at a workflow chain. However, the description itself offers zero usage context—no mention of when to prefer this over facebook_comments, pagination behavior, or typical call patterns. The cost/cache notes are operational, not usage-oriented.

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. It discloses cost (2 credits), caching behavior (cache=true for free 24h hit), and that empty results/failures are never charged. It also hints at conditional fields (reactions.like when mixed) which goes beyond typical schema info. This adds meaningful behavioral context.

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

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

The description is two concise sentences, front-loaded with the core purpose and return fields, then pricing and caching notes. Every sentence earns its place with no filler.

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

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

Given there is no output schema, the description compensates by listing key fields. It covers cost, caching, and failure charging. It could mention pagination or limit behavior in more detail, but the schema covers limit. Overall, it's sufficiently complete for a simple fetch operation.

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 parameters are already well-documented. The description adds a minor note about cache behavior and feedbackId origin, but these are largely redundant with the schema. It does not significantly enhance understanding beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool fetches Facebook post comments and lists specific return fields (reactionCount, reactions.like, author.id, replyCount). It distinguishes from siblings like facebook_comment_replies by specifying it's for post comments, not replies. This is specific and 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?

The description provides usage context (cost, caching, failure policy) but does not explicitly differentiate when to use this tool versus alternatives such as facebook_comment_replies or other comment-related tools. It lacks clear when/not-to-use guidance, though the scope is implied by 'Facebook post comments' which partially helps.

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 several behavioral traits: the operation costs 2 credits, empty results and failures are never charged, cache behavior is explained, and field availability depends on Facebook exposure. It doesn't mention rate limits or error codes, but for a simple fetch tool, this is above-average 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?

Three sentences cover content, cost, and caching with zero fluff. Each clause adds value: the field list is compact, the credit cost is stated, and the cache behavior is explained in one crisp sentence. Excellent front-loading of the core purpose.

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

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

For a tool with only 2 params, no output schema, and no nested objects, the description covers all essential context: what it returns (caption, engagement, etc.), cost, failure behavior, and caching. It even preempts questions about missing data with 'when Facebook exposes them.' This is complete for its complexity level.

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% for both parameters (url and cache), and the description reinforces the cache behavior but doesn't add new parameter-level semantics beyond what's in the schema. The baseline of 3 applies because the schema already does the heavy lifting, and the description doesn't clarify any ambiguity or add format details not already present.

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 tool as retrieving Facebook post or Reel details, enumerating specific fields (caption, engagement, author id, video playback, music) and caveat 'when Facebook exposes them.' This distinguishes it from sibling tools like facebook_page_details and facebook_profile_posts, and the verb is implied but 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?

While it doesn't name alternative tools, it provides strong usage context for cost (2 credits) and cache behavior, explicitly instructing when to pass cache=true for free cache hits (default always fresh). This gives clear when-to-use guidance for the cache parameter, but lacks explicit when-not-to-use or alternative tool references.

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 and does well: it discloses the 2-credit cost, states that empty results and failures are never charged, and explains the default fresh-fetch versus 24h cached behavior. This adds meaningful behavioral context beyond the schema, though it does not cover error responses 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 compact and well-structured: one sentence establishes the tool's purpose and return fields, and the second covers costs and cache behavior. Every clause earns its place, and key operational details are front-loaded after the core purpose.

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

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

Given no output schema, the description appropriately lists the returned fields and caveats ('attendance when exposed'). It also covers cost, failure charging, and caching, which is sufficient for a simple single-URL details tool. It could mention failure behavior or response envelope more explicitly, but overall it is largely 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 the baseline is 3, but the description adds value beyond the schema by explaining the cost implications of cache=true ('free 24h cache hit'), the default always-fresh behavior, and that cached hits include 'cached + cachedAt'. This enriches the semantics of the cache parameter beyond its schema description.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Get a Facebook event' and enumerates the returned fields (title, local start/end, timezone, place, host id, attendance). It is distinct from the sibling search tool in intent, but it does not explicitly name or contrast siblings, so it stops short of full 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 provides useful invocation guidance about credits and cache behavior ('Pass cache=true for a free 24h cache hit'), but it does not explicitly state when to use this tool versus alternatives like facebook_event_search or facebook_details. Usage context is implied rather than directly addressed.

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 burden. It clearly discloses credit cost (2 credits), the free cache behavior (cache=true for 24h hits), and the guarantee that empty results and failures are never charged. It also hints at potential past events without 'from', which is a useful behavioral quirk.

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, front-loaded with the core purpose, then quickly covers credits and cache. It is concise and to the point, though some repetition of '2 credits' could be tightened. Slightly repetitive but not verbose.

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 tool has 7 parameters, no output schema, and no annotations, the description does a good job of covering the most critical behavioral aspects: credit cost, cache, and date handling. It lacks some details like pagination or error response behavior, but the high schema coverage fills in parameter details. The integration of credit and cache into the description is complete enough for most use cases.

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

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

The schema has 100% coverage with detailed parameter descriptions (e.g., 'q' pairs with location, 'to' is inclusive, 'from' for upcoming-only windows, 'cache' default behavior, 'limit' default/max, 'location' matching logic, 'upcoming' setting from to today). The description reinforces the most important parameters (q, cache, from) and adds credit context, but most semantic value still comes from the schema. Given the high coverage, a 4 is appropriate for adding the credit note and cache help.

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: searching Facebook events by topic and city, with specific mention of date/timezone/venue. It distinguishes from sibling tools (e.g., facebook_event_details for a single event) by focusing on search across 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 provides usage context: pairing 'q' with 'location', and clarifying when to use 'from' vs 'upcoming' for date filtering. It doesn't explicitly name alternatives (like facebook_event_details for specifics), but the sibling list suggests a search tool is distinct enough. The lack of explicit 'when not to use' keeps it from a 5.

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

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

With no annotations present, the description carries the full behavioral-transparency burden, and it does a solid job: it discloses the 2-credit cost, the free 24-hour cache behavior, that empty results/failures are not charged, and mentions response-relevant fields like listingHits/hydrateFailures/hydrateSkipped. It does not cover rate limits or authentication nuances, but it goes well beyond a minimally viable 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?

The description is compact and packs the pricing, cache behavior, and high-level response expectations into roughly three sentences. It is front-loaded with the core resource and then tacks on valuable usage caveats. The internal field names like "*IsApproximate" are telegraphic but not excessively verbose.

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 that there is no output schema, the description provides useful hints about response metadata and return-field names, but it does not fully defined the output structure. The main description combined with the rich input schema is enough for basic selection and invocation, but the agent must still infer the exact return shape from the listingHits/hydrateFailure hints.

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 thorough descriptions for every parameter, including URL constraints, cache-true behavior, limit bounds, and sortBy values. Because the schema coverage is 100%, the description adds only marginal extra semantics. The main text mentions sortBy and cache, but does not substantially improve on the parameter documentation 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 points to public Facebook group posts as the target resource, and the phrase "Public Facebook group posts" conveys a fetch/list intent even though it lacks an explicit verb. It also distinguishes itself from related tools like facebook_profile_posts by specifying "group posts" and "public" scope. However, it fails to state a direct verb such as "fetches" or "lists", leaving the purpose slightly 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 implies usage through "Public Facebook group posts" and provides useful behavioral guidance around cache=true and cost. It does not explicitly tell the agent when to choose this tool over page/profile-focused Facebook tools or name any alternatives. The schema-level cross-platform warning indicates what not to pass, but the main description does not enumerate when to use this tool.

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

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

With no annotations, the description carries the transparency burden. It clearly discloses the 2-credit cost, that empty results and failures are never charged, and explains cache/always-fresh behavior. It does not mention authentication or rate limits, but the provided behavioral details are substantive and positive.

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 resource type and key fields. It includes a minor redundancy: 'coords (2 credits)' is immediately followed by 'Costs 2 credits', which slightly repeats the cost 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 provides useful context: listing fields, pricing, failure/cache behavior, and cache usage. It could be more explicit about the expected response envelope, but the provided context is adequate for selecting and invoking the tool.

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

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

The input schema already documents both parameters fully, reaching 100% description coverage. The description reinforces the cache behavior and credit cost, but it does not add much semantic value beyond the schema's existing parameter 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 identifies a specific Facebook Marketplace listing resource and enumerates key fields (title, priceAmount, status, seller, condition, coords), making the tool's purpose reasonably clear. It lacks an explicit verb like 'get' or 'fetch', and it does not explicitly contrast itself with sibling marketplace 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 description does not explicitly say when to use this tool instead of facebook_marketplace_search or facebook_marketplace_location_search. The URL parameter and 'Marketplace listing' wording imply specific item-detail lookups, but explicit alternatives or exclusions are 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?

No annotations are provided, so the description must reveal behavior. It clearly explains credit costs (flat 2 credits), that empty results/failures are free, and that cache=true gives free hits. It also mentions 'default always fresh' and cache hit details. This is strong transparency for a paid API tool, covering costs and caching 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 extremely concise (two sentences) yet covers purpose, cost, caching, and usage hints. No redundant information; every sentence adds value. The phrase 'Flat 2 credits' is repeated, but that's a minor redundancy; overall it's well-structured and 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?

Given the tool's moderate complexity (3 params, no output schema, no annotations), the description is quite complete. It covers the return type (id + lat/lng), user guidance for disambiguation, cost model, and caching behavior. It might benefit from mentioning pagination or response envelope details, but the schema already covers limit and cache. Overall, it's sufficient for an agent to use confidently.

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 parameter descriptions, but the description adds value by clarifying caching behavior and credit costs beyond the schema. It also reinforces the 'q' parameter semantics with examples of ambiguity and resolution. Since the schema already covers parameter details, the description complements it well.

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: disambiguate city names into Marketplace hubs with id and lat/lng. It distinguishes itself from siblings like facebook_marketplace_search and facebook_marketplace_item by specifying it's for location/hub resolution, not listings or item 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 implicitly indicates when to use this tool: when you need to resolve a city name to a hub ID for Marketplace. It provides usage hints like including state for single hits, but doesn't explicitly mention when not to use it or explicitly name alternatives. However, the differentiation from siblings is clear enough.

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 for behavioral disclosure. It clearly explains credit costs (2 credits, details=true adds 2 per listing), caching behavior (24h cache, cache=true for free), and that empty results/failures are not charged. It mentions opaque cursor and does not contradict any annotations (since none exist). It could add more detail on error handling or rate limits, but for a search tool this is sufficient.

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 concise and front-loaded with the core purpose, then adds critical operational details (credits, caching). It uses clear, direct language with no fluff. However, it repeats some information found in the schema (like details=true billing) which could be trimmed, but overall it 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 complex tool with 15 parameters and no output schema, the description is quite complete: it explains credit costs, caching, pagination cursor, and the distinction between flat and per-listing billing. It gives practical usage tips like using local_pickup for nearby-only, which is in the schema but also highlighted in the description. It could mention the response envelope structure (like cachedAt) but that is in the schema. Overall, it covers the essential operational 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 each parameter thoroughly. The description adds some value by summarizing key behaviors like caching and credit costs, but it does not add much beyond the schema for individual parameters. It mentions 'filters' broadly, but the schema already has detailed descriptions for each filter. Baseline 3 is appropriate because the schema is comprehensive, but the description doesn't enrich parameter meaning further.

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 searches Marketplace by keyword and city, and mentions filters, pagination, and credit costs. It distinguishes from sibling 'facebook_marketplace_item' (which likely fetches a single item) and 'facebook_marketplace_location_search' (which likely searches by location only), making the purpose specific and non-overlapping.

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 explicitly states when to use it ('Search Marketplace by keyword + city'), and the context of credit costs and caching (cache=true for free hits) provides clear guidance on when to use the cache. It implicitly differentiates from siblings like location_search by emphasizing keyword plus city, though it doesn't explicitly name alternatives, but the examples in the schema clarify usage scenarios.

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 of behavioral disclosure. It reveals credit cost (2 credits), that failures/empty results are free, and the default cache behavior with an option to cache. However, it does not disclose rate limits, error handling, or whether any special access is needed. This is useful but not exhaustive.

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 concise: two sentences front-load the purpose, then quickly cover cost and caching. Every word earns its place, with no filler or redundant explanation. The structure is ideal for quick scanning.

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

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

Given there is no output schema, the description must convey what is returned. It lists the specific fields (likes vs followers, talkingAbout, category, website, email) and mentions cost/caching but does not mention if additional standard profile data (e.g., name, followers count) is included. It is reasonably complete for a profile tool, but could be slightly more explicit about the full response envelope.

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% coverage for both parameters, including examples for url and a detailed explanation of cache behavior. The description adds no new parameter semantics; it merely restates the cache option and adds cost context. With schema coverage this high, 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 description clearly states the tool fetches a Facebook page profile and enumerates specific data fields: likes vs followers (distinct), talkingAbout, category, website, and public email. This explicitly defines the scope and differentiates it from sibling tools like facebook_profile_posts or facebook_comments. Even though facebook_details exists, this description pinpoints its unique output.

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

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

Provides context about credit cost and caching, but does not explicitly state when to use this tool versus alternatives. No mention of exclusions like 'use this for page profiles, not for posts' or comparisons to similar tools. The purpose is clear enough to infer use, but explicit guidance 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?

No annotations are provided, so the description carries the burden. It discloses pricing (2 credits), no charge for empty/failed results, cache behavior (24h cache, free hit with cache=true), and return fields. Missing details like pagination or authentication, but core behaviors are 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?

Two sentences with clear structure and front-loaded purpose. However, '2 credits. Costs 2 credits.' is redundant, and 'default always fresh' repeats the schema's cache description, so there is minor 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?

The tool is simple, all three parameters are well-documented, and the description covers pricing, caching, and key return fields. It does not specify whether events are upcoming or past, but overall it is sufficient for most use cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter meaning beyond what is already in the schema; it only restates the cache behavior in a shorter form.

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 clearly states 'List a Facebook Page's events' with specific data fields (local startDate, timezone, venue), making its purpose unambiguous and distinguishing it from sibling tools like facebook_profile_posts or facebook_event_search.

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

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

The description implies usage (when you need events for a Facebook Page) but provides no explicit when-to-use vs alternatives, such as facebook_event_details or facebook_event_search. No comparisons or exclusions 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, the description carries full burden. It discloses non-obvious behaviors: the credit cost (2 credits), that empty results and failures are never charged, and the cache behavior (cache=true for 24h free hit). It also clarifies that accessibilityCaption is alt-text, not a post caption, preventing misinterpretation. This goes well beyond the schema and provides essential operational context.

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

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

The description is three sentences, front-loaded with the core purpose. The first sentence states what it does and what it returns. The second covers cost and reliability. The third explains cache behavior and the default. No wasted words, and each sentence adds essential information without redundancy.

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 tool has 3 parameters and no output schema, the description covers all necessary context: purpose, data fields, cost, failure handling, cache behavior, and parameter nuances. It explains the limit's practical effect and the meaning of accessibilityCaption. There is no missing critical information that would prevent correct usage.

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

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

The description adds significant meaning beyond the schema. It explains the 'limit' parameter behavior with the insight that the public grid is a single SSR batch typically ~8, so retrievableCount is that batch, not a promise to fill limit. It also clarifies the economics of 'cache' and 'costs 2 credits'. Even though schema coverage is 100%, the description provides crucial nuances and prevents misuse of the limit 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 clearly states this is a 'Photo grid from a Facebook Page' with specific data returned (full image URL plus accessibilityCaption). It distinguishes from sibling tools like facebook_page_details or facebook_profile_posts by focusing on photos. The verb 'return' is implied through 'full image URL plus accessibilityCaption', making the purpose 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?

The description implies when to use (for fetching a page's photo grid) but does not explicitly name alternative tools or state when not to use it. It gives clear context by mentioning the data type and credit cost, but does not provide exclusions like 'use facebook_details for page metadata instead.' Lacks explicit 'when-not' guidance, so not a 5.

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

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

With no annotations present, the description carries the full transparency burden and delivers substantial detail: credits, caching, failure/empty charging, execution timeout, and truncation behavior. The 'listingHits / timings.phase' fragment is cryptic and somewhat unexplained, but overall the operational behavior is disclosed unusually well.

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, but it includes the unexplained internal fragment 'listingHits / timings.phase' and merely redundant statements: 'failures 0 credits' and 'Empty results and failures are never charged' convey almost the same point. This prevents it from becoming a truly well-structured, polished 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?

Given the tool's moderate complexity and lack of an output schema, the description mentions the nature of the result (posts and Reels) and covers crucial constraints like timeout, limits, and caching. It does not provide a proper response envelope, but the operational detail largely compensates for the missing 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 coverage is 100% and the schema already contains generous descriptions for url, cache, and limit. The description duplicates some of this information without adding new parameter-level meaning, 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 opening phrase 'Latest posts and Reels from a Facebook page' clearly defines what the tool returns and its social platform. It is specific enough to be distinguished from sibling fetchers like facebook_profile_photos and facebook_group_posts, even though it lacks an explicit verb like '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 provides concrete operational guidance: cache behavior, credit costs, empty/failure charging rules, and a 60-second deadline. However, it does not explicitly say when to prefer this tool over sibling Facebook fetchers, nor does it mention exclusions, leaving usage timing mostly inferred.

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

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

With no annotations, the description fully discloses key behaviors: ordering, filtering ('no archive padding'), cost, failure handling, and caching semantics. It mentions the limit parameter's range implicitly via schema. It doesn't cover authentication or rate limits, but for a read-only list tool with clear credit rules, it is quite 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, front-loaded with the primary function, then cost and caching details. Every sentence adds value, with no redundancy or filler.

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

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

For a simple list endpoint with 3 parameters and no output schema, the description covers the return content (metrics), ordering, cost, failure handling, and caching. It doesn't explicitly mention the response envelope structure, but the metrics list implies the data shape. It is complete enough for an agent to decide when to call it.

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 well-documented. The description adds the credit cost per call and the default freshness, but these are call-level behaviors, not param meanings. It does not add new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Latest Facebook page Reels' with specific metrics (views, likes, comments, shares) and ordering ('newest-first without archive padding'). It is distinct from siblings like facebook_profile_posts and facebook_profile_photos by focusing on Reels content type.

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

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

Provides clear usage context including credit cost (2 credits), no charge on empty/failed results, and cache behavior (24h cache true vs fresh default). While it doesn't explicitly list alternative tools, the purpose clarity makes the appropriate use case obvious. It lacks explicit when-not-to-use guidance, but the context 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?

The description discloses meaningful operational behaviors: the 4-credit cost, free cache hits with cache=true, and no charges on empty/failed results. However, with no annotations, it leaves out core behavioral details such as the nature of the operation (read-only), the format of the returned summary, and any rate limits or error handling beyond vague 'failures'.

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 brief but inefficient: 'Summarizer' as an opener adds no value, and the cost/cache information precedes any statement of function. The ordering is not front-loaded with the purpose, making it poorly structured despite its short length.

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 absence of an output schema places the burden on the description to explain what the tool returns, but it does not mention the summary output at all. It also doesn't cover edge cases like invalid URLs or authentication requirements, making it incomplete for a tool in a suite of many summarizers.

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 provides full descriptions for both parameters, including the platform-matching restriction for url and the caching semantics for cache. The description adds no additional meaning beyond reminding the reader that cache=true provides a free 24h cache hit, which duplicates the schema's explanation.

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 begins with 'Summarizer' which essentially restates the tool name, and does not explicitly state that it summarizes Facebook posts/videos. The only actionable information is about credits and caching, not the core function. The input schema's url description provides the missing context, but the description itself fails to convey its primary purpose.

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

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

There is no guidance on when to use this tool versus sibling summarizers (e.g., youtube_summarize, tiktok_summarize) or other Facebook-specific tools. It doesn't even state that it should be used for Facebook content, leaving that to the schema. 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?

The description discloses important behavioral details: a 90-event ceiling, approximate cost (~12 credits, 0.4/result), that empty results and failures are not charged, and caching behavior with cache=true. These go beyond typical annotations and help set 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 information-dense, with no redundant phrases. Each sentence adds value: event types, ceiling, cost, charging policy, and caching. It is well-structured with a dash separating the core function from constraints.

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 core behavior and limitations but lacks explicit detail on the response structure (no output schema). It vaguely mentions 'typed payload' but does not clarify the format or fields of returned events, which could leave users uncertain about the exact output.

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 parameters (username, cache, limit, cursor) with clear descriptions. The tool description adds contextual info (e.g., cache for free hits, 90-event ceiling) but does not significantly enhance parameter understanding 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 indicates it deals with public GitHub events and highlights specific event types (Push commits, PR/issue actions). It is distinct from sibling tools like github_contributions or github_followers, though it does not use an explicit verb like 'fetch' or 'retrieve'.

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 alternatives. It mentions caching and cost constraints but never states the intended use case or scenarios where it is preferred over other GitHub tools.

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

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

With no annotations, the description carries the full disclosure burden and excels: it discloses cost, free empty/failure behavior, cache behavior, and even response envelope fields (`cached`, `cachedAt`). This goes 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?

Three concise, information-dense sentences cover output, cost, failure policy, and cache usage without redundancy or filler. The most important information is 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 2-parameter tool with no output schema, the description provides sufficient context: what data to expect, how much it costs, when charges are waived, and how caching works. This enables correct invocation and interpretation of results.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining the effect of `cache=true`, the default freshness behavior, and response envelope details on cache hits. This is exactly the kind of semantic value-add expected.

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 specifies the resource ('GitHub contribution graph') and details returned fields ('sorted days[], currentStreak..., longestStreak...'). This cleanly differentiates it from sibling GitHub tools like github_repository or github_followers.

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

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

It gives clear practical context on when to use the `cache=true` parameter and explains billing behavior ('Costs 2 credits', 'Empty results and failures are never charged'). It does not explicitly mention alternatives or exclusions, but the guidance is actionable and relevant.

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 transparently discloses cost per result (0.1 credits), a ~3 credit estimate, that empty/failed requests are free, and the 24h cache behavior. This goes beyond basic function and helps set expectations, though it does not mention details like rate limits or authentication requirements.

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 deliver output fields, cost model, cache behavior, and a performance caveat with zero filler. The first sentence front-loads the core purpose (follower cards + fields), making the tool 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 list tool with no output schema, the description covers result fields, cost, cache, and hints at pagination via 'expensive to page fully'. The schema separately documents cursor semantics and nextCursor, so overall context is sufficient, but the description could explicitly connect pagination to the nextCursor field.

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 4 parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics by tying cost to limit/result count, explaining cache=true gives a free cached hit, and warning that large accounts are expensive to page fully, which enriches the understanding of limit and cursor parameters.

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 'Follower cards {id, login, type, url, avatar}' clearly indicates the tool returns GitHub follower data, and the field list clarifies the output shape. However, it lacks an explicit verb like 'list' and does not distinguish from sibling tool github_following, which returns accounts the user follows.

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

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

The description implies when to use the tool (to retrieve followers) and offers a caution about large accounts being expensive to page fully, suggesting careful use of pagination. However, it does not explicitly state when NOT to use it or mention alternatives such as github_following for following lists.

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 well by covering key behaviors: empty results and failures are never charged, pricing per result, and caching semantics (cache=true for free 24h hit, default always fresh). It doesn't mention potential rate limits or error responses, but the core behavioral traits are 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 extremely concise, using three short sentences that pack essential information: scope, pricing model, free failure behavior, and caching option. Every sentence adds value with zero fluff, and it's perfectly front-loaded with the core purpose.

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

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

Given that there is no output schema, the description does not need to explain return values, but it could still note the response format (e.g., card structure, envelope with cached flag). However, for a simple list-fetch tool with good schema coverage and clear pricing/caching, the description is reasonably complete. The only gap is the lack of mention of pagination behavior beyond the cursor parameter, but the schema already covers that.

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?

Since the schema has 100% coverage with detailed parameter descriptions (e.g., cursor is 'Opaque cursor from a previous nextCursor', not a bare page number), the description doesn't need to repeat them. However, it adds value by explaining the cache parameter's impact on cost ('free 24h cache hit') and the default fresh fetch behavior, which goes beyond the schema's description.

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

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

The description clearly states the tool returns accounts a user follows, matching its name and distinguishing it from sibling tools like github_followers and github_user. It specifies the scope (following accounts) and references the same data format as followers ('same card'), making the purpose 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?

The description mentions pricing and caching behavior, but does not explicitly say when to use this tool versus alternatives like github_followers or github_activity. It implies usage by the reference to 'followers' pricing but lacks explicit context or exclusions, providing only minimal 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 fully carries the behavioral transparency burden. It explicitly discloses the credit cost (~12 credits, 0.4/result), the policy that empty results and failures are never charged, and the caching behavior (cache=true gives a free 24h cache hit, default is always fresh). It also reveals response behavior such as state being echoed and the cursor being opaque. It omits details like auth requirements or rate limits, but the provided operational disclosures are 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 four short sentences, front-loaded with the core purpose ('List repo PRs'), followed by key response features, cost, failure policy, and cache behavior. Every sentence adds actionable information without redundancy or 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?

For a read-only listing tool with 5 parameters and no output schema, the description covers the essential context: purpose, notable response fields, cost model, caching strategy, and pagination cursor semantics. It does not fully specify the expected response shape (e.g., array structure), but the information provided is sufficient for an agent to select and invoke the tool correctly in most situations.

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 describes all five parameters in detail with 100% coverage, so the baseline is 3. The description adds minimal parameter-level value: it repeats the cache parameter behavior and lists response fields like draft, labels, author{}, head/base, which are not parameter semantics. It does not materially improve understanding 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 opens with 'List repo PRs', a specific verb+resource statement that clearly identifies the tool's function. It enumerates distinctive response features (draft, labels, author{}, head/base, opaque Link cursor) that separate it from sibling GitHub tools focused on repositories, users, activity, or trending. This makes the purpose immediately 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?

The description provides clear context by stating the tool lists repo PRs and includes operational guidance on state filtering, cache behavior, and credit costs. It does not explicitly name alternative tools or state when not to use it, which keeps it at a 4 rather than a 5. The example 'state echoed' and 'opaque Link cursor' also convey usage expectations for pagination and state.

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 well by disclosing cost (~0.4/repo, ~12 credits), caching behavior (24h cache, default fresh), and that empty/failed results are not charged. It also mentions the opaque Link cursor. This is strong transparency, though it omits explicit read-only status 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 compact, with the core purpose stated first, followed by distinct, relevant behavioral notes (cost, caching, failure policy). Every sentence adds value; no redundancy or fluff. It is well-structured for quick scanning.

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

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

Given the tool has no output schema and no annotations, the description covers important behavioral context: pagination, cost, caching, and failure handling. It does not describe the response format or mention any edge cases, but for a repository listing tool, it is reasonably 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 each parameter already has a clear description (e.g., sort excludes stars, cursor is opaque). The description adds minimal extra parameter meaning—only reiterating the cursor and cost but not clarifying parameter usage 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 states the tool lists a user's repositories with options for sort, direction, and type. It is specific and uses a strong verb, but it does not explicitly differentiate from sibling tools like github_repository or github_user, 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 provides practical usage details (e.g., cache=true for free cache hits, cursor pagination) but does not explain when to use this tool versus alternatives or when not to use it. There is no mention of comparing with other GitHub tools, so guidance is limited to operational tips.

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 of behavioral disclosure. It covers credit cost, caching behavior (cache=true gives free 24h hit), and that empty results and failures are never charged. It does not describe the response shape or error handling beyond charging, but given tool simplicity, this is sufficient.

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 concise, front-loaded with the most important data fields, and uses a single sentence that packs in cost and caching information without fluff. 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?

Given only 2 simple parameters and no output schema, the description adequately covers the tool's purpose, cost, and caching. It could mention the return envelope structure, but that is not critical given the tool's low complexity and the presence of good sibling 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 parameters are already well-documented. The description adds no additional parameter-level semantics beyond what's in the schema; it only repeats tool-level behaviors like cost and caching. Thus, 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 lists the resource (GitHub repo) and the specific data fields it returns (stars, watchers, openIssuesAndPrs, license, parent). It distinguishes from sibling github_repositories (plural) by indicating it's for a single repo's details, though it doesn't explicitly state 'get details for a single repository'.

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 vs alternatives. It doesn't mention that github_repositories is for listing multiple repos, nor does it provide context about selecting this over other github_* tools. The only usage hint is implicit in naming.

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 compensates by disclosing important behaviors: the 2-credit cost, the 24h cache option, the default fresh fetch, and that empty results or failures are free. It does not discuss factors like rate limits or response envelope details, but still provides meaningful behavior and safety context.

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

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

The description is short and front-loaded, using three concise sentences. There is slight redundancy in mentioning '2 credits' twice, but it remains efficient and easy to scan.

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

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

For a tool with no output schema and four well-documented parameters, the description provides sufficient context: what data is returned, how windows affect results, cost, cache behavior, and failure handling. It is not exhaustive about response structure, but it covers the important operational details.

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 input schema already explains cache, limit, since, and language in detail. The description adds no extra parameter semantics beyond cache guidance, but since the schema is sufficient, a 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 identifies github.com/trending/developers as a source of windowed rankings with popularRepo and followers, making the tool's purpose clear. However, it uses a noun phrase instead of a specific verb like 'get' or 'list,' and does not explicitly distinguish it from sibling tools like github_trending_repositories.

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 usage tips around caching and cost: 'Pass cache=true for a free 24h cache hit' and 'Empty results and failures are never charged.' However, it does not explain when to choose this tool over alternatives such as github_trending_repositories or github_user, leaving the selection guidance implicit.

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 fully addresses cost, caching, and failure semantics: it states the 2-credit cost, that failures and empty results are never charged, and the exact cache behavior. This adds valuable behavioral context beyond structured fields and distinguishes the tool nicely.

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 key 'tr' vs all-time' distinction, then costs, then cache. Every sentence earns its place; it is compact and useful.

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 no output schema, the description omits mention of the response envelope. However, the purpose, cost, cache, and parameters are well covered, and for a simple trending list the description is largely sufficient. The missing output shape slightly lowers this score.

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 well-described in the schema. The description adds nothing new about the parameters since the schema is already complete; it does add credit/cache context, but that does not affect the 'parameter semantics' score per the rubric's 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 fetches github.com/trending repositories ranked by stars greedy (daily|weekly|monthly), distinguishing it from all-time star counts and sibling tools like github_trending_developers or github_repositories. The 'ranked by stars greedy' phrase precisely scopes the data and the resource.

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 explicitly mentions the daily/weekly/monthly trending windows, the credit cost, and the cache option, giving clear usage context. It does not explicitly mention when not to use this tool, but the purpose clarity is high enough that an agent would be able to distinguish it from general repository listing tools.

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

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

With no annotations provided, the description fully bears the burden. It discloses cost (1 credit), free on empty/failures, and cache behavior (24h cache with cache=true), which are critical operational details. This goes beyond the schema and is exceptionally 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 waste. It leads with the core purpose, then efficiently covers cost and caching. Every piece of information is actionable and relevant, making it exceptionally concise and 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 simple profile retrieval tool with full schema coverage and no output schema, the description is complete. It specifies the returned data fields, cost, failure handling, and cache options, leaving no critical gaps. The context is sufficient for an agent to use 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 covers both parameters (cache and username) with full descriptions. However, the description adds value by explaining the cost implications of cache versus fresh fetches and the default always-fresh behavior, providing context beyond the schema's technical details.

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 a GitHub public profile with specific fields (login, type, email, followers). It distinguishes from siblings like github_activity or github_followers by focusing on profile data, making the purpose 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's evident the tool is for retrieving profile information, but there is no explicit 'when not to use' or comparison to alternative GitHub tools. The context is clear enough to infer usage, though it could explicitly differentiate from siblings like github_contributions or github_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 must carry all behavioral disclosure. It does this excellently: explains spend/impression data limitation (commercial ads omit them), isActive semantics (within 7 UTC days), credit cost, and caching behavior. This is concrete, non-obvious behavioral detail the agent couldn't infer from schema alone.

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 sentences, each adding value. The most surprising behavioral facts (spend/impression omission, isActive semantics) are front-loaded. Even the pricing and caching details are concise and worth mentioning. No wasted words.

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

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

Given 3 parameters with 100% schema coverage, the description adds the missing context: the isActive semantics are not in the schema, the spend/impression caveat is critical, and pricing/caching is essential operational info. This is complete for a detail-fetch tool with a well-defined purpose and 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining cache=true semantics (free hit) and creative_id format (URL). It also clarifies the false default meaning (always fetch fresh). This goes beyond schema descriptions, warranting 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?

The description clearly states the tool fetches Google Ad Library ad details via creative_id, distinguishing from Facebook ad library by name and explicit 'Google' reference. The verb+resource (fetch ad details) is specific and unambiguous. Sibling tools like google_ad_library_advertiser_search and google_ad_library_company_ads are distinct in scope.

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 explicitly explains when to use caching (cache=true for free 24h hits) and when not (default fresh), states the credit cost (2 credits), and clarifies that empty results/failures aren't charged—valuable guidance for an agent deciding whether to invoke. It doesn't explicitly name alternatives, but this is a fetch-by-ID tool with clear 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, the description carries the full burden of behavioral disclosure. It clearly discloses the credit cost (1 credit when results are found), that empty results and failures are free, and the cache behavior with cache=true. This is transparent about pricing and caching, but does not detail response structure or rate limits, which would elevate it further.

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 concise, fitting in two sentences with no redundant filler. However, the truncated 'AR…' introduces slight ambiguity and could be clearer. It is front-loaded with the core purpose, then adds credit and cache details, which 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?

Given the tool has 4 parameters and no output schema, the description covers key operational context like credit fees and caching, but does not explain the return format or pagination. It is a functionally adequate description for a search tool but leaves some gaps around output structure.

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, but the description adds meaningful semantics beyond the schema. It explains the q parameter works with expanded/ranked search favoring certain entity types, and it clarifies the cache parameter's cost-saving function. This provides value beyond the bare parameter descriptions 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 clearly identifies the tool as a search for Google Ads Transparency advertiser entities, using the verb 'Find' and mentioning ranking and multi-result behavior. This distinguishes it from sibling tools like google_ad_library_ad_details or google_ad_library_company_ads, which focus on individual ads or company-specific 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 implies usage by mentioning search by brand/domain and ranking behavior, but does not explicitly state when to use this tool instead of alternatives. It provides context about credit costs and cache usage, which are helpful operational guidelines, but sister tools are not referenced for exclusion or comparison.

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, and the description compensates with several meaningful behavioral details: non-election ads omit spend/impression ranges, `isActive` depends on 7 UTC days from `lastShown`, hits cost 2 credits, empty/failed results cost 0, and default cache behavior is fresh. This goes beyond the structured schema and is genuinely useful for an agent.

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 concise and contains no filler—every sentence conveys pricing, cache, or data-availability info. It loses one point because it is not front-loaded with a clear purpose statement; the first sentence is a caveat rather than a straightforward summary of what the tool does.

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

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

There is no output schema, and the description does not clearly summarize what the returned ad records look like. The schema does provide important hints like `nextCursor`, `totalReturned`, and `cachedAt`, so it is usable, but the tool's purpose and response shape remain under-specified.

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 100% of the 10 parameters with meaningful descriptions, so the description does not carry much burden here. It restates the spend/impression caveat and `isActive` logic that already appear in the schema, adding little 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 never explicitly states what the tool does: there's no verb like 'list', 'fetch', or 'search' identifying it as a company-ad retrieval tool. Instead, it opens with a caveat about Google's data publication behavior and then discusses credit/cache details, requiring the agent to infer the tool's core purpose from the 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?

The description provides conditional guidance for `cache=true`, but no clear guidance on when to use this tool versus alternatives such as `google_ad_library_advertiser_search` or `google_ad_library_ad_details`. It lacks when-to-use logic or exclusion criteria.

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 so admirably. It discloses cost (1 credit), the fact that empty results and failures are not charged, and the caching semantics (cache=true vs default fresh). This is detailed and adds significant behavioral context beyond any structured metadata.

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

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

Two sentences, zero fluff. Every piece of information—cost, schema alignment, cache behavior—serves a purpose. Front-loaded with the resource and key differentiating details (camelCase schema). Perfectly sized for quick 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 tool of this complexity (3 simple params, no output schema), the description covers all critical aspects: what it does, cost implications, cache options, and outcome on empty/failure. It also hints at response structure (camelCase, fields like followers, externalUrl, businessAddress), which helps set expectations without going overboard. No output schema means the description doesn't need to explain return values beyond this.

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 covers 100% of parameters, providing a baseline of 3. The description adds value by explaining the caching behavior of cache and cacheMaxAge (e.g., 'free 24h cache hit', 'default always fresh'), which enriches understanding beyond the schema alone. It doesn't describe the userId param further, but the schema already does that well.

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 tool as retrieving an Instagram profile by user ID or @handle, and mentions the camelCase schema aligned with Channel Details. However, it does not explicitly use a verb like 'fetch' or 'get', and does not differentiate itself from sibling tools like instagram_details or instagram_channel_details, though context implies the basic profile.

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

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

Provides clear context on cost and caching behavior, including when to use cache=true and the implications (free 24h cache hit, default always fresh). However, it does not explicitly state when to use this tool versus alternatives or mention any exclusions, though the cost and caching guidance is useful for decision-making.

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?

Despite no annotations, the description transparently discloses cost behavior (1 credit per successful fetch), no-charge on empty results and failures, caching default (always fresh), and cache hit behavior with free 24h TTL. Also hints at approximate flags, which is useful behavioral context.

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

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

The description is a single, dense paragraph with three sentences. Every clause adds unique value: key set, credit cost, failure/caching policy. No redundancy with the schema despite being rich in 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 description covers the important usage aspects (cost, caching, failure handling) and key output fields. Since there is no output schema, it mentions the fixed key set (fbid, bioLinks, isBusinessAccount, approx flags). It could benefit from describing what 'approx flags' means, but overall it is complete enough for the tool's simplicity.

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

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

Schema coverage is 100% and the schema contains detailed descriptions for all three parameters (url, cache, cacheMaxAge), including format guidance, platform matching warning, and TTL options. The description adds value by mentioning the cache default and free 24h period, but parameter semantics are mostly already 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 clearly states it fetches Instagram profile stats with a fixed set of fields including fbid, bioLinks, and business account flags. It distinguishes from instagram_basic_profile by noting the fixed key set and credit cost, but does not explicitly name alternative tools for simpler profile needs.

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 usage guidance for caching (cache=true for free 24h cache hits, cacheMaxAge for TTL control) and cost implications (1 credit, free on empty/failure). It does not explicitly contrast when to use this tool versus instagram_basic_profile or instagram_details, but the distinguishing feature of cost and fixed keys is 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 full transparency burden and does so well — it discloses the credit-pricing model (0.3/result), no-charge-on-empty/failure behavior, cache semantics, and default freshness policy. This goes beyond surface-level and meaningfully informs cost-sensitive agent decisions.

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

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

Three dense, information-rich sentences, each earning its place: purpose, cost model, and caching behavior. It is front-loaded with the main purpose and offers concrete, actionable usage details with zero 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?

For a relatively simple fetch tool with a well-documented four-parameter schema, the description covers the key contextual gaps — cost, cache, failures, and output highlights. It is slightly light on pagination caveats and the exact mapping between url formats and platform matching, but these are relatively minor given the schema already explains cursor and url behavior.

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

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

Schema coverage is 100% — every parameter (url, cache, limit, cursor) is already well-documented in the schema with formats, bounds, examples, and pagination details. The description adds the cost-per-result detail and output structure, which is useful but does not fundamentally extend the schema's parameter 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?

'Latest posts from a public Instagram profile' is a clear, resource-specific purpose statement. The mention of distinct output fields (carousel children[], mediaCount, user{}) helps differentiate it from siblings like instagram_channel_reels or instagram_basic_profile, though it never names them and lacks an explicit imperative verb like 'get' or 'fetch.'

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 offers strong contextual guidance on cost awareness ('Costs ~6 credits'), failure/empty-result policy, and the cache parameter ('Pass cache=true for a free 24h cache hit'). However, it never explicitly states when to use this tool versus alternatives or names exclusion cases, leaving some ambiguity for 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?

No annotations are provided, so the description carries the burden. It discloses important behaviors: cost structure (credits per result, ceiling), free failures, caching behavior, and pagination mechanics. It also clarifies the difference between cache and fresh requests. While it covers many critical aspects, it does not mention if there are rate limits or specific authentication requirements, and 'null' title is not relevant.

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

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

The description is dense but efficient, with a single paragraph that front-loads the core purpose and then covers cost, pagination, and caching. Every sentence adds unique value, no filler or repetition. It is appropriately concise for the complexity of the tool.

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

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

Given the tool's complexity (5 parameters, pagination, caching, cost model) and no output schema, the description covers key aspects: credits, empty results, pagination flow, and cache behavior. It does not describe the return envelope structure beyond cursor and hasMore, but that might be acceptable. It could also mention rate limits or typical response contents, but it is fairly complete for decision-making.

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 value by explaining the purpose of parameters like userId to skip resolve, cache behavior, cursor format, and limit default/max. It goes beyond the schema by mentioning 'legacy sequential WPI could cost ~80s' and the exact structure of nextCursor. This enriches understanding of the parameters, so a 4 is warranted.

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 'Latest Reels from a public Instagram profile' with a resource and platform specified. It distinguishes itself from sibling tools like instagram_channel_posts and instagram_trending_reels by focusing on 'Reels' from a 'profile'. However, it could be slightly improved by explicitly mentioning it is for the 'channel' as opposed to other Instagram-related reels 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 provides good usage context: it mentions skipping resolve via userId, pagination via nextCursor and hasMore, and conditional caching. It implies when to use it (when wanting profile reels) but does not explicitly state alternatives or when not to use it, such as pointing to instagram_reels_search or instagram_trending_reels. Sibling differentiation is inferred from the 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?

With no annotations provided, the description must carry the behavioral burden, and it does. It discloses that Instagram may not expose all data ('when Instagram exposes them'), cost behavior ('~45 credits (0.9/result)'), the no-charge guarantee for empty/failed results, and the cache= true behavior with a free 24h hit. This goes well beyond a generic 'gets comments' statement. The only minor gap is not describing pagination behavior in the description, but the cursor parameter schema already covers that, so this is above average.

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 concise sentences, each carrying distinct value: what the tool returns, cost/billing transparency, and cache behavior. It is front-loaded with the core purpose, then provides operational details without verbose filler. Every sentence earns its place, and nothing is redundant with the schema.

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

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

Given the tool's moderate complexity — 4 parameters, no output schema, no annotations — the description covers the primary operational concerns: result fields, cost, cache, and failure billing. The schema fully covers parameter semantics and pagination via cursor/nextCursor. The only missing context is a mention that output is an envelope with items, nextCursor, and hasMore, but since no output schema exists and the description already mentions 'results', the provided information 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 description coverage is 100%, so the baseline is 3. The description's mention of 'cache=true for a free 24h cache hit' and 'default always fresh' reinforces the cache parameter semantically but does not add substantial new meaning beyond the schema. The URL parameter's cross-platform warning is already in the schema. Overall, the description does not compensate further beyond what the schema already documents, so a 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 uses a specific verb ('Get') plus a clear resource ('comments on any Instagram post or Reel'), and enumerates the returned fields: text, author, likes, and timestamp. It explicitly distinguishes itself from sibling comment tools on other platforms (facebook_comments, tiktok_comments, youtube_comments, rumble_comments) by naming Instagram. This is a clear, differentiating purpose statement.

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 does not explicitly name alternative tools, but the broader context of sibling tools (e.g., instagram_channel_posts, instagram_details) combined with the explicit platform-scope in the description ('any Instagram post or Reel') makes when-to-use clear. The description also notes cost and that empty results/failures are never charged, helping agents decide when to call. It lacks an explicit exclusion such as 'for replies, use instagram_comment_replies' — indeed there is no exact sibling for comments-replies in the list, so the guidance is sufficient for the tool's purpose.

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

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

With no annotations provided, the description carries the full burden. It discloses credit cost, free cache hits, and that empty results or failures are never charged. It also clarifies default freshness. This is meaningful behavioral information beyond the schema, though it doesn't mention rate limits or authentication.

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, well-structured sentence that leads with the core action, then useful operational details. No fluff or redundancy.

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 no output schema, the description lists the expected data fields, covering return content. It also covers cost, caching, and failure behavior, making it complete for a straightforward data-fetch tool.

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

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

Schema coverage is 100% and both parameters are well described in the schema. The description adds a note about cache behavior ('free 24h cache hit') but this doesn't enhance parameter semantics significantly 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 clearly states the tool retrieves Instagram posts, reels, or carousels and lists specific data fields (caption, likes, comments, views, media URLs, author, per-slide children). This distinguishes it from sibling tools that focus on profiles, channels, comments, or transcripts.

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 explains cost and caching behavior, which is useful context, but does not explicitly state when to use this tool versus alternatives like instagram_channel_posts or instagram_embed. Usage is implied rather than explicitly contrasted with other Instagram tools.

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

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

With no annotations, the description carries the burden of disclosing side effects. It transparently mentions the 1-credit cost, free for empty results/failures, and the 24h cache behavior. This is honest about pricing and caching, though it doesn't detail rate limits or error scenarios. Strong for the category.

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

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

Three short sentences cover purpose, usage, and pricing. Every clause serves a purpose—no fluff. The description is immediately scannable and front-loaded with the most critical info.

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 embed tool, the description covers purpose, cost, and caching. It might have clarified the response format (e.g., JSON containing HTML) but 'drop html' implies the output is HTML. Given no output schema and low complexity, this is sufficient and 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 the baseline is 3. The description's mention of 'cache=true for a free 24h cache hit' adds slight value by highlighting the credit savings, but the schema already documents this clearly. No new parameter meaning beyond the schema.

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

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

The description clearly states it's a classic Instagram embed snippet with blockquote.instagram-media and embed.js. The verb 'drop html into your page' makes the purpose immediately obvious. It differentiates well from sibling Instagram tools like instagram_details and instagram_basic_profile by focusing on the embedding use case.

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 for embedding Instagram content without explicitly stating when to choose this over alternatives. It includes practical usage details like cache=true and credit costs, but no explicit when/when-not or alternative guidance. Clear enough for a simple utility, but no explicit differentiation.

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?

Even though no annotations are supplied, the description discloses several meaningful behaviors: flat 2 credits, no charge for empty results or failures, fresh-by-default with an optional free 24h cache, and a hybrid native/Apify data source. The phrase 'Stale 200 on wall' is cryptic and read-only nature is not explicit, but the cost, caching, and failure-charging details add real value.

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

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

The description is short but structurally choppy, made of fragments like 'Max 50.' and 'Stale 200 on wall.' It also contains direct redundancy: 'Flat 2 credits.' followed by 'Costs 2 credits.' The cryptic phrase 'Stale 200 on wall' is not explained well enough to earn 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?

The description covers pricing, caching, and failure billing, which helps an agent set expectations before calling. However, with no output schema, it does not describe the shape of the returned listing or what 'wall' refers to, leaving the response format ambiguous for downstream use.

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 useful context around credit cost and cache freshness ('default always fresh'), but it largely repeats what the schema already states about limit and cache, and it adds nothing about mediaType or q 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 phrase 'Hashtag Explore' and 'Apify listing actor' imply this tool returns hashtag-based listings, and the resource is clear from the name and the q parameter. However, it never states plainly that it searches Instagram for posts matching a hashtag, and it does not explicitly differentiate itself from sibling tools 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 guidance about when to use this tool versus alternatives such as instagram_reels_search, instagram_tagged_posts, or other platform hashtag searches. The only conditional usage advice is about the cache parameter ('Pass cache=true for a free 24h cache hit'), which is parameter-level guidance rather than tool-selection guidance.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses pricing behavior ('Flat 1 credit'), failure behavior ('Empty results and failures are never charged'), and cache behavior ('Pass cache=true for a free 24h cache hit'), which is meaningful operational context beyond the input schema. It does not disclose details such as rate limits or exact error behavior, but the disclosed traits are strong.

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 resource and output fields, but it contains redundancy: 'Flat 1 credit' is immediately followed by 'Costs 1 credit.' That repeated sentence does not earn its place and could be merged to improve 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 3-parameter tool with no output schema, the description covers the main pieces: what is returned, the target platform/profile scope, crypto/pricing, cache-free outcomes, and failure-cost transparency. It does not mention pagination or exact output envelope shape, but given the sibling context and schema richness, the description is still sufficiently complete 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 description coverage is 100% and the schema fairly explains url, cache, and userId including the 'skip handle→ID resolve' behavior. The tool description adds almost no new parameter-level meaning; it restates the cache option but does not extend the user's understanding 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 ('Persistent Story Highlight albums for a public profile') and specifies the returned fields: id, title, cover, owner. It lacks an explicit verb such as 'list' or 'fetch', and it doesn't explicitly contrast itself with the sibling instagram_highlights_details, but it is easy to infer what is being retrieved.

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: it targets public profiles, costs a flat 1 credit, and allows a free 24-hour cache hit. However, it provides no explicit guidance about when to use this tool instead of related siblings like instagram_highlights_details or instagram_basic_profile, so alternative selection is only implied.

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 (flat 1 credit, no charge for empty/failed) and cache behavior (24h cache with cache=true, always fresh otherwise) — valuable transparency not present in annotations (none provided). It doesn't describe output details or potential errors beyond the cost policy, but the key 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 concise (2 sentences, 4 fragments) and front-loaded with the core purpose. Every sentence adds value: what the tool returns, cost, and caching option. No fluff or redundancy, despite minor repetition of '1 credit' and 'costs 1 credit' which is slightly redundant but doesn't hurt.

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 data-fetching tool with a clear schema and no output schema, the description covers the purpose, cost, and caching behavior. It lacks explicit mention of prerequisites (like needing a valid highlight ID) or error handling, but the input schema and context of sibling tools (e.g., instagram_highlights) suffice. It's near complete for its scope.

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% coverage of both parameters (id and cache). The description adds that id is from highlights endpoint and cache hits are free, but these are already in the schema descriptions. The description doesn't add significant new semantic meaning beyond the schema.

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

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

The description clearly states what the tool does: 'Items inside one Instagram Story Highlight album — media URLs, type, takenAt.' This is specific with a clear verb and resource, and it distinguishes from sibling tools like instagram_highlights (which lists highlights) and instagram_media 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 implies the tool is for fetching the contents of a highlight albumtor, with the 'id' parameter needing a highlight ID. It doesn't explicitly say when to use it vs. alternatives like instagram_highlights, but the context of 'items inside one album' makes the use case clear. The cache guidance provides practical usage tips.

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 well by disclosing credit cost, no-charge behavior for empty results/failures, and the 24h cache option. However, the phrase '(default always fresh)' is confusing because the schema says cache defaults to true, contradicting the idea of always fetching fresh.

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, covering core purpose, cost, failure billing, and cache behavior in just a few sentences. The only issue is the ambiguous cache default wording, which slightly weakens the clarity of an otherwise tight 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?

Despite lacking an output schema, the description names what the caller receives (stable id, bio, links, stats) and covers key operational behaviors like cost, failed requests, and caching. It could be more specific about API prerequisites or rate limits, but for a simple single-profile resolver it is reasonably 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?

The input schema already provides strong descriptions for both parameters (q and cache) with 100% coverage, so the description adds little parameter-level meaning. The credit cost and cache context is useful, but it does not materially enrich what the schema already says.

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

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

The description uses a specific verb ('resolve') and clearly defines the resource: one public Instagram profile with stable id, bio, links, and stats. The explicit 'not niche discovery' distinction differentiates it from related Instagram search and discovery 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 a clear use case: resolving a brand or @handle to a single public profile, not niche discovery or keyword search. It does not name alternative sibling tools explicitly, but the exclusion is enough to guide selection in most cases.

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 burden of behavioral disclosure. It does explain cost per call/results, caching behavior, and that failures/empty results are free, which is valuable. However, it does not describe the exact output structure (e.g., what isTrendingInClips and trendRank look like) beyond naming them, leaving some ambiguity.

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 concise, front-loaded with the core question, and each sentence adds value (trending indicators, cost, caching, failure policy). No fluff or redundancy.

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 tool's moderate complexity (3 params, no output schema, no annotations), the description covers the essential use case, cost, and caching. It lacks explicit return value details, but the schema for output is not available, so the description is reasonably complete for an API consumer.

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 each parameter (cache, limit, audioId). The description adds value by explaining the cache behavior and cost implications, but it does not significantly alter understanding of the parameters beyond the schema. It also does not clarify the 'full audio URL' format beyond an example.

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 states the tool's function: checking if an Instagram sound is trending and retrieving reels that use it. It names the specific resource (audio ID) and distinguishes it from sibling tools like instagram_reels_search or instagram_trending_reels, which is not a direct 'instagram_reels_search, not a direct

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

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

It provides clear usage context (e.g., 'Is this Instagram sound trending?') and explicit cost/caching guidance, including when to use cache=true. It also states that empty results are not charged, which helps with decision-making. No explicit exclusion, but the context 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, the description carries the full burden and discloses important operational behavior: a multi-provider cascade, flat 2-credit cost, no charge for empty/failed calls, and a 24h cache option with free hits. These details go beyond the schema. It omits auth, rate limits, and return envelope details, so it is strong but not perfect.

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, but not every sentence earns its place: 'Flat 2 credits' and 'Costs 2 credits' are redundant, and the 'Cascade' wording is unexplained jargon. It front-loads routing and pricing rather than the core function, which would make it more immediately useful.

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 tool with no nested objects, the operational context is substantially covered, especially cost, failure behavior, and cache semantics. However, with no output schema and many Instagram sibling tools, the description should state what is returned and when this tool is the right choice. Both are missing, so the definition is usable but incomplete.

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 some value for cache (free hits, default fresh) and limit (max 50, flat credit cost), but it adds nothing meaningful about q or datePosted beyond their schema descriptions. It is adequate without compensating 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 never explicitly states a verb+resource such as 'searches Instagram Reels by hashtag or keyword.' It starts with an unexplained 'Cascade' and focuses on source routing and billing, so the tool's purpose is only vaguely implied by its name and q schema. It also does not differentiate from siblings like instagram_hashtag_search or instagram_channel_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?

The only guidance is 'Pass cache=true for a free 24h cache hit (default always fresh),' which is cache behavior rather than tool selection. There is no statement of when to use this tool versus alternatives such as instagram_trending_reels or instagram_channel_reels, and no exclusions or prerequisites 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, the description carries the transparency burden well. It discloses the credit cost, the no-charge policy for empty results and failures, and the cache behavior. It could add details about response format or error semantics, but the essential behavioral traits 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?

Three concise, front-loaded sentences with no wasted words. The first sentence states the core purpose, and the next two add high-value cost and cache details. 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 summarize tool with good schema coverage, the description is nearly complete. It covers the output type, cost, failure charging, and cache behavior. It could be more explicit about platform exclusions or alternatives, but overall the agent has enough to select and 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?

The input schema already describes all three parameters with 100% coverage, so the baseline is 3. The description adds some cache and cost context, but this largely overlaps with the schema's cache description and does not materially deepen parameter understanding.

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 action ('Get an AI summary of any Instagram Reel'), the specific resource (Instagram Reel), and the output form ('a short paragraph plus key points'). It also distinguishes itself from transcript tools by adding 'without watching the video', and the platform-specific name separates it from sibling summarize 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 provides clear context: use this tool to get a summary of an Instagram Reel without watching the video. It does not explicitly name alternatives or state when not to use it, but the scope is unambiguous from the description and sibling names.

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. It discloses credit costs, caching behavior, empty results and failures not being charged, and the staleFeed fallback. This is comprehensive behavioral transparency, even covering edge cases like archives and free cache hits.

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, front-loaded with the core purpose, then adds critical usage details (cost, cache, fallback). Every clause is informative with no fluff. Excellent 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?

The description covers purpose, cost, caching, and fallback behavior. With no output schema, it doesn't elaborate on response format, but the envelope mention covers that partially. It could benefit from noting pagination (cursor is in schema but not mentioned in description), but the schema already documents that. Overall complete 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 parameters are already well-documented. The description adds context on credit cost per call, default freshness, and the envelope including cached and cachedAt. However, it doesn't add new parameter semantics beyond the schema, but the schema is thorough. Slightly above baseline due to added context on cache and cost.

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

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

The description clearly states it retrieves posts tagging an Instagram account, distinguishing it from other Instagram tools like instagram_basic_profile or instagram_channel_posts. It also mentions the authoritative author verification and failover behavior, which are specific and informative.

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

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

The description implies usage by specifying the endpoint's purpose and credit costs, but it does not explicitly contrast with alternatives like instagram_channel_posts or instagram_hashtag_search. The schema note about platform match provides some guidance. Lacks explicit when-not-to-use or alternative naming, but the purpose is clear enough.

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