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 behavior disclosure burden and largely succeeds: it discloses the 1-credit cost, that empty results and failures are never charged, and the free 24h cache-hit behavior with default always-fresh. It doesn't address auth or rate limits, but the economically important 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?

Four sentences with zero filler: purpose, payload scope, exclusion, and cost/caching behavior in order. Every sentence earns its place and the most decision-relevant facts are 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 5-param tool with no output schema or annotations, the description covers scope, exclusions, output-content hints, pricing and caching, while the schema covers all parameters at 100%. Only auth/rate-limit behavior and the exact return structure go unspecified, which is a minor gap for this tool family.

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

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

Schema description coverage is 100%, with url, cache, limit, cursor and marketplace each fully documented, so the baseline 3 applies. The description reinforces cache=true and the credit cost but adds no parameter syntax or format details beyond the schema — appropriate given the rich schema.

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

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

States a specific verb+resource: fetching third-party seller storefronts via /sp?seller= or /s?me=. Enumerates the payload (ASIN + canonical /dp URLs, price, badges) and explicitly excludes influencer /shop/{handle} pages, sharply distinguishing it from potential sibling 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?

Provides clear context: it targets Amazon seller storefronts and excludes influencer /shop pages, with the schema reinforcing the URL-platform-match requirement. No alternative tool is named for influencer storefronts, so the 'when-not' guidance is present but the routing alternative is left for the agent to infer.

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

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

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

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

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

The description uses three tight sentences, front-loading the core purpose before cost and caching details. Every sentence adds distinct information with no filler or repetition of the schema verbatim.

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

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

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

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

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

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

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

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

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

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

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

The description clearly implies this tool is for comparing multiple URLs at once, and references Post Analytics to indicate platform scope. It does not explicitly say 'use analytics_post for a single URL' or list exclusion conditions, but the multi-URL comparison context gives an agent clear situational guidance.

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

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

With no annotations, the description carries the burden and it delivers meaningful behavioral detail: 1-credit cost, no charge for empty results/failures, and cache behavior with a free 24h hit when cache=true. It does not describe what metrics are included or any rate limits, which keeps it from a 5.

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

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

The description is short and front-loaded with the core purpose. It loses a point because 'Costs 1 credit' repeats the parenthetical '(1 credit)' in the first sentence.

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

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

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

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

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

Schema description coverage is 100% and both url and cache are already fully documented, so the description adds only cost/cache context rather than parameter meaning. Baseline 3 is appropriate.

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

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

States a specific verb and resource: returns unified metrics for a single post, video, or reel, with platform auto-detection. The schema's 'unlike single-platform endpoints' explicitly distinguishes it from the many platform-specific detail tools in the sibling list.

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

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

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

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

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

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

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

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

The description is compact and front-loads the core purpose and return content. The cost information is slightly redundant ('(1 credit)' followed by 'Costs 1 credit'), and 'Post thread' is ambiguous as a verb phrase, but the overall structure is efficient.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is compact and front-loads the profile contents, but it contains redundancy: '(1 credit)' appears in the first clause and 'Costs 1 credit' repeats the same information in the second sentence. The caching guidance is concise, but the duplication means not every sentence earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is extremely compact and front-loaded: it opens with the core resource and content type, then adds cost and caching details in short, scannable sentences. Every sentence contributes useful information with no redundancy or filler.

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

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

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

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

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

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

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

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

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

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

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

The description gives useful context about caching and cost, but it does not explicitly state when to choose this tool over alternatives such as bluesky_profile or bluesky_post_details. Usage is only implied by the phrase 'Author feed' rather than explicitly routed with when-to-use or when-not-to-use guidance.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the baseline is 3. The description's cache guidance largely duplicates the schema's cache property description, and it adds no URL-format details beyond what the schema already provides for the url parameter.

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

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

States a specific operation: retrieve one Meta ad by ID. 'Same creative as search, plus delivery breakdowns' distinguishes it from the search and transcript sibling tools without relying on the tool name alone.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the burden, and it does add useful operational context: flat 2-credit cost, no charge for empty results/failures, and cache-hit semantics. However, it does not disclose what the tool returns, how results are structured, or any other runtime behavior.

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

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

Two short sentences with no filler; the cost and cache behavior are stated efficiently. It is concise, though it front-loads billing details instead of the tool's actual function.

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 is incomplete for a tool with no output schema and no annotations. It covers cost and caching but never states that the tool returns a company's Facebook Ad Library ads, what fields come back, or how it differs from related library tools.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no parameter-level meaning, but the baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description never states what the tool does; 'Company Ads' merely echoes the tool name and then moves straight to pricing. There is no verb or resource statement, so an agent cannot tell this apart from facebook_ad_library_search or facebook_ad_library_ad_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?

No guidance is given about when to use this tool versus alternatives. The description focuses entirely on credits and caching, with no mention of use cases, prerequisites, or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses billing behavior (flat 2 credits, empty/failed calls not charged), cache semantics (cache=true free for 24h, default fresh), and a data-availability caveat (spend/impressions typically only filled for political/issue ads). This is meaningful behavioral transparency beyond the bare operation. It doesn't document rate limits or auth, but the disclosed operational behaviors are substantial. No contradiction with annotations since annotations are 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 a single compact paragraph with high information density. Every sentence earns its place: what it does, what it costs, and the free-cache option. It could slightly improve structure by separating billing/caching into bullet points, but it is still efficient and 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 14 parameters, no annotations, and no output schema, the description fills several critical gaps: pricing, cache semantics, political/issue data caveat, and the broad search scope. Some gaps remain — no rate limits, no explicit mention of pagination depth or return shape, and no explicit sibling differentiation — but the description covers the most decision-relevant operational context and the schema covers all parameter meanings at 100%.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining billing per call (flat 2 credits), the cache behavior (0 credits on cache hit), and the caveat that spend/impressions are typically only filled for political/issue ads. It also hints that trim relates to lean payloads. It doesn't describe pagination deeply, but the cursor parameter and nextCursor mention in schema cover the basics. Minor gap: no explanation of how date range interacts with delivery start, though that's partially in schema.

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

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

The description names a specific verb ('Search'), a precise resource (Meta Ad Library), and the key axes of the search (keyword, active/inactive, media type, date range, platforms, cursor, spend/impressions). It says what the tool returns at a level that distinguishes it from siblings like facebook_ad_library_ad_details and facebook_ad_library_search_companies.

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

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

The description implies when to use it — general keyword search of Meta Ad Library — and several operational facts (2 credits, cache=true for free hits, spend/impressions only typically filled for political/issue ads in the ad_type parameter). It doesn't explicitly contrast with sibling tools like facebook_ad_library_company_ads or facebook_ad_library_search_companies, but the search-scoped verb and parameter hints do enough. The cache and billing guidance is useful direct usage guidance.

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

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

With no annotations provided, the description carries full burden. It discloses pricing (2 credits), that empty results/failures are free, cache behavior (cache=true gives free hit, default fresh), and the output nature (pageId for company-ads, not profileId). This is substantial behavioral context beyond a simple 'find' statement.

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

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

Three short sentences, all earning their place. The first sentence delivers the core purpose with key differentiators, the second covers pricing and failure policy, the third gives the cache hint. No redundant or speculative content.

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

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

For a 4-param search tool with no output schema and no annotations, the description covers purpose, cost, failure policy, cache behavior, and ID type. It doesn't explicitly describe the return list shape, but the 'pageId for company-ads' phrase conveys the essential output. Most of the missing parameter details are in the 100%-covered 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 baseline is 3. The description adds value by specifying the result contains pageId for company-ads (not profileId), which is not in the schema. It also reiterates cache=true for free hit, reinforcing the schema. This exceeds the baseline.

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

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

The description opens with a specific verb and resource: 'Find Meta Ad Library pages by brand.' It adds two differentiating details: results are name-matched and return pageId for company-ads (not profileId). This clearly separates 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 gives clear context: this is for finding Meta Ad Library pages by brand name, name-matched, with pageId output. It doesn't name sibling alternatives or state when not to use it, but the purpose implies the appropriate scenario. Cache and cost behavior also guide usage.

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

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

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

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

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

The description is short and dense, with each sentence delivering distinct operational facts about cost, failure billing, and caching. The only waste is the redundant 'Comment Replies' at the start, but overall the structure is efficient and to the point.

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

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

For a simple fetch-replies tool, the schema covers parameters and the description covers credits and caching. However, there is no output schema and the description does not clarify the return shape, pagination, or how the results relate to the provided commentId, so some important context is missing.

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

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

Schema description coverage is 100%, so the parameters are already well-documented in the input schema. The description adds no new semantic meaning about the parameters beyond echoing the cache option, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Comment Replies', which merely restates the tool name rather than stating an action such as 'Fetch' or 'List'. It does not explicitly identify the resource or distinguish this from facebook_comments or the sibling comment-reply tools for other platforms.

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

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

No guidance is given about when to choose this tool over alternatives like facebook_comments or youtube_comment_replies. The description focuses on credits and caching, not on the conditions that should lead an agent to select this endpoint.

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

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

With no annotations provided, the description carries the transparency burden and does substantial work: it discloses the 2-credit cost, the no-charge policy for empty results and failures, the 24h cache behavior, and the default fresh-fetch behavior. It does not mention pagination or reply expansion, but the disclosed behavior is valuable and specific.

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 with no wasted words, front-loading the output fields before covering cost and caching. 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?

Combined with the fully described schema, the agent knows the input parameters, the key output fields, the cost model, and the caching behavior, which is sufficient for a moderate-complexity tool with no output schema. The main missing context is routing to facebook_comment_replies if reply bodies are needed.

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 four parameters are already well documented. The description adds no parameter-level meaning beyond what the schema provides, including the cache behavior which is already described in the schema. This matches the baseline for complete 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 identifies the resource as Facebook post comments and lists distinctive output fields (reactionCount, reactions.like, author.id, replyCount), making the tool's purpose inferable. It lacks an explicit verb such as 'list' or 'get' and does not differentiate from the sibling facebook_comment_replies tool.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention facebook_comment_replies or other comment-related siblings, and the cache/cost notes are operational tips 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?

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

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

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

Four short sentences lead with the resource and returned fields, then cover cost, charge policy, and caching. No filler or repetition; each sentence adds information. The only slight cryptic element is 'video{} playback', but it conveys the object shape without bloat.

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

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

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

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

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

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

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

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

The description identifies the target resource ('Facebook post or Reel') and enumerates returned content (caption, engagement, author id, video{} playback, music), distinguishing it from sibling Facebook tools like facebook_comments or facebook_page_details. However, there is no explicit verb like 'retrieves' or 'fetches', so the action is inferred rather than stated.

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

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

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

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

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

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

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

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

Three sentences, front-loaded with the tool's purpose followed by cost and caching. No filler or redundancy; every sentence earns its place.

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

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

For a simple two-parameter lookup with no output schema, the description is nearly complete: it names returned fields, cost model, and cache behavior. The only notable gap is explicit routing guidance among Facebook sibling tools, but that is more about tool selection than invocation context.

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

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

Schema description coverage is 100%, with both url and cache fully documented. The description's cache note ('free 24h cache hit... default always fresh') largely mirrors the schema and adds no new parameter semantics beyond what is already structured.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a moderate-complexity tool (7 params, all schema-documented), the description plus schema cover purpose, result content, cost, cache, and failure-charge policy reasonably well. Gaps remain: no explicit sibling routing, no output schema to describe return shape beyond a partial hint, and no operational limits like rate ceilings. Adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all seven parameters. The description adds only marginal reinforcement — it restates cache behavior ('Pass cache=true for a free 24h cache hit') and references 'local startDate/timezone' which maps to the to/from filters, but adds no new format or syntax details beyond the schema.

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

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

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

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

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

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

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

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

With no annotations at all, the description carries the full burden and does a strong job: it discloses the 2-credit cost, free handling of empty results and failures, 24-hour cache behavior, and the approximate-count/failure/skip response characteristics. This is far more than a generic read-only statement.

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 resource, and every sentence adds value: response characteristics, cost, failure policy, and cache behavior. No filler or repetition.

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

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

For a tool with no output schema, the description does a reasonable job of hinting at response content via listingHits/hydrateFailures/hydrateSkipped and approximate counts, plus the required url parameter is documented in the schema. It could more clearly state the overall return shape, but the core calling and billing context is 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 mentions cache, sortBy, and approximate counts, but it mostly echoes or lightly references what the schema already documents rather than adding 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 identifies the resource as 'Public Facebook group posts' and lists the notable response attributes, so an agent can tell this is a fetch/list operation for group posts. It is specific enough to distinguish from profile posts or page details, though it lacks an explicit verb like 'get' or 'list'.

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

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

The description clearly implies it is for public Facebook group posts, but it never names sibling tools or conditions for when to choose this over, for example, facebook_profile_posts or facebook_page_details. It does provide useful operational guidance on caching and credit charges, but not tool-selection guidance.

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

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

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

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

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

The description is compact and front-loads the resource and key fields before moving to cost and caching details. The phrase 'coords (2 credits)' is slightly cryptic, but the overall structure is efficient and each sentence contributes useful information.

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

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

For a simple two-parameter tool with no output schema, the description lists the expected return fields and covers billing, failure charging, and cache behavior. It could be more explicit about URL input and error details, but the schema covers the URL and the description mentions failures.

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

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

The input schema already provides 100% parameter coverage, including URL platform matching and cache behavior. The description mostly reiterates the cache parameter and cost, adding no new semantic meaning beyond what the schema already documents.

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

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

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

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

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

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

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

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

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

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

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

The description is short and front-loads the purpose and output. However, it contains a redundant duplicate: 'Flat 2 credits. Costs 2 credits.' — the same fact stated twice in adjacent fragments. Otherwise every sentence earns its place, covering output, cost, failure pricing, and cache behavior.

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

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

For a simple 3-parameter tool with no output schema, the description covers purpose, cost, caching, and a partial output shape (id + lat/lng). It is complete enough for an agent to call the tool correctly. It could be stronger by describing the response structure in more detail, but the minimal output hint is sufficient for this use case.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter meaning beyond the schema: it repeats the cache cost/behavior already documented in the schema and does not add details for 'q' or 'limit'. The useful cost-on-failure note is behavioral rather than parameter-specific.

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

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

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

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

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

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

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

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

With no annotations provided, the description correctly takes on the transparency burden: it discloses the 2-credit cost, no-charge policy for empty/failed results, and cache hit behavior. It also hints at result semantics via isLocal/shipsOutsideRadius and the opaque cursor. It does not cover rate limits or full response shape, but the core behavioral profile is clear.

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

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

Three short, front-loaded sentences: purpose, essentials, cost, then cache policy. Every sentence carries distinct information and there is no fluff or repetition of generic 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?

The description plus the very detailed schema cover required inputs, billing, filtering, caching, and pagination semantics, and the tool name alone implies a listing response. But because there is no output schema and no annotations, the description still leaves the agent to infer the full return shape and any operational limits. It is solid but not fully complete for a 16-parameter tool.

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

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

Schema coverage is 100%, and the schema already documents every parameter (including cache, cursor, searchLocation, and billing tied to limit/details), so the baseline is 3. The description restates the cache and cost model rather than adding new parameter-level meaning. It adds no syntax or format details 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 first sentence is specific: 'Search Marketplace by keyword + city' gives verb, resource, and core inputs. It also names key capabilities (filters, isLocal/shipsOutsideRadius, opaque cursor). It does not explicitly contrast with sibling tools like facebook_marketplace_item or facebook_marketplace_location_search, so it stops short of full 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?

The description implies usage by stating the search scenario and adds concrete conditions for caching ('Pass cache=true...') and billing ('Empty results and failures are never charged'). However, it never tells the agent when to prefer this over alternative Marketplace tools or when not to use it, leaving alternative selection 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 carries the full burden of disclosing behavior. It usefully discloses the 2-credit cost, that empty results and failures are never charged, and the cache behavior with cache=true. This goes beyond surface-level purpose and gives an agent actionable operational expectations, though it does not discuss rate limits or error response specifics.

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

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

The description is a compact two-sentence structure: the first sentence conveys purpose and key output fields, and the second covers cost and caching. There is no filler or redundant elaboration; every clause contributes useful information.

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

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

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

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

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

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

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

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

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

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

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

The description gives no guidance on when to use this tool versus alternatives such as facebook_details or facebook_summarize. It mentions cache usage and credit cost, but offers no selection criteria or exclusions to help route an agent to the correct endpoint.

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

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

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

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

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

The description is short and front-loaded with the core purpose, but it redundantly states '2 credits. Costs 2 credits.' and largely repeats the schema's cache explanation. The redundancy makes it less crisp than it could be.

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

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

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

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

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

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

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

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

The description opens with a specific verb and resource — 'List a Facebook Page's events' — and adds the distinguishing output fields (local startDate, timezone, venue). This makes it clearly distinguishable from siblings like facebook_event_search (general event search) and facebook_event_details (details of a single event).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's cache and credit mentions largely restate what the schema's cache and limit descriptions already say ('0 credits on hit', 'Flat 2 credits per call'). The accessibilityCaption note is output semantics rather than parameter meaning, so the description adds little beyond the schema baseline.

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

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

The description clearly identifies the resource—'Photo grid from a Facebook Page'—and specifies the output contents (image URL plus accessibilityCaption). It is easily distinguished from siblings like facebook_profile_posts, facebook_profile_reels, and facebook_details because it is the only photos-oriented Facebook tool. However, it lacks an explicit verb ('Retrieves'/'Fetches'), phrased as a noun phrase rather than a specific verb+resource construction.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, and the schema already documents url, cache, and limit in substantial detail, including timing caps and truncation behavior. The description mostly repeats the cache guidance and does not add meaningful parameter semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: 'Latest posts and Reels from a Facebook page.' This accurately states what the tool returns. It does not explicitly differentiate it from sibling tools like facebook_profile_reels or facebook_page_details, so it stops short of a 5.

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

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

There is no guidance on when to use this tool instead of related siblings such as facebook_profile_reels, facebook_profile_events, or facebook_page_details. The cache and credit guidance is operationally useful, but it does not help an agent decide between this tool and its alternatives.

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

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

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

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

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

The description is two sentences with zero filler. The core purpose and output characteristics are front-loaded, followed by cost and cache guidance. Every clause earns its place.

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

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

For a simple list tool with 3 fully documented parameters and no output schema, the description is complete: it covers what data is returned, the ordering, filtering behavior, cost, failure handling, and cache options. An agent has everything needed to call it correctly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives operational guidance about caching and cost, but it does not say when to use this tool versus sibling alternatives like facebook_details, facebook_comments, or video_summarize. There is no when-to-use or when-not-to-use framing for tool selection.

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

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

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

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

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

The description is compact, front-loaded with the core purpose, and every clause earns its place: typed payload, ceiling, credits, failure charging, and cache behavior. There is no filler or repetition beyond what the context requires.

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

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

Given the moderate parameter complexity and absence of an output schema, the description is mostly complete: it explains what events are returned, gives payload examples, notes the ceiling, and covers costs and caching. It could be slightly stronger by outlining the response shape or pagination contract, but the essential operational details are present.

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

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

Schema coverage is 100%, so the schema already documents all four parameters thoroughly. The description mostly restates what the schema says (limit's 90 max, cache being free, 24h cache), adding little new semantic meaning beyond emphasizing the overall ceiling and billing context.

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

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

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

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

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

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

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

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

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

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

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

The description is compact and front-loaded with the core purpose. However, 'longestStreak (2 credits)' followed by 'Costs 2 credits' creates minor ambiguity about whether the 2 credits refers to the longestStreak field or the entire call, which costs a little clarity.

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

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

For a simple two-parameter tool, the description covers the essential operational context: cost, caching, failure charging policy, and a rough sketch of the return shape. It does not explicitly route the agent to a sibling for profile data or describe all output details in the absence of an output schema, but the needed info for a correct call is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates the cache parameter's behavior ('cache=true for a free 24h cache hit') and mentions username indirectly through the tool's purpose, but it does not add meaningful detail beyond what the input schema already documents.

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

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

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

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

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

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

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

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

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

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

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

Every sentence earns its place: result shape, pricing and pagination warning, and cache/failure billing. The description is compact, front-loaded with the core purpose, and contains no filler.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is short and front-loads the core purpose. There is some minor redundancy in the pricing statements ('same card and ~0.1/row pricing' followed by 'Costs ~3 credits (0.1/result)'), but the overall length is appropriate and every sentence contributes useful information.

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

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

For a simple list tool with a complete schema, the description is mostly adequate but leaves gaps: it does not mention what the response contains beyond 'accounts', lacks an alternative differentiation, and with no output schema, an agent might benefit from a note about pagination or result structure. The cost and cache details are helpful but not sufficient for full context.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not add new parameter semantics beyond what the schema already provides; it only reinforces the cache behavior already described in the schema.

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

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

The description states the resource clearly: 'Accounts a user follows,' which unambiguously identifies the following list. It does not use an explicit verb like 'list' or 'return', and while it mentions followers for pricing, it does not explicitly contrast itself with the github_followers sibling tool.

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

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

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

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

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

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

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

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

The description is tightly packed and front-loaded: the action and resource come first, followed by return hints, cost, and caching. Every sentence earns its place and there is no redundant restatement of schema fields.

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

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

With no output schema and no annotations, the description communicates the essential return fields, pagination cursor behavior, cost model, and cache behavior. It could be more explicit about response envelope or error handling, but the information needed to invoke it correctly is present.

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

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

Schema coverage is 100%, setting the baseline at 3. The description adds value beyond the schema by clarifying that the cursor is an opaque GitHub Link token, that state is echoed as data.state, that cache=true yields a free 24h hit, and that billing is per result.

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

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

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

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

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

The description implies usage context: call it when you need pull requests for a repository, with cache and state options detailed. It does not explicitly name alternatives or say when not to use it, so guidance is adequate but leaves routing to inference.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100% and the schema itself is unusually rich (defaults, option lists, the 'Not stars' caveat, 'Not a bare page number' cursor warning, 'Echoed as data.*'). The tool description only references sort/direction/type and cache=true at a high level, adding no incremental parameter meaning beyond the baseline.

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

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

States a specific verb ('List') and a specific resource ('a user's repos'), with qualifying dimensions 'sort/direction/type'. The plural resource distinctly separates it from close siblings like github_repository (single repo) and github_trending_repositories (not user-scoped), so an agent can distinguish it without opening schemas.

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

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

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

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

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

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

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

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

The description is short and front-loads the returned fields before moving to cost and cache behavior. There is minor redundancy: 'parent when fork (1 credit)' followed by 'Costs 1 credit' re-states the credit cost. Overall, it is compact and scannable.

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

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

For a simple single-repository lookup with a well-documented input schema, the description covers the resource, key returned values, cost, failure policy, and caching. It does not explain how it relates to sibling GitHub tools, but the core information needed to invoke the tool correctly is present.

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

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

Schema description coverage is 100%, so the baseline is 3. Both parameters are already well documented in the schema, and the description does not meaningfully expand on the repo or cache parameters; it mainly restates cache cost behavior already present in the schema.

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

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

The description names a specific resource ('GitHub repo') and enumerates the data fields it returns (stars, real watchers, openIssuesAndPrs, license, parent when fork), making the purpose reasonably clear. However, there is no explicit verb like 'retrieves' or 'fetches,' and it does not distinguish itself from the sibling github_repositories, so it falls short of a 5.

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

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

The description gives operational guidance about cost and cache usage ('Pass cache=true for a free 24h cache hit (default always fresh)'), but it never states when to use this tool versus alternatives such as github_repositories, github_user, or github_activity. No prerequisites, exclusions, or selection criteria are provided.

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

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

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

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

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

The description is compact and front-loaded with the endpoint and key semantics, followed by billing/cache caveats. It is slightly redundant in stating the 2-credit cost twice, but it remains efficient and scannable.

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

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

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

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

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

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

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

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

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

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

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

The description implies when to use it (when you need trending developers, optionally filtered by since window or language), and the since/language parameters provide usage context. However, it does not explicitly state when not to use it or name an alternative such as github_trending_repositories.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives clear context for when to use this tool: when trending ranking by starsGained is desired, with an explicit exclusion of all-time star rankings. It also gives concrete cache-usage guidance (cache=true for a free hit, default always fresh). It does not explicitly name a sibling alternative or state when not to use it, so it stops short of the strongest guidance.

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

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

With no annotations, the description carries the full burden and discloses genuinely useful behaviors beyond the schema: the 1-credit cost, that empty results and failures are never charged, and the 24h cache semantics with default-always-fresh. Rate limits and error handling are not covered, but the cost/cache/billing disclosure is substantive and well beyond what structured fields provide.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the full behavioral burden, and it discloses several non-obvious traits: crediting cost, no charge on empty/failed results, 24h cache behavior, the definition of isActive, and that spend/impression ranges only appear for election ads. It stops short of covering auth or rate limits, but it is notably transparent for practical 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 and information-dense: four short sentences cover data availability, field semantics, billing, and caching. It is well-structured and front-loaded with a key caveat, though it would be slightly clearer if the core purpose statement came first.

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 operational details well—credits, caching, failure charges, and one field definition—and the schema covers all parameters. However, with no output schema and no explicit statement of what 'ad details' includes or how this tool differs from google_ad_library_company_ads, an agent is left to infer the tool's main return content and selection context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description essentially restates the cache parameter behavior that already appears in the schema and adds nothing new about creative_id or country. It does not compensate with extra semantic detail 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 never explicitly states that this tool fetches details for a single Google Ad Library ad; it jumps straight into caveats about spend/impression availability, isActive semantics, credits, and caching. The tool name and the required creative_id make the purpose inferable, but the description itself lacks a clear verb+resource 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?

There is no guidance on when to use this tool versus sibling tools like google_ad_library_company_ads or google_ad_library_advertiser_search. The only usage advice is about passing cache=true for a free cache hit, which is parameter-level, not tool-selection guidance.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses meaningful operational traits: cost is 1 credit, empty results and failures are free, caching can yield a free hit within 24 hours, and results are ranked. This goes well beyond a generic tool description, though it omits potential rate limits, error formats, or return structure.

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

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

The description is short and generally front-loaded, but it repeats credit information: '1 credit when found; empty is free' is followed by 'Costs 1 credit. Empty results and failures are never charged.' This redundancy reduces conciseness. The overall structure is readable, but the duplication wastes a sentence.

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

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

For a tool with no output schema and no annotations, the description covers cost, cache, and ranking but not the shape of returned results or when to choose this tool over similar siblings. The schema covers parameters well, but the description alone is not fully complete for an agent deciding whether and how to invoke 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 the baseline is 3. The description reinforces ranking and cache behavior, but those details are already covered by the q and cache parameter descriptions in the schema. The description adds little new meaning beyond what the input schema already provides.

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

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

The description states a clear verb and resource: 'Find Google Ads Transparency AR… entities — ranked multi-result.' It communicates that this is a search tool returning multiple ranked results. However, it does not explicitly differentiate from sibling tools like google_ad_library_ad_details or google_ad_library_company_ads, so the purpose is clear but the distinction from siblings is left implicit.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions caching and credit behavior, but does not explain when an agent should prefer advertiser_search over company_ads or ad_details, nor any exclusions or context that would route the agent correctly.

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

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

With no annotations provided, the description carries the full burden and delivers substantial disclosure: flat 2-credit cost, no charge for empty results or failures, free 24h cache hit when cache=true (default always fresh), spend/impression ranges published only for election ads, and the isActive definition (lastShown within 7 UTC days). These all go beyond what the schema states. It stops short of covering rate limits or error behavior, but this is a genuinely informative behavioral disclosure.

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

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

Five dense sentences with zero filler; each sentence carries a distinct fact (data availability, isActive rule, cost, billing, caching). The only structural flaw is leading with a caveat instead of the tool's core function, but as a behavioral note it is efficiently packed and 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 10-parameter tool with no output schema and no annotations, the description is incomplete: it never states the core operation or what the response contains (e.g., ad creatives, nextCursor pagination, default ATC sort order). Rich parameter documentation in the schema and the behavioral notes compensate partially, but the central 'what does this return and what do I do with it' is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description adds interpretive context — commercial ads omit spend/impression ranges, and isActive depends on lastShown within 7 UTC days — which helps an agent understand why response fields may be empty, but it provides no parameter-level semantics beyond what the schema already documents.

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

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

The description never states what the tool does — there is no verb+resource statement like 'lists an advertiser's ads from the Google Ad Library.' A reader must infer the core function from the tool name and the advertiser parameter. It opens with a data-availability caveat rather than a purpose statement, and does not differentiate from siblings such as google_ad_library_ad_details or google_ad_library_advertiser_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?

No guidance on when to select this tool over its siblings — google_ad_library_ad_details, google_ad_library_advertiser_search, or the facebook_ad_library_* equivalents are never mentioned. The only operational advice is about caching and billing (cache=true, 2 credits), which is cost optimization rather than tool-selection guidance. The schema's advertiser parameter points to advertiser-search, but the description itself does not.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses cost (1 credit), free 24h cache behavior, default fresh fetch, and that empty results/failures are never charged. It does not cover error conditions or rate limits, but transparently addresses the main non-obvious behaviors.

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

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

Several short, information-dense sentences that front-load the core purpose before adding cost and caching details. Every sentence contributes distinct, non-redundant 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 essentials for a simple profile fetch: identifier formats, key output fields, cost, and caching. Because there is no output schema, it relies on the Channel Details alignment to convey the response shape; this is adequate but not exhaustive. It doesn't mention auth or rate-limit context, but for this basic lookup the definition is fairly complete.

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

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

Schema coverage is 100% and already explains all three parameters in detail. The description adds value by clarifying that cache=true yields a free 24-hour cache hit and that fresh fetches are the default, which is not fully captured in the schema. This strengthens the semantic model for the cache parameter.

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

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

States a specific operation (fetch profile) by user ID or @handle, and adds schema context (aligned with Channel Details) with key fields listed. It is clear about the resource, but does not explicitly differentiate from overlapping siblings like instagram_channel_details or instagram_details.

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

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

The description gives useful operational context (credit cost, caching, charge policy) but does not say when to choose this tool over instagram_channel_details, instagram_details, or instagram_profile_search. Usage is implied by the purpose, not explicitly routed.

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

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

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

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

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

The description is compact: four short sentences, with the purpose front-loaded before operational details. Every sentence earns its place (purpose/output shape, cost, failure policy, caching). The first sentence is dense to the point of being slightly cryptic, but there is no redundancy or filler.

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

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

Given there is no output schema and no annotations, the description partially compensates by listing key output fields and operational behavior (cost, cache, failure charges). However, it leaves gaps: no explanation of what 'approx flags' or the full fixed key set means, no sibling differentiation among Instagram profile tools, and no error/rate-limit context. It is adequate but not complete.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already handles url/cache/cacheMaxAge semantics. The description adds a small extra detail for cache ('free 24h cache hit (default always fresh)') beyond the schema, but contributes nothing for url or cacheMaxAge. No compensation beyond baseline is needed.

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

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

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

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

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

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

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and does well: it states the profile must be public, explains credit cost per result, notes that empty results/failures are never charged, and clarifies cache behavior and default freshness. This goes beyond the schema's parameter-level descriptions and gives an agent realistic expectations for cost and failure handling.

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

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

The description is only three sentences, front-loads the core function and key output fields, and then packs billing and cache behavior into the remaining sentences. Every sentence earns its place; there is no filler, redundancy, or unnecessary detail.

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

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

Given there is no output schema and no annotations, the description compensates well by naming important return fields, stating the public-profile requirement, and covering cost/failure/cache behavior. It also relies appropriately on the schema for parameter details like pagination and URL format. Minor gaps remain around the exact response envelope and how failures manifest, but the essential context for calling the tool is present.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds value on top by explaining cost implications (~6 credits, 0.3/result) and the free cache-hit benefit. This helps an agent reason about limit and cache parameter trade-offs. It does not redundantly restate the parameter descriptions, so it earns a point above baseline.

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

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

The description clearly states the tool returns 'Latest posts from a public Instagram profile' and highlights key response fields (carousel children[], mediaCount, user{}). It is specific enough about the endpoint's resource and output. However, it does not explicitly contrast with closely related siblings like instagram_channel_reels or instagram_tagged_posts, so it stops short of perfect differentiation.

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

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

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

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

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

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

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

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

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

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

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

For a tool with no annotations and no output schema, the description provides a remarkably complete picture: cost, caching, pagination, resolve behavior, and failure charging. The only notable gap is the lack of any description of the returned reels data shape, which is partially mitigated by the mention of nextCursor and hasMore.

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

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

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

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

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

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

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

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

The description implies usage context by saying 'from a public Instagram profile', but it never explicitly states when to choose this tool over alternatives like instagram_reels_search or instagram_channel_posts, nor does it mention exclusions or prerequisites beyond 'public'. The guidance is clear but not directly comparative.

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

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

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

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

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

The description is compact and front-loaded: the core resource appears first, followed by short, dense operational caveats. The phrase about the 'logged-out 2-row preview... 503 SESSION_UNAVAILABLE' is cryptic, but the overall text is efficient rather than padded.

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

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

For a four-parameter, read-style endpoint with no output schema and no annotations, the description covers the main invocation concerns: session/error behavior, caching, cost, and pagination context. It does not describe the response shape, but the fully documented schema reduces that burden.

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

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

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

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

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

The description identifies the resource ('Instagram comments') and the pagination mode ('Session-paged'), and the schema's URL parameter clarifies that it operates on Instagram post/reel URLs. It does not open with an explicit verb phrase like 'Retrieves comments for...' and it does not differentiate against sibling tools, but the tool name plus schema make the operation unambiguous.

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

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

It gives actionable call guidance: pass cache=true for a free 24h cache hit, default is always fresh, and empty/failed calls are not charged. It does not name alternative endpoints or explicit exclusions, but within the Instagram sibling set there is no direct comments alternative, so the context provided is sufficient.

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

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

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

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

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

The description is two sentences with no filler. It front-loads the action and returned data, then packs cost, failure policy, and cache behavior into the second sentence. Every clause earns its place.

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

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

For a simple 2-parameter read tool with no output schema, the description compensates by listing the expected return fields and operational details like credits and caching. It is sufficient for an agent to call correctly, though it could go further by naming sibling alternatives for disambiguation.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents both url and cache semantics. The description repeats the cache behavior but adds no new parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

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

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

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

The description implies when to use this tool by scoping it to posts, Reels, and carousels, and it gives useful cache usage guidance. However, it never explicitly names alternatives or states when to prefer a sibling tool such as instagram_comments or instagram_channel_posts, so usage context is implied rather than explicitly routed.

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

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

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

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

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

Three short, front-loaded sentences with no fluff. The purpose comes first, followed by cost, failure policy, and caching behavior. Every clause earns its place.

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

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

For a low-complexity tool with two simple parameters and no output schema, the description plus schema fully covers what the tool does, how to use it, what it returns, and its operational behavior around credits and caching. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so both url and cache are already well documented. The description reinforces the cache default and cost implications, but adds no new meaning about the parameters themselves beyond the schema.

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

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

The description clearly identifies a specific deliverable: a classic Instagram embed snippet using blockquote.instagram-media and embed.js, to be dropped into a page. This distinguishes it from the many Instagram data-fetching siblings like instagram_details or instagram_channel_posts.

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

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

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

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

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

With no annotations, the description carries the full behavioral burden — and it delivers: flat 2-credit cost, free 24h cache hits, empty results/failures never charged, and the native-grid/Apify fallback mechanism. These go well beyond what the schema reveals. Minor gap: no mention of auth requirements or rate limits, and 'session-raced native grid' is jargon that an agent may struggle to interpret.

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?

Tight and front-loaded — identity first, then pricing, then cache behavior. The clear flaw is redundancy: 'Flat 2 credits. Costs 2 credits.' says the same thing twice. Otherwise every sentence earns its place; removing the duplicate would make this a 5.

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

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

For a search tool with no output schema and no annotations, the description covers pricing, caching, and failure policy unusually well, and the schema fully documents all 4 parameters. What's missing: return-value shape (what items come back), pagination, and rate limits. An agent could call it correctly but wouldn't know what to expect in the response.

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

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

Schema coverage is 100%, so the baseline is 3 — the schema already documents q's format/error code, cache's 0-credit hit behavior, limit's default of 20, and mediaType's options. The description reinforces the max-50 and cache semantics, but mostly duplicates what the schema states rather than adding new parameter 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 tool name plus 'Hashtag Explore' makes the verb+resource clear: search Instagram hashtags. The description adds execution context (session-raced native grid, Apify fallback), which gives it a specific identity. However, it doesn't explicitly distinguish itself from sibling hashtag tools like youtube_hashtag_search or tiktok_search_by_hashtag beyond the platform already implied in the name.

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

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

No guidance on when to use this tool versus alternatives. There are many search variants among siblings (instagram_profile_search, instagram_reels_search, youtube_hashtag_search), but the description never names a condition, exclusion, or alternative. It does explain cache=true usage, but that's operational detail, not tool-selection guidance.

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

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

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

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

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

The description is short and front-loads the core purpose before pricing/caching details. The only blemish is redundancy—'Flat 1 credit. Costs 1 credit.'—which keeps it from top marks.

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

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

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

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

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

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

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

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

States the resource and returned fields (id, title, cover, owner) clearly, and 'for a public profile' sets scope. However it lacks an explicit verb and does not directly distinguish itself from the sibling instagram_highlights_details, so it falls short of a 5.

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

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

The description implies this is for retrieving a profile's highlight albums and gives clear context (public profile, cache behavior), but it never states when to choose this tool over the similar instagram_highlights_details or other Instagram tools. No exclusions or alternatives are mentioned.

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

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

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

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

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

The description is short and front-loaded with the main purpose, but 'Flat 1 credit. Costs 1 credit.' is redundant repetition. The cache guidance also largely duplicates the schema, so not every phrase earns its place.

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

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

For a simple two-parameter read operation with no output schema, the description is reasonably complete: it states the input source context via the schema, the returned fields, pricing, cache options, and failure/empty-result charging behavior. It could mention how to obtain the highlight id more directly, but the schema already references /v1/instagram/highlights.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description mostly restates the cache behavior already present in the schema, adding no significant new parameter semantics beyond the schema.

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

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

The description clearly identifies the resource: items inside one Instagram Story Highlight album, and names the returned data (media URLs, type, takenAt). The word 'one' distinguishes it from the sibling tool instagram_highlights, which lists highlight albums themselves.

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

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

No guidance is given about when to use this tool versus alternatives such as instagram_highlights. The cache parameter is explained, but tool-selection context is absent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool costs 1 credit, that empty results and failures are never charged, and that cache=true provides a free 24h cache hit. These are important operational details beyond the schema. It does not mention auth or rate limits, but for a simple lookup tool this is reasonably 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 concise, front-loads the core purpose, and then covers cost and caching in two additional sentences. No fluff, every sentence adds value. It is well-structured and easy to scan.

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

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

For a simple 2-parameter tool with no output schema and no annotations, the description covers the essential context: what it does, what it returns (stable id, bio, links, stats), cost, cache behavior, and public scope. It lacks explicit details on output structure or error responses, but given the tool's simplicity, it is adequately 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 schema description coverage is 100%, so both q and cache are already well-documented in the schema. The description adds minimal new meaning for parameters—it repeats the cache behavior and clarifies that q is not a niche keyword search, which the schema already states. Per the baseline rule, since coverage is high, a 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 clearly states the tool resolves a brand or @handle to a single public Instagram profile and lists what it returns (stable id, bio, links, stats). It explicitly excludes niche discovery, which helps distinguish from search-like tools. However, it does not explicitly name or differentiate from other profile tools like instagram_basic_profile or instagram_details, so it is not fully distinguishing.

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: it excludes niche discovery, implying when not to use, and explains cache behavior (cache=true for free hit). However, it does not explicitly state when to choose this tool over specific alternatives, such as instagram_details for deeper profile info or instagram_search for discovery. The 'not niche discovery' note gives a clue but no explicit alternative routing.

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

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

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

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

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

The description is compact and front-loaded with the core value proposition; every sentence carries purpose or operational information. The only weakness is the cryptic 'rich music{}' notation, which is not as self-explanatory as the rest of the text.

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

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

With no output schema, the description compensates reasonably by naming expected response fields (isTrendingInClips, trendRank, rich music) and explaining cost and cache behavior. It does not fully define the shape or nesting of returned objects, but combined with a fully documented input schema it is adequate for an agent to invoke the tool correctly.

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

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

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

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

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

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

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

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

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

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: the cascade approach, flat 2-credit cost, no charge on empty results/failures, and the 24h cache behavior. It also states the default freshness. This goes well beyond the schema. However, it does not describe the response structure or potential error behavior beyond cost implications.

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 dense, but it contains redundancy: 'Flat 2 credits' and 'Costs 2 credits' repeat the same fact. It front-loads the technical 'Cascade' term, which may not be the most relevant starting point. Overall it is efficient and readable, though a tighter edit would improve it.

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 no annotations, the description omits essential information: what the returned data looks like, pagination behavior, rate limits, or any prerequisites. It explains cost and cache well but leaves the agent guessing about the actual result format and how to interpret the output. This is a significant gap for an agent trying to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats some parameter facts (max 50, flat 2 credits) but adds no new meaning beyond the schema. It does not clarify parameter interactions or provide examples. Thus it meets the baseline but does not exceed it.

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

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

The name clearly indicates searching Instagram reels, but the description focuses on the execution cascade and cost model rather than stating the tool's purpose explicitly. It never says 'searches Instagram reels by hashtag' – that is only implied by the schema's 'q' parameter and the phrase 'Android tag feed'. This is more than a tautology but leaves the agent to infer the core function.

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

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

No guidance is given about when to use this tool versus its many siblings (e.g., instagram_hashtag_search, instagram_trending_reels). The description mentions a cascade and cost details but offers no decision criteria or exclusions. An agent cannot tell from the description why to pick this tool over similar ones.

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 transparency burden and does well: it discloses credit cost, that failures and empty results are not charged, and the cache hit behavior. It could add more about failure conditions or privacy restrictions, but the current information is genuinely useful 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?

Three short sentences, each adding distinct value: core purpose, pricing/failure policy, and cache behavior. No filler or redundancy; 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 tool with no output schema and no annotations, the description adequately covers the return shape, cost, failure charging, and caching. The language parameter is left to the schema, which fully documents it. This is sufficient for an agent to select and call the tool correctly in most 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 schema already documents url, cache, and language. The description does not add meaning beyond the schema — it mostly repeats the cache behavior. This meets the baseline but does not go 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 states a specific verb and resource: 'Get an AI summary of any Instagram Reel' and defines the output as 'a short paragraph plus key points.' This clearly distinguishes it from transcript tools like instagram_transcript and from platform-specific summarize siblings like tiktok_summarize or youtube_summarize.

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

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

The description clearly communicates when to use this tool: when a concise AI summary of an Instagram Reel is needed 'without watching the video.' It also gives cost-related context that helps an agent decide, though it does not explicitly name alternatives such as instagram_transcript for verbatim text.

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 to lean on, the description fully carries the behavioral disclosure burden. It transparently covers the 1-credit cost, free handling of empty/failed results, fresh-by-default caching behavior, the free 24h cache hit path, and the staleFeed fallback when Instagram only exposes an archive.

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

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

Three tight sentences front-load the core purpose, then add cost, failure, and cache semantics without filler. Every sentence adds a distinct piece of information an agent needs before invoking 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?

For a tool with no annotations and no output schema, the description covers the essential contextual ground: what the posts are, data-quality caveats, cost, cache behavior, and the fallback case. It does not enumerate exact output fields or pagination response shape, but the schema's cursor description and the strong behavioral notes make the tool sufficiently callable.

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

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

Schema description coverage is 100%, so the schema already documents url, cache, limit, and cursor in detail. The description mostly repeats the cache behavior already present in the schema rather than adding new parameter-level meaning, so it stays at the baseline.

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

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

The description names the resource explicitly ('posts that tag an Instagram account') and adds useful distinctions such as author verified/avatar availability and the staleFeed archive fallback. This lets an agent distinguish it from sibling tools like instagram_channel_posts or instagram_hashtag_search, though it lacks an explicit operation verb like 'list' 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 use case is clear: call this when you need posts that tag an Instagram account, and the cache note gives concrete guidance on when to pass cache=true. It does not explicitly compare against sibling tools or state exclusion cases, but the context is specific enough to guide selection.

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

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

With no annotations, the description carries the full behavioral burden. It adds meaningful operational context: the 2-credit cost, no charge for empty results or failures, and the cache=true free cache-hit behavior with a default fresh fetch. This gives an agent a realistic picture of cost and side effects.