API Direct

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

Annotations already declare readOnly, openWorld and non-destructive, so safety is covered. The description adds genuinely useful operational context not in the annotations: per-request billing ($0.005), the 50-item page limit, and top-100 ranking coverage.

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

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

Four compact sentences, front-loaded with the resource and ranking types, then return fields, then limits and cost. No filler.

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

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

With no output schema, the description carries the return-value burden and does so (rank, rank change, ASIN, title, price, rating). Pagination, category scope and pricing are all covered; only an explicit alternative-tool pointer 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 all four parameters (page, type, country, category) are already documented, including the enum values and the category-doc URL. The description repeats the pagination/top-100 context but adds no parameter meaning beyond the schema. Baseline 3.

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

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

States a specific verb (Get) and resource (Amazon rankings for a category), and enumerates the five ranking types it covers. An agent can distinguish it from search_amazon_products and amazon_product_details, which retrieve products rather than category rankings.

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

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

Usage is implied by the resource's nature (rankings listings), but the description gives no explicit when-to-use or when-not-to-use guidance and never names search_amazon_products as the alternative for keyword-based product lookup. Nothing is misleading, but the routing guidance is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely new context the annotations cannot: per-request billing ($0.005) and an enumeration of returned fields (pricing, buy box/seller_id, availability, reviews). It doesn't mention rate limits or failure modes, but the cost disclosure is the key non-structural trait.

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

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

Front-loaded with the verb+key input, followed by a dense return-value enumeration, then the billing note. Every clause earns its place, though the return list is long enough to read as a run-on rather than sharply prioritized.

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 must convey return shape, and it does so thoroughly (pricing, buy box with seller_id, availability, condition, media, specs, ratings, reviews). Combined with billing and input provenance, an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 100% with only 2 params, so the baseline is 3. The description adds value by tying ASIN to its origin (search_amazon_products), which the schema does not explain, clarifying the expected input provenance beyond the raw format example.

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

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

States a specific verb ('Get') and resource ('Amazon product by ASIN') and immediately distinguishes itself from the sibling search_amazon_products by naming it as the ASIN source. An agent can tell this is a details-lookup, not a discovery tool, 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?

The parenthetical '(from search_amazon_products)' gives clear context that this tool follows a search step, which is useful routing guidance. It stops short of stating when not to use it or what to do if the ASIN is unknown/expired, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: ~16 results per page, a per-request cost of $0.005, and that the seller's total catalog size is returned alongside the products. It does not discuss auth or rate limits, but for a read-only endpoint this is solid.

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 short sentences, front-loaded with the purpose and return content, then sort options, page size and billing. Every sentence carries distinct information an agent needs; no filler.

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

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

With no output schema, the description usefully states what comes back (product objects plus catalog size) and adds pagination and cost context. The country parameter is left to the schema, and no explicit alternatives are offered, but an agent has enough to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema documents seller_id, page, country and the sort_by enum on its own. The description's mention of sort options (price, reviews, newest, best sellers) loosely echoes the enum without adding syntax or defaults, 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?

States a specific verb and resource (get the products an Amazon seller sells) scoped by seller ID, and explicitly ties itself to search_amazon_products by saying it returns the same product objects. This lets an agent distinguish it from the seller siblings (amazon_seller_profile, amazon_seller_reviews) and from the search tool without opening any schema.

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

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

Usage is implied by the purpose (browse a specific seller's catalog) and the relationship to search_amazon_products is noted, but there is no explicit when-to-use/when-not guidance or routing against alternatives like amazon_best_sellers or amazon_seller_profile. An agent must infer the selection criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new operational context: the $0.005 per-request billing cost and the full list of returned fields including the feedback time windows. No mention of rate limits or failure modes, but the billing disclosure is a valuable addition.

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

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

Two dense sentences with zero filler; the identity/scope statement is front-loaded, followed by the return payload and the cost. Every clause carries information an agent can act on.

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

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

There is no output schema, and the description compensates by enumerating the returned fields (name, logo, about, registered business name/address, rating, total ratings, positive-feedback percentage, 30/90/12-month/lifetime breakdown). Combined with the annotations covering safety and the explicit cost, 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% and both parameters are documented there, including the country default, so the baseline is 3. The description adds only that seller_id is sourced from main_buy_box.seller_id on amazon_product_details, which is a useful provenance hint but not format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Get an Amazon seller's profile by seller ID') and distinguishes itself from siblings like amazon_seller_products and amazon_seller_reviews by naming the exact entity returned. The parenthetical pointing at main_buy_box.seller_id from amazon_product_details makes the resource unambiguous.

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

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

Gives clear context for when this tool applies by telling the agent where the required seller_id comes from (amazon_product_details), which is the key prerequisite. It does not explicitly say when to prefer amazon_seller_products or amazon_seller_reviews instead, so no exclusion guidance.

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

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

Annotations already declare readOnly/openWorld/non-destructive. The description adds value beyond them by disclosing pricing ($0.005 per request) and the shape of the returned reviews, plus the existence of a sentiment surcharge. It does not cover auth, rate limits, or pagination cap behavior explicitly.

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-loaded with purpose, then filtering/pagination, then cost. No filler; every sentence conveys something actionable.

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

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

With no output schema, the description supplies the essential return fields (author, text, star rating, date, seller responded), plus pagination and billing behavior. Annotations cover the safety profile, so nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents seller_id, country, page, star_rating, and get_sentiment. The description reinforces the filter semantics and pagination loop but adds no syntax or format detail beyond the schema, 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?

States a specific verb+resource (get customer feedback on an Amazon seller) and the keying parameter (seller ID), which cleanly separates it from amazon_seller_products and amazon_seller_profile. An agent can distinguish this from siblings without opening a schema.

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

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

Gives concrete operational guidance: filter by star rating or positive/critical, and page until has_next_page is false. It does not name alternatives or state when-not-to-use, so it falls short of a 5, but the invocation context is clear.

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

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

Goes well beyond the readOnly/openWorld annotations: concurrency, per-item status and body returned in input order, a latency warning ('large batches can take several minutes'), and a cost model ('the batch call is free; each item is billed at its endpoint's normal rate'). Partial-failure semantics are implied by each item returning its own status.

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

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

Front-loads the capability and limit in the first clause, then stacks constraints, execution semantics, exclusion, latency, and billing with no filler. Every sentence carries distinct operational information.

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

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

With no output schema, the description supplies the return contract (per-item status and body, in input order), the input contract, the exclusion, and the cost/latency profile. An agent has everything needed to construct and interpret a batch call.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds value by defining what an item's params mean ('that endpoint's query parameters') and pointing to external documentation for the accepted values, plus reiterating the 1-100 bound.

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 (Run) and resource (up to 100 API Direct REST requests in one call) and immediately distinguishes itself from every sibling by describing itself as a meta-tool that mixes 'any endpoints the other tools cover'. The example (50 twitter_user_profile + 50 instagram_user_profile) makes the abstraction concrete.

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

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

Explains that items run concurrently, that batching is the point, and names an exclusion (/v1/web/ai-mode isn't supported), which steers endpoint selection. It stops short of an explicit 'use this instead of N sequential single-endpoint calls when X' rule, so the agent must infer the trigger condition.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: replies are returned up to 10 levels deep as a flat list of full posts whose in_reply_to_id points at the parent, plus a concrete cost of $0.003 per request.

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-loaded with the action and identifier rule, followed by return shape and cost. Every sentence carries distinct information with no filler.

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

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

With no output schema, the description compensates by describing the return shape (flat list of full posts with in_reply_to_id pointing at the parent), the traversal depth, and the per-request price. An agent has everything needed to call it correctly and predict 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, but the description adds the mutual-exclusivity rule ('provide exactly one' of url or post_id) that the schema itself does not state, which is meaningful invocation guidance.

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

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

States a specific verb and resource ('Get the replies to a Bluesky post') and specifies the two accepted identifiers (URL or AT URI post_id), which distinguishes it cleanly from siblings like bluesky_post_likes, bluesky_post_quotes and bluesky_post_reposts that target the same parent post.

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

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

Usage is implied by the verb and resource, and the 'provide exactly one' constraint tells the agent how to supply identifiers, but there is no explicit when-to-use/when-not guidance or named alternative for retrieving related post data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond the schema: the exact billing rate ($0.003/request) and the sentiment surcharge, plus what fields come back. Return format specifics like pagination are not addressed, but this is a single-item fetch so that gap is minor.

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

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

Three compact sentences: identification rule first, then return contents, then cost. Every clause carries information an agent needs; nothing is repeated from 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?

With no output schema, the description compensates by enumerating the returned fields (text, author, date, engagement metrics, media, link card, quoted post). Combined with the cost and the param rule, 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 coverage is 100%, so the baseline is 3. The description adds the mutual-exclusivity rule ('provide exactly one' of url/post_id) which the schema itself does not state, and surfaces get_sentiment's effect, earning credit 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?

States a specific verb ('Get') and resource ('one Bluesky post') with a clear identification mechanism (URL or AT URI). An agent can distinguish this from siblings like bluesky_post_comments, bluesky_post_likes, and search_bluesky without opening any 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 'provide exactly one' of url or post_id constraint is an explicit usage rule. However, it names no alternatives or when-not conditions (e.g., when to use this vs. search_bluesky or batch_requests), so guidance is clear but incomplete.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), so the bar is lower. The description adds genuinely valuable behavior beyond that: billing at $0.003 per page, a 50-per-page cap, and newest-first ordering, which the agent would not otherwise know.

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-loaded with the core purpose, then inputs, then return fields and cost. No wasted words; every clause carries information.

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

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

With no output schema, the description capably enumerates returned fields, pagination and billing. Params are fully documented in schema. Complete enough to call correctly, though it doesn't note whether more than one of url/post_id is rejected or takes precedence.

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. However, the description adds the mutual-exclusion rule ("provide exactly one" of url or post_id), which is a real constraint not stated in the schema, giving it value 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?

States a specific verb and resource: "Get the users who liked a Bluesky post, newest first." The direction of the relationship is unambiguous, distinguishing it from siblings like bluesky_user_likes (posts a user liked) or bluesky_post_reposts.

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 a usage constraint on inputs ("by URL or AT URI post_id (provide exactly one)"), which is useful, but gives no guidance on when to prefer this tool over alternatives and no explicit exclusions. Implied usage only.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond them: page size cap (50), newest-first ordering, returned fields, and per-page billing at $0.003, which matters for an agent managing cost. No pagination token or rate-limit detail, but nothing is misstated.

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 tightly packed sentences that front-load the operation and input constraint, then the return contents, ordering, page cap and price. Every clause earns its place with no filler.

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

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

With no output schema and 100% schema coverage, the description must explain returns and it does (text, author, engagement metrics, media), plus pagination, ordering and billing. An agent has everything needed to invoke and budget the call 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 parameters are already documented; the baseline is 3. The description adds the mutual-exclusivity rule ('provide exactly one' of url/post_id) that the schema does not state, which is meaningful semantic value.

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

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

Specific verb+resource: retrieves posts that quote a given Bluesky post, ordered newest first. It clearly distinguishes itself from siblings like bluesky_post_comments, bluesky_post_likes and bluesky_post_reposts, which return different engagement sets.

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?

States the input constraint clearly: provide exactly one of URL or AT URI post_id, which routes the caller correctly. No explicit when-not or named alternative, but the context is unambiguous for 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?

Annotations already cover the safety profile (readOnly, non-destructive, open world). The description adds genuinely useful behavior beyond them: newest-first ordering, a 50-per-page cap, and a per-page billing rate of $0.003, which matters for cost-aware callers. It stops short of pagination/cursor behavior, but the disclosure is strong.

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

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

A single tight paragraph that front-loads the purpose, then the return payload, then the cost/limit constraints. Every sentence carries information; 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?

No output schema exists, but the description enumerates the returned fields (handle, display name, DID, bio, verification, profile picture, join date), plus page size and billing. An agent has everything needed to invoke and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule ('provide exactly one' of URL or AT URI post_id) that the schema does not express. This is meaningful semantics beyond the structured fields.

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 ('Get the users who reposted a Bluesky post'), names the ordering ('newest first'), and is clearly distinguishable from siblings like bluesky_post_likes, bluesky_post_quotes, and bluesky_post_comments. An agent can select this 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?

Usage is implied by the precise name and the 'provide exactly one' input constraint, so an agent knows the context. However, there is no explicit when-to-use/when-not guidance and no routing to alternative sibling tools (e.g. quotes or likes) for adjacent questions.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: newest-first ordering, 50-per-page pagination, and per-page billing ($0.003), which an agent needs for cost/scope decisions.

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

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

Four tight sentences with zero waste; the core purpose and identifier constraint are front-loaded, followed by return fields, pagination, and cost. 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?

With no output schema, the description usefully enumerates return fields (handle, display name, DID, bio, verification, picture, join date) and covers pagination and billing. Minor omissions like rate limits or auth needs remain, but the definition is complete enough to call 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 documents the parameters well (baseline 3). The description adds value by stating the 'exactly one of username or url' exclusivity constraint, which the schema does not enforce (0 required params), directly guiding correct 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 a specific verb and resource ('Get a Bluesky user's followers'), plus the ordering ('newest first') and the accepted identifier forms (handle, DID, profile URL). This clearly distinguishes it from the sibling bluesky_user_following.

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

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

Gives clear context on how to invoke it and an explicit input constraint ('provide exactly one of username or url'). It does not, however, name the alternative sibling (bluesky_user_following) or state when not to use this tool.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), so the bar is lower. The description adds genuinely useful behavioral context the annotations don't: newest-first ordering, 50-per-page cap, and $0.003 per-page billing. It stops short of describing edge cases like empty/private lists.

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 tightly packed sentences: purpose first, then inputs, then return fields, then pagination/billing. Every clause carries information and none is redundant.

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

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

For a read-only paginated list tool with no output schema, the description covers return fields, pagination limits, billing, and the input exclusivity rule. Combined with annotations that carry safety and world-openness, 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 coverage is 100%, so baseline is 3, but the description adds the mutual-exclusion rule ('exactly one of username or url') that the schema itself does not express since all params are optional. That extra input-contract detail lifts it 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?

States a precise verb+resource ('Get the accounts a Bluesky user follows') and adds ordering ('newest first') and the accepted identifier forms. It is clearly distinguishable from the sibling bluesky_user_followers, which is the inverse relationship.

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 an input constraint ('provide exactly one of username or url') and the billing/page model, but never states when to use this versus alternatives such as bluesky_user_followers or bluesky_user_profile. Usage is implied by the verb rather than explicitly guided.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive). The description adds meaningful behavior beyond them: pagination cap ('Up to 50 per page'), cost ('Billed $0.003 per page'), and the shape of returned data including liked_at. Auth/rate-limit behavior is still unstated.

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

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

Front-loaded with the primary action, then ordering, identification, return shape, pagination, and cost. Every clause carries information; nothing is wasted or redundant.

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

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

For a read-only listing tool with full schema coverage and no output schema, the description covers return contents (full post + liked_at), ordering, page size, cost, and the input constraint. 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 coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity constraint (exactly one of username or url) that the schema (0 required params) does not express. That is genuine added semantic value over the structured fields.

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 ('Get the posts a Bluesky user liked') plus ordering ('newest first') and identification methods. The 'liked' framing inherently separates it from siblings like bluesky_user_posts (authored) and bluesky_post_likes (who liked a post).

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 an input constraint ('provide exactly one of username or url') but no when-to-use guidance or explicit alternatives. Use versus siblings like bluesky_user_posts is only implied by the resource name, so this lands at minimum-viable.

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

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

Annotations already cover readOnly/openWorld/non-destructive, but the description adds genuinely non-derivable behavior: pinned-post-first then newest-first ordering, up to 50 posts per page, and $0.003 per-page billing. Cost disclosure is especially valuable and is not in any structured field.

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

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

One dense sentence plus a short returns/pricing clause; the input constraint is front-loaded, ordering and output shape follow, and pricing closes. No filler.

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

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

With no output schema, the description carries the return burden and does so: post text, engagement metrics, media, link cards, quoted posts, and is_reply/is_repost/is_pinned flags, plus pagination and cost. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description earns a bump by adding the mutual-exclusivity rule ('exactly one of username or url') that the schema does not express. Per-page billing semantics reinforce the pages 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 verb and resource ('Get a Bluesky user's feed') and scopes the content precisely: posts, replies, reposts, with ordering. It implicitly distinguishes itself from post-level siblings like bluesky_post_details, but never names an alternative, so an agent must infer the boundary.

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

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

The parenthetical 'provide exactly one of username or url' is a real input constraint, but there is no when-to-use guidance versus siblings such as bluesky_user_profile, search_bluesky, or bluesky_user_likes. Usage is implied rather than stated.

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

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

Annotations already cover readOnly, openWorld, and destructive=false, so the safety profile is handled. The description adds genuinely non-structured context: the exact response fields returned and the per-request billing cost ($0.003), which an agent needs for cost-sensitive planning.

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

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

A single compact paragraph, front-loaded with the action and accepted inputs, followed by return fields and pricing. The enumeration of return fields is slightly long but each item is informative, so no sentence is wasted.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it also discloses the identifier exclusivity constraint and the billing rate. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule ('provide exactly one of username or url') that is not expressed in the schema itself. This is meaningful semantic value beyond the field-level 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?

States a specific verb (Get) and resource (Bluesky user's profile) plus the accepted identifier forms (handle, DID, profile URL). It is clearly distinguishable from siblings like bluesky_user_followers, bluesky_user_posts, or search_bluesky_users.

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

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

The description gives a real constraint ('provide exactly one of username or url'), which is useful operational guidance, but it never states when to choose this tool over search_bluesky_users or the other Bluesky profile-adjacent siblings. Usage is implied by the profile-lookup framing 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?

Annotations already declare readOnly/openWorld/no-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the exact returned fields and the per-request cost ($0.008), which is a meaningful behavioral trait for a billed API. It stops just short of describing rate limits or failure modes.

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-loaded with the core action, followed by return values and the chaining/cost notes. Every sentence earns its place with no filler.

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

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

With no output schema, the description compensates by enumerating returned fields and the downstream handoff, plus billing cost. For a single-parameter read tool, an agent has everything needed to call it correctly and use the result.

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

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

Schema description coverage is 100% for the single 'url' parameter, so the schema documents it fully. The description only restates 'by URL' and adds no format or syntax detail beyond what the schema provides. 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 ('Get') and resource ('Facebook group') with the input modality ('by URL'). Clearly distinguishes itself from siblings like facebook_group_posts and facebook_page_details by name and resource type.

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

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

Provides clear workflow guidance: 'Pass the group ID to facebook_group_posts,' which tells the agent how this tool chains into the next step. It does not state explicit when-not conditions or compare against alternatives like search_facebook_pages, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: what is returned (post text, author, engagement metrics, media) and the per-page pricing of $0.008, which matters for a paged, billable endpoint.

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

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

Three short sentences, each earning its place: purpose and ID source first, then return contents, then sorting and cost. Nothing is padded and the most important routing 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?

With no output schema, the description compensates by enumerating what is returned, and it covers the input prerequisite, sorting choice and billing model. 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%, including enums, defaults and the per-page billing note for 'pages', so the schema carries the parameter burden. The description adds little parameter-level detail beyond restating sort options and the page-based billing already documented in the schema.

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

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

States a specific verb and resource ('Get posts from a public Facebook group') with the key scoping detail that the group must be public and identified by numeric ID. It distinguishes itself from facebook_group_details by naming it as the source of the ID, and the 'group' vs 'page' framing separates it from facebook_page_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?

Gives clear prerequisites: the group must be public and the group_id must be numeric, sourced from facebook_group_details. It also documents sort options and billing behavior, but never states when to use this versus search_facebook_posts or how it differs from facebook_page_posts.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context the annotations cannot express: a per-request price of $0.008, and the fact that the response carries downstream identifiers other tools depend on. It omits error behavior for invalid or missing pages.

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

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

Two sentences, zero filler. The core action and returned fields are front-loaded, and the billing note is placed last where it does not obstruct the primary 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?

There is no output schema, and the description compensates well by enumerating the returned fields and the cross-tool identifiers. Pricing is disclosed. What remains missing is failure behavior (invalid URL, page not found, rate limiting), a minor gap for a single-parameter read tool.

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

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

One parameter at 100% schema coverage, so the schema already documents the url argument and gives an example. The description adds no syntax, format, or validation detail beyond the schema, which is the expected baseline when structured data does the work.

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

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

Specific verb+resource ('Get a Facebook page by URL') plus an explicit enumeration of what is returned (name, page_id, follower/like counts, categories, contact info, rating, verification status). This clearly separates it from search_facebook_pages and the sibling facebook_page_posts/photos/reels tools.

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

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

No explicit when-to-use vs search_facebook_pages, and no prerequisite that a page URL must already be known. The description does imply usage by noting the returned delegate_page_id and reels_page_id are required by facebook_page_videos and facebook_page_reels, which is a useful chaining signal but not full guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only, external nature is covered. The description adds the billing rate ($0.008 per page), which is useful cost context not in annotations. It doesn't describe rate limits, pagination, or return structure beyond listing what's returned.

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 compact sentences that front-load the action and resource, then add return details and billing. No wasted words, though it could be slightly more front-loaded on the ID source.

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 annotations cover the safety profile and the schema covers parameters, the description adds billing and ID source context. It's largely complete for a simple read operation, though pagination behavior when requesting multiple pages isn't described.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description adds no syntax or format details beyond what the schema provides, making the baseline 3 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 ('Get photos') and resource ('from a Facebook page') with the required identifier. Distinguishes from siblings like facebook_page_videos and facebook_page_posts by naming the media type and the ID source.

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 usage by specifying the page ID comes from facebook_page_details, which is useful routing. However, it doesn't state when to use this versus other page media tools or what prerequisites exist beyond the ID source.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful non-schema context: the $0.008 per-page billing rate and the fact that results include engagement metrics and reaction breakdowns. It does not mention pagination or rate limits, keeping it short of a 5.

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

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

Three tight sentences: what it does, what it returns, the optional filter, and the cost. Nothing is wasted and the core purpose plus the pricing signal 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?

With no output schema, the description carries the return-value burden and does so (post text, engagement, reactions, media). Annotations cover the read-only/open-world safety profile, parameters are fully documented in the schema, and the cost model is disclosed — 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 baseline is 3 and the schema already documents pages, page_id, start_date, end_date and get_sentiment. The description still adds meaning by tying page_id to its origin tool and reiterating that date filtering is optional, plus the per-page billing linkage — modest but real value beyond the schema.

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

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

States a specific verb and resource ('Get posts from a Facebook page'), pins the input to a numeric page ID sourced from facebook_page_details, and enumerates the returned content (post text, engagement metrics, reaction breakdown, media). This cleanly separates it from siblings like facebook_group_posts, facebook_page_photos, facebook_page_reels, and search_facebook_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?

Gives clear context: fetch posts for one known page, optionally narrowed by date range, with the page ID obtained from facebook_page_details. It does not name exclusions or alternatives (e.g., search_facebook_posts when the page is unknown or keyword search is wanted), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context not present in the annotations: per-page billing at $0.008 and the fact that pages are billed per fetched page. It does not cover pagination or rate limits, so it stops short of a 5.

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

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

Three short sentences, zero filler, with the core action and identifier front-loaded before the return and cost details. Every sentence contributes something distinct.

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

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

With no output schema, the description carries the return-value burden and does so briefly ('reel metadata and engagement metrics'), and all parameters are documented via the schema. The picture is adequate, though a note on result volume/pagination would close the remaining 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 schema already documents all three parameters including the billing note on 'pages' and the sentiment surcharge on 'get_sentiment'. The description's only parameter-adjacent detail (the id origin) is already echoed in the schema, so it adds little 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?

The description states a specific verb and resource ('Get reels from a Facebook page') and names the required identifier and its source endpoint, so an agent knows exactly what is produced. It does not explicitly contrast itself with nearby siblings such as facebook_page_videos or facebook_page_posts, so it falls short of a full 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 parenthetical '(from facebook_page_details)' implies a prerequisite lookup step, which is useful routing context. However, there is no explicit when-to-use/when-not statement and no named alternative (e.g., use facebook_page_videos for non-reel video content), leaving usage implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by disclosing the billing model ($0.008 per page) and the returned fields (review text, recommendation status, author info), though it omits auth or rate-limit 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?

Three tight sentences, front-loaded with the core action and input source, then returns, then cost. Every sentence earns its place with no filler.

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

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

For a read-only fetch tool with no output schema, the description adequately covers the input provenance and returned content, and the pages parameter bounds are in the schema. Pagination/cost interplay could be slightly clearer, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning by specifying that page_id is numeric and sourced from facebook_page_details. It does not describe the pages or get_sentiment semantics, but those are fully documented in the schema.

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

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

States a specific verb and resource ('Get reviews of a Facebook page') and names the input source (numeric page ID from facebook_page_details), which clearly separates it from siblings like facebook_page_posts, facebook_page_photos, and place_reviews. An agent can identify this as the page-review endpoint without opening the schema.

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

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

It gives clear context by pointing out that the page_id comes from facebook_page_details, effectively routing the agent through the right prerequisite call. It lacks explicit when-not-to-use or named alternative tools, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), and the description adds value beyond them: explicit per-page billing ($0.008) and the shape of the result ('video metadata and play counts'). It stops short of pagination or rate-limit behavior.

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

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

Three short sentences, front-loaded with the core action and identifier, then return content, then cost. Each sentence carries distinct information with no filler.

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

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

With no output schema, the description usefully names what comes back (metadata and play counts) and discloses billing. For a 3-parameter, annotated read tool this is nearly complete; only pagination/volume limits are unaddressed.

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 pages and get_sentiment in detail. The description adds only the provenance hint for delegate_page_id ('from facebook_page_details'), which is a small but real addition over the schema text.

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 ('Get videos from a Facebook page') and the keying identifier (delegate_page_id), so an agent knows exactly what is returned. It does not explicitly differentiate itself from the close siblings facebook_page_reels or search_facebook_videos, which is the only gap.

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 pointing to facebook_page_details as the source of delegate_page_id, a useful prerequisite. However, it never states when to prefer this over facebook_page_reels or search_facebook_videos, so routing between near-identical siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds value beyond that with per-page billing ('Billed $0.008 per page') and an explicit enumeration of returned fields (text, author, reaction/reply counts, date, attachments). It does not disclose pagination/cursor behavior.

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

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

Three sentences, front-loaded with the core action and resource, followed by output contents and pricing. Every sentence earns its place with no filler.

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

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

With no output schema, the description usefully summarizes the return fields, and it covers the ID source, pagination range, and cost. It is nearly complete; only cursor/pagination continuity and rate-limit behavior are left implicit.

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 reinforces the pfbid-or-numeric format for post_id and ties billing to pages, but adds no syntax or meaning beyond what the schema already carries, making 3 the correct 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 and resource ('Get the comments on a Facebook post by post ID') and immediately clarifies the ID format (pfbid or numeric). An agent can distinguish it from siblings like facebook_page_posts (the post source) or search_facebook_posts without opening a schema.

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

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

Names the prerequisite workflow by pointing to facebook_page_posts, facebook_group_posts, or search_facebook_posts as sources of the required post_id, which tells the agent how to be in a position to call this tool. It stops short of stating when-not-to-use it or naming a comment-specific alternative.

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

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

Annotations already declare read-only, non-destructive, and non-open-world behavior. The description adds useful behavioral context: the playbook contains ordered tool calls and filters, inputs can be omitted to get a prompt for the user, and the operation is free.

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

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

The description is front-loaded with the core action and output, then covers invocation details and the omitted-input case. It is appropriately sized with no redundant sentences.

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

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

For a two-parameter read-only tool with no output schema, the description explains what the playbook contains, how to identify the skill, and what happens when inputs are omitted. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by noting that a human-readable skill name can be passed and close matches will resolve, while also reinforcing the omit-inputs behavior for the inputs parameter.

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

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

The description states a specific verb and resource: get one skill's step-by-step playbook, including ordered tool calls and filters. It distinguishes this from list_skills by making clear this retrieves a single playbook rather than a 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?

It explains how to supply skill_id from list_skills or a user-provided skill name with close-match resolution. It also says omitting inputs produces a list of questions for the user. It lacks explicit when-not-to-use guidance, but the context is clear.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), yet the description adds real behavioral context: pagination size (~100 comments per page), the return shape (text, author, counts, date, link, up to 5 preview replies), and per-page billing cost ($0.005). The cost and pagination disclosures are exactly the kind of thing annotations cannot convey.

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

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

Four tight sentences, front-loaded with purpose then outputs, sorting, pagination, and cost. Every sentence carries information, though the 'per page' concept is mentioned twice, slightly redundant.

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

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

With no output schema, the description carries the return-value burden and does so, listing returned fields plus the preview-replies limit. Combined with annotations covering safety and the explicit cost note, 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 coverage is 100%, so url, pages, and sort_by are fully documented in the schema itself. The description largely restates them (URL or ID, newest or relevance, ~100 per page), adding no syntax or edge-case guidance beyond the schema. Baseline 3 applies 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?

States a specific verb (get) and resource (comments on a YouTube video) with the input forms (URL or video ID). An agent can distinguish it from youtube_video_details (metadata) and social comment tools on other platforms without opening any 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 description implies the use case (fetching comments for a given video) and mentions inputs, but never states when to choose this over siblings like youtube_video_details or when not to use it. Usage is inferred from the resource, not stated.

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

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so the bar is lower, yet the description adds material context: answers 'can take over a minute' (latency) and 'Billed $0.005 per request' (cost). It also discloses the continuation mechanism, which is behavior an agent must know before calling.

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

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

Four tight sentences, front-loaded with the core action and output shape, then latency/cost/alternative. Every sentence carries information, though the output-shape parenthetical is slightly dense.

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

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

With no output schema, the description compensates by naming the return fields (reply_parts, reference_links) and covering latency, billing, and session continuation. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so prompt, country, language, and session_token are already documented in the schema. The description reinforces session_token's conversational-continuation meaning but adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Ask Google AI Mode a prompt') and enumerates the shape of the answer (reply_parts: paragraphs, headings, lists, images) plus citations. This distinguishes it cleanly from the many search_* siblings without opening a schema.

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

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

Explicitly routes the agent: 'Use search_web for plain search results,' and describes the follow-up flow via session_token. The condition selecting this tool (AI-synthesized answers vs. plain results) is stated, not implied.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: per-page billing ($0.006), empty-list return when no replies exist, and the fields returned. It doesn't cover pagination limits or failure modes, so not 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?

Front-loaded with purpose, then input rule, then return contents and billing. Dense and largely waste-free, though the enumerated return fields make it slightly long — justified since there is no output schema.

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

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

With no output schema, the description compensates by enumerating returned fields (text, author details incl. AI-label flag, like count, date, link, parent comment), plus billing and empty-result behavior. Combined with annotations, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds the cross-parameter rule that url and code are mutually exclusive and one is required — a constraint the schema does not express. It also names the source of comment_id (instagram_post_comments), aiding correct parameter population.

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 ('Get the replies to one Instagram comment') and scopes it to a single comment, clearly distinguishing it from sibling instagram_post_comments (which lists top-level comments). An agent can identify the tool's role 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?

Explains the prerequisite ('the comment_id from instagram_post_comments') and the constraint 'provide exactly one' of url or code, which tells the agent how to invoke it. It lacks an explicit statement of when not to use it (e.g., for top-level comments, use instagram_post_comments), so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the description's real value is the operational context it adds: per-page billing ($0.006/page), a ~30-posts-per-page ceiling, and deduplication across pages. It stops short of describing auth requirements or result ordering guarantees, so it is strong but not exhaustive.

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

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

Four short sentences, front-loaded with the core action, then return shape, tab selection, pagination, and cost. No sentence is redundant and the cost caveat is placed last where it belongs.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming the shared post object shape and the extra hashtag post count, plus pagination and cost. It leans on the sibling tool's definition rather than describing fields itself, which is a minor gap for a no-output-schema tool.

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

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

Schema description coverage is 100%, so all four parameters (hashtag, pages, sort_by, get_sentiment) are already documented in the schema. The description restates the tab semantics and page yield but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get Instagram posts and reels for a hashtag") and explicitly anchors itself to a sibling by noting it returns "the same post objects as search_instagram plus the hashtag's total post count." An agent can distinguish it from search_instagram and instagram_user_posts 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?

The description explains that sort_by selects the tab (top default, recent, reels), which implies usage, and the search_instagram comparison hints at differentiation. However, it never states when to prefer this tool over search_instagram or a user-posts tool, nor any exclusions or prerequisites.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond them with two operationally critical facts: media URLs expire after ~6-24 hours and each request is billed $0.006. It also enumerates the returned payload (title, cover, media URLs, post time, stickers, mentions, tags, location, audio, AI detection).

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

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

Purpose and accepted input forms come first, followed by return contents, then the two operational caveats (expiry, price). Every clause carries information, and the return-field list is justified by the absence of an output schema.

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

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

With no output schema, the description covers return values itself, and it adds the expiry and billing caveats an agent needs before calling. Nothing material is missing for a single-parameter read tool.

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

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

Schema coverage is 100% and the schema already gives ID/URL examples, so the baseline is 3; the description adds provenance by stating the ID comes from instagram_user_highlights, which helps the agent construct the argument correctly rather than guess.

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 ('Get the stories saved in one Instagram highlight') and scopes it to a single highlight, distinguishing it from instagram_user_highlights (which enumerates highlights) and instagram_user_stories (which returns current stories). An agent can select it without opening the schema.

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

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

Explicitly names the prerequisite source for the input ('from instagram_user_highlights'), which tells the agent the typical call order. It does not state when to avoid this tool or what to do if the highlight is private/expired, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/openWorld/destructive=false, so safety is covered. The description adds real behavioral context: per-page billing cost ($0.006), page/comment caps (15 per page), sort semantics (popular includes pinned), and the returned fields. It stops short of rate limits or error behavior, so not 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?

Front-loads what the tool does, then input method, return fields, sorting, pagination, sibling routing, and billing. Every sentence carries information with no 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?

With no output schema, the description fully explains the return shape (text, author with AI-generated label, like/reply counts, date, link). Combined with pagination, sort, and billing notes, 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 coverage is 100% and the schema already documents url, code, pages, sort_by (including the pinned note), and get_sentiment. The description reinforces sort and pagination but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (comments on an Instagram post or reel), plus the accepted identifiers (URL or shortcode). It is clearly distinguishable from the sibling instagram_comment_replies, which it explicitly routes replies to.

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

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

Names the alternative explicitly ('Use instagram_comment_replies for a comment's replies') and the condition that selects it, plus the constraint to provide exactly one of url/code. The routing to the sibling is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds valuable behavior beyond them: per-request billing at $0.006 and an extensive enumeration of the returned fields. It stops short of mentioning auth or rate-limit 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 sentences, both front-loaded with the essential scope and input constraint, then the return inventory and price. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly (counts, media, carousel, audio, tags, location, author, AI label). Input constraints and cost are both covered, leaving no material gap for calling the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents url, code, and get_sentiment. The description contributes the mutual-exclusivity rule ('provide exactly one'), which the schema does not state and which incidentally explains the otherwise odd zero-required-parameters shape.

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 (Get) and resource (one Instagram post, reel or IGTV video) and names the accepted identifiers (URL or shortcode). An agent can immediately distinguish this single-item fetch from the sibling listing/comment/like tools 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 description constrains input ('provide exactly one' of URL or shortcode), which is genuine usage guidance. However, it never says when to prefer this over siblings like instagram_post_comments, instagram_post_likes, or instagram_user_posts, so routing guidance is only implied.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the bar is lower. The description goes beyond them by disclosing the return cardinality ('typically several hundred'), that it is a single request, and the exact billing cost ($0.006 per request) — genuinely useful operational context.

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

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

Two tightly packed sentences, front-loaded with the verb and resource; the exclusivity constraint, return shape, and cost all appear without filler. 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?

With no output schema, the description carries the burden well by enumerating returned fields (username, full name, user ID, verification/privacy, picture) and the total like count. It stops short of describing failure modes or result caps, but is adequate for a two-param read tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a real constraint not encoded in the schema: the two parameters are mutually exclusive and exactly one must be supplied, which meaningfully changes how an agent builds the call.

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 ('Get the users who liked an Instagram post or reel') and narrows scope with the URL/shortcode input modes. An agent can distinguish it from instagram_post_comments and instagram_post_details 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 description gives an input constraint ('provide exactly one' of URL or shortcode), which is useful, but never says when to choose this tool over the adjacent siblings (post details, comments) or what prerequisites/auth apply. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is clear. The description adds substantial behavioral context beyond annotations: billing cost ($0.006 per page), a verified-account cap (first ~50 followers, later pages not billed), and query-mode billing rules. This is rich transparency about cost and edge-case 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 a single, front-loaded paragraph that moves from purpose to return fields to pagination/billing to the query alternative. It is dense but every sentence carries useful information. Slightly packed, but no wasted words.

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

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

Given the tool's complexity (two input modes, pagination, billing, verified-account limits) and the absence of an output schema, the description covers return fields, pagination, cost, and special cases. Annotations cover safety, and schema covers parameters. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it enforces 'provide exactly one' of username or URL, and clarifies that query mode returns up to 50 matches billed as one page (schema notes pages is ignored but the description ties it to billing). These additions earn a 4.

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

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

States a specific verb and resource: 'Get an Instagram user's followers by username or profile URL.' The resource is unambiguous and clearly distinct from siblings like instagram_user_following, which the name itself already differentiates. No ambiguity about what the tool does.

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 parameter-level usage ('provide exactly one' of username/url) and an in-tool alternative ('Pass query to search the followers instead'), but does not state when to use this tool versus external alternatives like instagram_user_following or search_instagram_users. Usage is implied by the name and description but no explicit when/when-not 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?

Annotations cover only the safety profile (readOnly, openWorld, non-destructive), and the description adds substantive behavior beyond that: page size (50 accounts), per-page billing ($0.006), the fact that query is billed as one page, and that pages is ignored when query is set. It also enumerates the returned fields, which matters because there is no output schema.

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

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

Three sentences, each carrying distinct load: identification rule, return shape, then the query-override and pricing caveat. Front-loaded with the primary action and free of filler.

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

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

With no output schema, the description supplies the return field list; with four parameters and no required ones, it supplies the mutual-exclusion rule; and it discloses pricing and pagination. 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 baseline is 3, but the description adds cross-parameter semantics the schema does not state: the exactly-one constraint between url and username, and the override relationship where query causes pages to be ignored. Format details like the 500/100-character limits remain schema-only.

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

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

States a specific verb (Get) and resource (the accounts an Instagram user follows) with the two accepted identifier forms. It is clearly distinguishable from the sibling instagram_user_followers, which is the inverse relationship.

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?

Explicitly says to provide exactly one of username or profile URL, and routes the agent to the query mode for searching within the list rather than fetching it whole. It does not, however, name sibling alternatives such as instagram_user_followers or search_instagram_users for the case where the target account is unknown.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new operational context: the $0.006 per-request billing and the exact shape of the returned highlight fields, which the annotations cannot convey.

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

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

Three tight sentences: purpose first, then the two input forms and constraint, then downstream routing and cost. No filler, and every clause carries information.

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

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

No output schema exists, but the description enumerates the return fields (ID, title, story count, cover image, dates, link), so an agent knows what to expect. Combined with the billing note and sibling routing, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity constraint ('provide exactly one') that the schema itself does not express. That is real semantics beyond the structured fields.

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) plus resource (an Instagram user's story highlights) and names both accepted input forms. It is clearly distinguishable from siblings such as instagram_user_stories and instagram_highlight_stories.

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?

Specifies the 'provide exactly one' selection rule between username and URL, and explicitly routes downstream work to instagram_highlight_stories for the stories themselves. No explicit when-not-to-use guidance, but the alternative is named with its condition.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower. The description earns credit by disclosing operational traits annotations cannot: 'Up to 12 posts per page' and 'Billed $0.006 per page', which directly affect how an agent sizes the 'pages' argument.

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

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

Three dense sentences with no filler: the retrieval scope, the required one-of input rule, the returned fields, and pagination/cost all arrive in the first read-through. Nothing repeats the name or title 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?

For an open-world read tool with no output schema, the description enumerates the returned payload (captions, engagement metrics, author metadata, hashtags, mentions, AI label), pagination limits, and cost. Inputs, outputs and pricing are all covered, leaving nothing an agent needs for a correct call.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the mutual-exclusivity rule between 'username' and 'url' ('provide exactly one') that the schema does not express via required fields or oneOf. It also restates the per-page volume that maps to the 'pages' parameter, mildly strengthening the schema's own text.

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 ('Get an Instagram user's recent posts and reels (their feed)') and scopes it to user-level retrieval, which cleanly separates it from siblings like instagram_hashtag_posts, instagram_post_details and search_instagram. An agent can identify the target resource 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?

'By username or profile URL (provide exactly one)' gives a concrete usage constraint that selects the correct input path. It does not, however, name when to prefer this over alternatives such as instagram_user_stories or instagram_hashtag_posts, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly, non-destructive, open-world behavior, so the safety profile is covered. The description goes beyond them by enumerating the returned fields and disclosing the $0.006 per-request billing, which is genuinely useful cost context an agent cannot get from annotations.

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

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

Front-loaded with purpose, followed by return fields and cost. The field enumeration is somewhat long but each item is informative and the sentences earn their place.

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

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

With no output schema, the description compensates by listing return values, and annotations cover the safety profile. Input constraints and cost are present; only explicit alternative-routing is missing, leaving the definition near-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% (baseline 3), but the description adds the mutual-exclusivity constraint ('provide exactly one') that the schema does not express, since both parameters are optional with no required field. This is meaningful semantics beyond the structured schema.

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

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

Specific verb (Get) plus resource (an Instagram user's full profile), with the accepted input forms (username or profile URL) stated up front. It is clearly distinguishable from siblings like instagram_user_posts, instagram_user_followers, and search_instagram_users.

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 'provide exactly one' rule gives a useful input constraint, but the description never states when to choose this tool over alternatives such as search_instagram_users or instagram_user_followers. Usage is implied by the purpose 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?

Annotations cover the read-only/safe profile, and the description adds substantial context beyond them: story fields returned, media URL expiry window (6-24h), empty-list behavior when no stories are active, and per-request billing ($0.006). These are exactly the operational traits an agent cannot infer from structured fields.

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

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

Front-loaded with purpose and input rule, then the return contents, expiry caveat, empty-list behavior, alternative tool, and cost. Every sentence carries distinct, non-redundant information with no filler.

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

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

With no output schema, the description steps in to describe return fields and edge cases, and it covers input constraints, expiry, empty results, alternatives, and pricing. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the mutual-exclusivity rule ('provide exactly one'), which the schema does not express since both params are optional and unconstrained. That constraint meaningfully shapes correct 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 a specific verb (Get), resource (Instagram user's active stories), and scope (last 24 hours), plus the two accepted input forms. It names the sibling instagram_user_highlights for saved stories, letting an agent distinguish it without opening another schema.

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

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

Gives an explicit input selection rule ('provide exactly one' of username or URL) and routes to the correct alternative (instagram_user_highlights for saved stories). Conditions for use and for switching tools are both stated.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: per-request billing ($0.006) and the exact shape of the return (name, employees, industry, locations, similar companies), which the annotations do not provide.

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

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

Three short sentences, zero filler, front-loaded with the core action and return contents, followed by the sibling routing and cost note. 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?

With no output schema, the description compensates by listing the returned fields, and it adds cost and routing context. For a single-param read tool with full annotation coverage, nothing an agent needs to invoke it 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?

Single parameter with 100% schema description coverage; the schema already documents 'url' as a LinkedIn company page URL. The description's 'by URL' phrase reinforces but adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (LinkedIn company page) plus the identifying input (URL), and enumerates the returned fields. It is clearly distinguished from search_linkedin_companies, which it names as the name-based lookup alternative.

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

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

It explicitly routes the agent to search_linkedin_companies for name-based lookup, implying this tool is for when you already have a URL. It does not spell out a when-not condition beyond that, but the alternative is named with a clear selecting condition.

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

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

Annotations cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint). The description goes beyond them by disclosing return contents (post text, author, images, videos, engagement metrics), pagination granularity, and per-request pricing ($0.006) plus the sentiment surcharge — cost information an agent cannot get from structured fields.

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

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

Three tight sentences: capability first, then return payload, then pagination and cost. Every sentence carries information and nothing is padded.

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

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

With no output schema, the description correctly describes the return payload, and it covers pagination and cost. Minor gaps remain: no note on auth requirements, rate limits, or whether the URL must be a canonical full page URL, but for a simple read endpoint this is close to complete.

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

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

Schema description coverage is 100%, so the schema already documents url, page, and get_sentiment in detail. The description restates '10 posts per page' and the engagement metrics but adds no syntax, format, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource with scope qualifier: 'Get recent posts from a LinkedIn company page by URL.' This cleanly separates it from linkedin_company_details (page metadata), linkedin_person_posts (a different author type), and linkedin_post_details (single post).

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

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

Usage is implied by the resource description ('posts from a company page'), but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as linkedin_post_details for a single post or search_linkedin_companies for finding the page URL. Adequate but leaves selection to inference.

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

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

Annotations already declare the read-only, non-destructive, open-world profile, so the safety picture is covered. The description adds genuinely new behavioral context beyond the annotations by enumerating the returned fields and disclosing the $0.002 per-request billing, which an agent cannot derive from structured 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?

Two sentences, front-loaded with the action and identifier, then the payload and cost. No filler, no repetition of the title.

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

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

With no output schema, the description compensates by listing the returned fields (title, company, location, salary, benefits, full description), and it adds cost and scope. For a single-parameter read tool with rich annotations, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single 'url' parameter is fully documented in the schema, including the accepted URL format and the numeric-ID alternative. The description restates the URL-or-ID duality but adds no format or validation detail beyond the schema, 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?

States a specific verb and resource ('Get one LinkedIn job listing') and scopes it to a single record identified by URL or numeric ID, which cleanly separates it from search_linkedin_jobs. An agent can tell immediately this is the detail-fetch counterpart to the search 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 single-record phrasing implies the tool is used once a job URL or ID is already known, but it never states when to reach for this versus search_linkedin_jobs or linkedin_company_details. Usage is inferable from the name and scope rather than spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real operational context: the billing rate ($0.006 per request) and a full enumeration of returned profile sections, which tells the agent what to expect without an output schema.

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

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

Two tightly packed sentences: the return contents are front-loaded, the sibling routing and pricing follow. Every clause carries information and nothing is wasted.

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

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

No output schema exists, yet the description inventories the returned fields thoroughly, names the alternative for posts, and discloses per-request cost. For a single-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

With one parameter and 100% schema description coverage, the schema already documents that url accepts a profile URL, public slug, or member URN. The description repeats those accepted identifier forms without adding syntax examples, validation rules, or fallback behavior, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (a LinkedIn person's profile) and enumerates the returned sections, so the agent knows exactly what this returns versus sibling tools like linkedin_company_details or linkedin_job_details. It is clearly distinguishable from linkedin_person_posts, which it names explicitly.

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

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

Directs the agent to linkedin_person_posts for a person's posts, which is a useful exclusion among many LinkedIn siblings. However, it gives no guidance on when to reach for this versus search_linkedin or search_linkedin_companies, so the routing is only partially covered.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: pagination limits (20/page, ~600 max), what data classes are returned, and billing at $0.006 per request.

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-loaded with what is retrieved, followed by return contents, pagination caps, alternative routing, and cost. No filler.

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

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

With no output schema and only three parameters, the description covers everything an agent needs: input form, return payload contents, pagination ceiling, alternative tool for keyword filtering, and cost. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents url, page (1-30), and get_sentiment. The description restates the URL-or-slug input and page ceiling but adds no new parameter semantics and never mentions get_sentiment or the sentiment surcharge. Baseline 3 applies 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?

States a specific verb (Get), resource (recent posts a LinkedIn person authored), and an input mode (profile URL or public slug). It is clearly distinguishable from linkedin_company_posts and linkedin_post_details, since it scopes to a person's authored 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?

Explicitly routes keyword filtering to a sibling: "Use search_linkedin with author to filter a person's posts by keyword." That is strong alternative guidance, though it does not state when-not to use this tool (e.g. versus linkedin_post_details for a single post).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: it discloses the per-request cost ($0.002) and enumerates the return payload (full text, author details, images, links, engagement metrics with reaction breakdowns). It does not cover auth or rate limits, but the added cost and return detail justify a 4.

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 are front-loaded: purpose, return payload, then billing. Each sentence adds distinct information and none is redundant, making it appropriately sized for 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?

With no output schema, the description carries the return-value explanation and does so by listing the key fields an agent will receive. It also states the cost, so an agent can call the tool knowing the price and expected output. The only omission is sentiment behavior, but that is fully specified in the input schema.

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

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

Schema description coverage is 100%, so both url and get_sentiment are fully documented in the schema. The description adds only 'by URL,' which the schema already conveys, and says nothing about get_sentiment. Baseline 3 applies 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 names a specific verb and resource ('Get one LinkedIn post by URL') and scopes it to a single post, which differentiates it from sibling list/search tools like linkedin_person_posts and search_linkedin. It also enumerates the returned data, reinforcing what the tool is for.

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

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

Usage is only implied by the purpose: use when you have a LinkedIn post URL and need full details. There is no explicit statement of when to choose this over search_linkedin or linkedin_person_posts, and no exclusions or prerequisites are given.

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

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

Annotations already declare the read-only, non-destructive profile, so the bar is lower; the description still adds useful context by enumerating the returned fields and noting the tool is 'Free'. It does not mention pagination or result-size behavior, but for a simple list tool this is strong additive context with no contradiction.

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

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

Front-loads the core purpose, then adds outcome categories, return fields, usage, and cost in tight succession. It is dense and slightly list-heavy but every clause carries information; nothing is padded.

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

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

With no output schema, the description compensates by naming the returned fields (id, name, category, summary, inputs), and it covers purpose, selection conditions, follow-up tool, and cost. An agent has everything needed to decide and call.

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

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

Schema coverage is 100% and there is a single optional parameter already fully documented, so the baseline is 3. The description's 'filters such as author_title, mentions_company and AI sentiment' refer to the skills' inputs rather than this tool's category parameter, so it adds no syntax or semantics for the parameter itself.

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 ('List API Direct's ready-made skills: playbooks that chain the data tools') and explains what a skill is, which no sibling name conveys. It is clearly distinguishable from the many raw data tools and from get_skill, the companion that runs a chosen skill.

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?

Explicitly says when to use it ('when a request matches one of those goals') and names the next step and alternative ('then run the chosen skill with get_skill'). The routing to get_skill leaves nothing to inference.

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

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

Annotations already declare readOnly, open-world and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: the exact billing cost ($0.003 per request) and the breadth of returned data, though it omits any rate-limit or error/empty-result 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?

Purpose is front-loaded, followed by the return inventory and then the billing note, so nothing critical is buried. The long enumerated return list is dense but each item is relevant given there is no output schema.

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

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

With no output schema, the description properly carries the return-value burden by enumerating the fields returned, and it adds a cost signal. It is complete enough to call correctly, though it never states auth/API-key requirements or the shape of error responses.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning for the required parameter by disclosing its origin (from search_places). The optional country/language flags are left to the schema and get no extra explanation in the text.

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 ("Get a Google Maps place by place_id") and immediately disambiguates from its siblings place_photos, place_reviews and search_places by naming the upstream source of the id. An agent can tell exactly what this 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 parenthetical "(from search_places)" tells the agent where the required place_id must come from, effectively instructing it to search first. However, it does not explicitly say when to prefer this over place_photos or place_reviews, so a small inference gap remains.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description goes further by disclosing cost ($0.01 per page), pagination limits (10 items per page), and a data-shape gotcha (photos and videos come mixed, filter on type). This is exactly the behavioral context annotations cannot convey.

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

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

A single dense sentence front-loads the action and resource, then appends only decision-relevant facts (return fields, mixed media caveat, page size, cost). No filler.

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

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

With no output schema, the description carries the return-value burden and does so ('standard and large URLs, coordinates and capture time'), plus cost and pagination. An agent has everything needed to call it correctly and predict the cost.

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

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

Schema description coverage is 100%, so the schema already documents place_id, pages, country, and language, including the per-page billing and item count. The description's 'up to 10 items per page' and pricing largely restate the pages schema field rather than adding new parameter semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Get photos and videos of a Google Maps place') plus the keying parameter ('by place_id'), which clearly distinguishes it from siblings like place_details, place_reviews, and search_places.

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?

Explicitly tells the agent where place_id comes from ('from search_places'), establishing the prerequisite chain, and implies usage. It does not, however, state when not to use it or contrast it against place_details for a photo-adjacent need.

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

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

Annotations already cover readOnly/openWorld/non-destructive, and the description adds genuinely new behavioral facts: billing at $0.01 per page, a hard cap of 10 reviews per page, and the non-obvious behavior that each sort_by order surfaces a different set of reviews. That last point is exactly the kind of trait an agent could not infer from structured fields.

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

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

Front-loads purpose, then layers in return fields, filtering behavior, pagination, and cost with no filler. Every sentence carries actionable information for an agent deciding whether and how to call 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?

Despite no output schema, the description enumerates the review fields returned (rating, text, author, timestamps, photos, owner response), and covers pagination, cost, filtering, and sorting. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that each sort_by order yields a different review set (schema only says 'Sort order') and clarifies the language filter behavior. The billing/pagination notes for pages also add value the schema only partially covers.

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 ('Get reviews of a Google Maps place by place_id') and distinguishes itself from siblings like place_details and place_photos by naming the exact resource returned. It also routes the agent to the source of the required id ('from search_places'), so the tool is identifiable without opening any schema.

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

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

Gives a clear entry condition (place_id comes from search_places) and practical usage tips (combine sort_by orders for more coverage, use language to restrict). It stops short of explicit when-not-to-use guidance or naming a specific alternative review tool, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: result count per page (~16), full return field list, and a billing rate ($0.005/request). Missing pagination cap (though schema shows page max 20) and rate-limit info.

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

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

Four tight sentences, front-loaded with the core purpose, then output fields, then filters, then the routing hint and pricing. Every sentence carries information; no filler.

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

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

For a 14-param search tool with no output schema but full schema coverage, the description covers purpose, filter categories, return fields, pagination size, sibling routing, and cost. An agent has everything needed to select and invoke correctly.

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

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

Schema description coverage is 100% and the schema itself documents defaults, enums, units, and formats. The description summarizes which filters exist (category, price, condition, brand, seller, Prime, deals, 4+ stars) and reinforces the currency context ('in the marketplace currency'), adding light value over the schema. Baseline 3 is appropriate but the enumerative filter summary plus currency framing push it slightly higher.

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 (Search) and resource (Amazon products), names the input modes (keyword or ASIN), scope (24 marketplaces), and explicitly distinguishes from the sibling amazon_product_details. An agent can immediately tell this apart from amazon_best_sellers and amazon_product_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?

Names the alternative for single-product lookups ('Use amazon_product_details for one product'), giving clear routing context. However, it does not position against other Amazon siblings like amazon_best_sellers or amazon_seller_products, so routing among the full Amazon family is incomplete.

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

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

Annotations already declare readOnly, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: pagination ceiling (up to 50 posts per page), explicit billing ($0.003 per page, billed per page returned), and a surcharge for sentiment analysis.

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-loaded with purpose then return fields then controls and cost. No filler, though the returned-field enumeration is a long list rather than prose.

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

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

With no output schema, the description usefully enumerates what is returned (post text, author, date, engagement metrics, media, link cards, quoted posts), and cost/pagination behavior is stated. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the enum and defaults. The description restates sort options and date-range limiting but adds no syntax, bounds, or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Search) and resource (Bluesky posts) with a keyword-based scope, and clearly separates itself from sibling search_bluesky_users. An agent can identify the target immediately.

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

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

Implied usage is clear (keyword search over Bluesky posts with sort and date range), but it never states when to prefer this over alternatives like search_bluesky_users or bluesky_user_posts, nor any exclusions. Adequate but with a clear routing gap in a 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond that: the returned field set, a 50-users-per-page cap, and a $0.003-per-page billing cost, which materially affects how an agent should size a call.

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

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

Three short sentences, front-loaded with the search scope and then the return shape and cost. No filler, and the billing constraint is placed where it will be read before invoking.

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

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

There is no output schema, so the description correctly carries the return-value burden by enumerating handle, display name, DID, bio, verification status, picture and join date. Combined with the page cap and pricing, an agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100% and both parameters (query, pages) are already documented with limits and the per-page billing note. The description repeats 'up to 50 users per page' but adds no syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (search) and resource (Bluesky users) plus the exact match fields (handles, display names, bios), which clearly separates it from the sibling search_bluesky that covers posts. An agent can route correctly 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 description implies when to use it (keyword lookup of user accounts) but names no alternatives and gives no when-not-to-use guidance, e.g. versus search_bluesky or bluesky_user_profile. Usage is inferable but not stated.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds value beyond them: the returned fields (names, IDs, links), the cost model ("Billed $0.008 per page"), and the fact that paging drives cost. It does not cover rate limits or result caps, but the billing disclosure is genuinely useful for an agent controlling call volume.

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

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

Three tight sentences: purpose, return shape, then refinement and cost. The primary verb is front-loaded and nothing is redundant with the title.

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

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

With no output schema, the description compensates by naming the returned fields, and it covers scoping, cost, and the upstream dependency for location_id. Minor gaps remain around pagination behavior and maximum result counts for a multi-page billed call.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: start_date/end_date are framed as range limits and location_id is tied to its upstream source tool. It also links the pages parameter to billing, which the schema only mentions in isolation.

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

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

Specific verb+resource ("Search public Facebook events by keyword") with the scope qualifier "public" made explicit. It is clearly distinguishable from the numerous search_facebook_* siblings (posts, pages, videos, locations) without opening any schema.

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

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

Gives concrete narrowing strategies (limit by date range, scope by place) and names the upstream sibling search_facebook_locations as the source of location_id. It stops short of stating when this tool should be preferred over sibling searches like search_facebook_pages, but the context is clear enough to route 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?

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description earns credit for adding non-obvious operational context: the $0.004 per-request billing cost and the downstream handoff of the id. It does not describe return fields or rate limits, but the cost disclosure is meaningful value beyond structured 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?

Three short sentences, front-loaded with the core purpose, then the chaining instruction, then the cost. Every sentence earns its place with zero filler.

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

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

For a one-parameter resolver with no output schema, the description covers purpose, downstream usage, and cost. It could be slightly more complete by sketching what the returned location object contains (name/type alongside the id), but nothing essential for correct invocation 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% for the single query parameter, so the baseline is 3. The description's phrase 'city, region or country' loosely broadens the accepted input types beyond the schema's examples, but adds no format or constraint detail 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?

States a specific verb (resolve) and resource (place name → Facebook location IDs), which is distinct from the sibling search_* tools that return content. An agent can tell this is a lookup/resolution step, not a content search, 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?

Explicitly tells the agent what to do with the output: pass the returned id as location_id to search_facebook_posts or search_facebook_events. That is strong chaining guidance, though it stops short of stating when not to use it (e.g. when you already have a location_id).

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

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

Annotations already cover the read-only/open-world safety profile, so the lower bar applies. The description adds genuinely useful behavioral context the annotations don't: the exact return fields (name, URL, profile image, verification status) and the $0.008 per-page billing cost.

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

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

Three tight sentences, front-loaded with purpose, then return fields, then routing, then cost. Every sentence earns its place with no filler.

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

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

With no output schema, the description compensates by naming the returned fields, and it covers routing and pricing. Comprehensive for a two-param search tool; only minor gaps around result limits or pagination.

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 'query' and 'pages' with ranges and billing notes. The description's mention of keyword search and per-page billing adds marginal value but no syntax or format detail beyond the schema.

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

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

States a specific verb (Search) and resource (Facebook pages) with scope by keyword, which cleanly distinguishes it from the many search_facebook_* and facebook_page_* siblings. An agent knows immediately what this retrieves.

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 follow-up routing: pass a page URL to facebook_page_details for IDs and full profile, which signals this is the discovery step. However, it gives no explicit when-not guidance versus overlapping search tools like search_facebook_posts.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new operational context: billing at $0.008 per page, that the 'pages' parameter drives cost, and that get_sentiment carries a surcharge. It stops short of noting rate limits or result-cap behavior.

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

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

Four tight sentences: purpose, return payload, filtering options, cost. The most decision-relevant facts (what it does, what comes back, what it costs) are front-loaded and every clause carries information.

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

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

With no output schema, the description correctly compensates by naming the return fields, and all parameters are covered by the schema. For a paid, open-world search tool it is close to complete, though pagination limits and how sentiment interacts with multi-page billing are left implicit.

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 seven parameters are already documented with types, defaults, enums and formats. The description reinforces the location_id provenance and the per-page billing tie-in, but adds little syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Search public Facebook posts by keyword') plus scope ('public') and enumerates what is returned (post text, author details, engagement metrics, media). This distinguishes it from page/group-scoped siblings like facebook_page_posts and facebook_group_posts, which cannot search by keyword.

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

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

Gives concrete narrowing strategies (date range, sort order, place scoping) and explicitly routes the agent to search_facebook_locations to obtain a location_id, which is a real dependency an agent would otherwise have to guess. It does not state when this tool is the wrong choice versus sibling searches (e.g., search_facebook_pages), so no exclusions are covered.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description adds real value by disclosing the billing model ($0.008 per page) and the shape of results (title, description, author, thumbnail, view metrics). It omits rate limits and pagination caps, keeping it short of a 5.

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

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

Three tight sentences with the core action front-loaded, followed by output and pricing. Every clause carries information, though the sort/date sentence partially duplicates schema 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?

With no output schema, the description usefully lists returned fields and covers cost, filtering, and sort. It is nearly complete for a search tool; only pagination behavior and any auth prerequisites are unaddressed.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the enum and date formats. The description restates sort and date filtering but adds no syntax or semantic detail beyond the schema, matching 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 and resource ('Search Facebook videos by keyword') and enumerates what comes back, which cleanly separates it from sibling search tools for posts, pages, and events. It stops short of naming an explicit alternative, but the resource scope is unambiguous.

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

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

The description implies usage through its keyword-search framing and notes the date-range and sort options, but it never states when to prefer this over search_facebook_posts, facebook_page_videos, or search_youtube. Usage is implied rather than directed.

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