API Direct

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

With no annotations provided, the description carries the full burden. It discloses pagination behavior ('each page returns up to 50 ranked items'), the typical top-100 coverage, and the fields included in each item. It does not mention authentication, rate limits, or error behavior, but for a read-only rankings tool the disclosed behavior is substantial.

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

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

Two tight sentences deliver the core action, the supported ranking types, the return fields, and pagination constraints. There is no fluff or repetition of obvious 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?

Given no output schema or annotations, the description does a good job of explaining what the response contains and how pagination works. It could be more complete by noting valid country-code values or potential limitations, but the essential information for selecting and calling the tool is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining page size, top-100 coverage, and what each returned item contains. It reinforces the enum values and category slug concept, though it does not add much detail for the country 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 starts with a specific verb and resource: 'Get Amazon best-seller rankings for a category.' It enumerates the supported ranking types and clarifies that the result is a ranked list, which clearly distinguishes it from sibling product-search and product-detail tools like search_amazon_products 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?

The description makes the tool's purpose immediately evident: use when you need category best-seller rankings rather than product details or free-form product searches. It does not explicitly name alternatives or state when not to use it, but the context is clear enough that an agent can route appropriately.

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

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

There are no annotations, so the description carries the behavioral burden. It uses a clear read verb ('Get') and discloses a detailed return payload including pricing, buy box seller_id, availability, condition, media, specs, rating breakdown, and reviews. It does not discuss error/not-found behavior, but the read-only nature is transparent.

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

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

Two sentences with no wasted words: the first delivers the purpose and input source, the second packs a comprehensive list of return fields. 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?

No output schema exists, so the detailed return field list is essential and is provided. The parameter schema covers the only required input and the optional country default. Minor omissions like invalid-ASIN handling or country-specific behavior do not prevent correct invocation.

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

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

Schema coverage is 100% and both parameters are documented, so the baseline is 3. The description adds value by explaining that the asin is the 10-character code produced by search_amazon_products, which clarifies the expected input more concretely than the schema alone.

Input schemas describe structure but not intent. Descriptions should explain 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 full details for an Amazon product by ASIN." It also enumerates the returned fields, which distinguishes it clearly from sibling search tools like search_amazon_products. Mentioning that the ASIN comes from search_amazon_products further disambiguates the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: after search_amazon_products returns an ASIN, when full product details are needed. It does not explicitly name alternatives to exclude, but the ASIN provenance guidance and the detail-focused purpose provide enough routing context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful behavioral context: pagination of ~16 results per page, sortability by price/reviews/newest/best sellers, and that it returns the same product objects as search_amazon_products plus total catalog size. It does not mention error handling or rate limits, but for a read-only catalog fetch this is reasonably transparent.

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

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

Two sentences with no filler. The core action and required identifier are front-loaded, and the second sentence adds relevant comparison and pagination/sort behavior. Every clause contributes useful information.

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

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

For a paginated catalog tool with no output schema, the description covers what is returned, the relationship to search_amazon_products, page size, and sortability. It does not explain error behavior for invalid seller IDs or country-specific nuances, but those are typically not required for tool selection and invocation. The required parameter, pagination, and sorting are all addressed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal semantic value by summarizing sort options as 'price, reviews, newest, or best sellers,' but the schema already documents every parameter, enum, and default. No parameter meaning is missing.

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

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

The description clearly states a specific verb and resource: 'Get the catalog of products sold by an Amazon seller by seller ID.' It distinguishes itself from the sibling search_amazon_products by noting it returns the same product objects plus the seller's total catalog size, avoiding confusion with other Amazon tools.

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

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

The description implies when to use this tool: when you have a seller ID and need all products from that seller. It explicitly references search_amazon_products as the related alternative and clarifies the difference, though it does not state explicit exclusion cases or say 'use search_amazon_products for keyword searches.'

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses the operation as a read (Get) and enumerates the returned data (name, logo, ratings, feedback breakdown). It does not mention error cases, rate limits, or marketplace-specific variations, but for a simple profile lookup the behavior is well specified.

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

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

Two sentences with no waste: the first sentence states the action and input source; the second lists the full return payload. The information is front-loaded and every phrase earns its place.

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

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

The description fully enumerates return fields, compensating for the missing output schema, and provides the input-source context. It does not address possible failure modes (e.g., invalid seller_id, unsupported country) or clarify that seller_id is marketplace-specific, but for a low-complexity two-parameter tool it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context above the schema by explaining that seller_id comes from a product's main_buy_box.seller_id, giving the agent a concrete extraction path. The country parameter is already self-explanatory in the schema.

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

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

The description states a specific verb ('Get'), a specific resource ('Amazon seller's profile'), and the exact input ('seller ID'). It also explicitly differentiates from sibling tools like amazon_seller_products and amazon_seller_reviews by focusing on profile attributes (name, logo, business address, ratings, feedback).

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

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

The description clearly implies the intended use case: when you have a product's main_buy_box.seller_id and need the seller's profile details. It does not, however, explicitly contrast against sibling tools like amazon_seller_products or amazon_seller_reviews, or state when not to use it. The source-of-ID hint provides strong contextual usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the pagination mechanism ('paginate with page until has_next_page is false'), the filtering options, and the get_sentiment surcharge behavior. It does not mention rate limits or error cases, but the core behavioral traits are well covered.

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose and return fields; the second sentence packs filtering and pagination guidance. Every clause earns its place.

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

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

For a read-only retrieval tool with 100% schema coverage and no output schema, the description covers the essential call pattern: what it returns, how to filter, and how to paginate. It does not describe the output structure, but since there is no output schema and the return fields are listed in the description, an agent has enough to invoke it correctly. Minor gaps like rate limits or error handling prevent a 5.

Complex tools with many parameters or behaviors need more documentation. 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 five parameters. The description adds value by explaining the pagination loop ('until has_next_page is false') and the sentiment surcharge, which are not fully captured in the schema. It does not repeat parameter names, so it complements rather than duplicates the schema.

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

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

The description states a specific verb ('Get'), a specific resource ('customer feedback for an Amazon seller by seller ID'), and enumerates the exact data fields returned (author name, text, star rating, date, seller response). It is clearly distinguishable from sibling tools like amazon_seller_profile or amazon_seller_products, which target different resources.

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

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

The description gives clear context on when to use the tool: when you need customer feedback for a seller, with filtering by star rating or sentiment, and pagination instructions. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it correctly among the many sibling tools.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses concurrency, per-item status/body, input-order preservation, separate billing per item, unsupported endpoint inside a batch, potential latency for large batches, and a docs link. This is comprehensive and gives the agent confidence in side effects and cost 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 sentences deliver all essential information: definition, example, concurrency and order, billing, exclusion, latency, and docs reference. No fluff, every sentence earns its place, and key facts are front-loaded. The structure is logical and scannable.

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

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

Given the tool has no output schema and no annotations, the description covers the critical context: what the tool does, how many items, mixing, concurrency, per-item result format, billing, limitation, potential long duration, and a link to full docs. This is complete enough for an agent to select and invoke the tool correctly.

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

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

The schema already provides 100% coverage of the only parameter, describing items, endpoint, params, and tag. The description adds an example and reiterates the mix of endpoints but doesn't provide new parameter-level semantics beyond the schema. Per the rubric, baseline 3 is appropriate when schema coverage is high.

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

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

The description uses a specific verb phrase 'Execute up to 100 API Direct requests in a single call' and clearly identifies the resource as a batch aggregation of other endpoints. It distinguishes from siblings by explaining it can mix any of the other tools' endpoints, with a concrete example (50 twitter_user_profile + 50 instagram_user_profile). This leaves 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?

It clearly states the primary use case (batching multiple API requests) and the limitations (no /v1/web/ai-mode, large batches can take minutes). However, it doesn't explicitly contrast with using individual endpoint tools directly, though the example and wording strongly imply the alternative. A direct statement like 'For single requests, use the specific endpoint tool' would earn 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?

The description discloses billing ('Billed $0.003 per request') and the exclusivity requirement ('exactly one of url or post_id'), which are useful behavioral details. However, with no annotations provided, the description carries the full burden. It does not mention pagination, rate limits, or what happens if both parameters are provided. The billing disclosure is a positive, but the lack of pagination/error behavior leaves a gap.

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

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

The description is two sentences with no wasted words. It front-loads the core action, then adds the billing and parameter constraint. Every sentence earns its place.

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

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

For a simple read tool with three well-documented parameters, the description is mostly complete. However, there is no output schema and no mention of pagination or result structure, which an agent might need to know for a comments endpoint. The billing and exclusivity details are helpful, but the lack of pagination/response info keeps this at a 3.

Complex tools with many parameters or behaviors need more documentation. 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 thoroughly. The description adds the 'exactly one of' constraint, which is valuable, and mentions the sentiment surcharge. However, it does not add much beyond the schema's own parameter descriptions. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Get the replies to a Bluesky post.' This clearly distinguishes it from sibling tools like bluesky_post_likes, bluesky_post_quotes, and bluesky_post_reposts, which retrieve different engagement data. It could be slightly stronger by explicitly naming a sibling, but the resource and action are unambiguous.

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

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

The description provides a clear usage constraint: 'Provide exactly one of url or post_id.' This tells the agent how to invoke the tool correctly. It does not explicitly state when to choose this over alternatives, but the tool name and description make the use case obvious (fetching comments/replies for a Bluesky 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses the per-request cost and the exclusivity constraint, and the verb 'Get' implies a read-only operation. However, it does not mention error handling, response format, or what happens if both or neither identifier is supplied.

Agents need to know what a tool does to the 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 concise sentences front-load the core purpose and immediately follow with cost and a critical usage constraint. Every sentence contributes useful information with no redundant 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 single-post retrieval tool with no output schema and no annotations, the description adequately covers the core need: how to identify the postregation and what to expect. It could be more complete by noting the return shape or error behavior, but this is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter guidance by explicitly stating that exactly one of url or post_id must be provided, which is not encoded in the schema's required 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?

The description clearly states the tool 'Get a single Bluesky post by URL or ID', identifying a specific verb, resource, and input method. It is distinct from sibling tools like bluesky_post_comments or bluesky_user_posts, though it does not explicitly name those alternatives.

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

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

The description gives clear context: use this tool to fetch one specific post using either a URL or an AT URI. It also provides a crucial usage rule—'Provide exactly one of url or post_id'—but does not explicitly discuss when to choose this over sibling post-related tools.

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

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

With no annotations, the description carries the behavioral burden and it does well: it discloses the ordering, the exact per-page cost, and the need to supply exactly one identifier. It does not mention auth or error behavior, but for a read-style list tool the key operational traits are covered.

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

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

Three short sentences: purpose, cost, and usage constraint. The core behavior is front-loaded and every clause adds new information without verbosity.

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

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

For a simple paginated read with three parameters, the description plus schema covers how to call it, how ordering works, and the cost model. It might have mentioned what account fields are returned, but there is no output schema and the list nature is already implied by 'users who liked.'

Complex tools with many parameters or behaviors need more documentation. 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, pages, and post_id. The description adds the important relational constraint that url and post_id are mutually exclusive and that one is required, which is not visible in the schema's required list.

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

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

The description opens with 'Get the users who liked a Bluesky post' – a specific verb and resource – and adds 'newest first.' In a sibling set that includes comments, reposts, quotes, and details for the same post type, this clearly names the exact operation and object.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states a strict invocation condition ('Provide exactly one of url or post_id') but does not say when to choose this tool over, say, bluesky_post_reposts or bluesky_post_comments. Usage is reasonably implied by the resource being 'users who liked,' but no explicit alternatives or exclusions are given.

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

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

The description discloses that results are sorted newest first, which is a behavioral trait not in annotations (none provided). It also mentions billing per page, adding cost transparency. However, it doesn't describe what the response contains (e.g., post details, author info) or whether it includes nested data, but with no annotations, this is a moderate gap.

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

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

The description is concise, with two sentences. The first sentence states the core purpose and ordering, and the second provides a crucial usage constraint (exactly one of url or post_id). It is front-loaded with the action, though it could be slightly more structured with explicit use-case guidance, but overall it's efficient.

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

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

The description is fairly complete for this tool: it tells the agent what it does, the ordering, the essential parameter constraint, and cost implications. With no output schema and no annotations, it doesn't describe return structure, but that is a minor gap. It adequately covers the necessary context for an agent to call it correctly.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description adds the mutual exclusivity (exactly one of url or post_id) which is useful beyond the schema. It also mentions the default pages behavior indirectly via schema, but the description doesn't further clarify parameter formatting beyond what's in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves quote posts for a Bluesky post, ordered newest first, and specifies the input requirement (exactly one of url or post_id). It is distinct from siblings like bluesky_post_details (which gets individual post details) and bluesky_post_comments (which gets comments), so an agent can select it correctly.

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

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

The description explicitly says to provide exactly one of url or post_id, which is a key usage rule. It also includes a note about billing per page, which helps agents understand usage context. However, it doesn't mention when to use this tool over alternatives like bluesky_post_likes or bluesky_post_reposts, though the naming and purpose are fairly 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?

With no annotations, the description carries the behavioral disclosure burden. It adds concrete behavioral details: results are ordered newest first, and the tool is billed per page. It does not mention auth requirements or response shape, but for a read-only listing tool the disclosed details are reasonably complete.

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

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

Three short sentences with zero filler. The purpose is front-loaded, followed by billing and the key parameter constraint. Every sentence earns its place.

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

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

For a simple listing tool with no output schema and no annotations, the description covers the inputs, the core behavior, ordering, and cost. It is missing only explicit guidance on what response shape to expect, but that is largely inferable from 'users who reposted.'

Complex tools with many parameters or behaviors need more documentation. 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 meaningful constraint information beyond the schema: exactly one of url or post_id must be provided. It also ties billing cost to the pages parameter, which helps agents reason about usage cost.

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

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

The description states a specific verb and resource: 'Get the users who reposted a Bluesky post.' It also adds ordering ('newest first'), and the term 'reposted' clearly differentiates it from sibling tools like bluesky_post_likes and bluesky_post_comments. This is unambiguous and immediately actionable.

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

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

The description gives clear parameter usage guidance ('Provide exactly one of url or post_id') and billing context, but it does not explicitly state when to choose this tool over alternatives. Usage is implied by the tool's name and purpose 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?

No annotations are provided, so the description carries the full burden. It usefully discloses billing ($0.003 per page) and ordering (newest first), but does not mention rate limits, error behavior, or explicitly confirm it is read-only. These disclosures add meaningful context beyond the raw schema, but gaps remain.

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

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

Two sentences with no wasted words. The first sentence states action, resource, and ordering; the second covers billing and the parameter rule. Everything earns its place and is front-loaded.

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

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

For a simple read-only list tool with no output schemaaca, the description captures purpose, ordering, cost, and the parameter exclusivity rule. The schema handles details like page size and defaults. The only minor omissions are rate-limit or auth notes, which are uncommon in this context.

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

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

The schema already documents all three parameters with 100% coverage, establishing a baseline of 3. The description adds the crucial exclusive-or constraint ('exactly one of username or url'), which is not present in the schema, and clarifies the output ordering. This extra meaning raises the score above baseline.

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

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

The description states a specific verb ('Get') and resource ('followers of a Bluesky user') with ordering ('newest first'). This clearly distinguishes it from the sibling tool bluesky_user_following, which retrieves the opposite 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 provides no guidance on when to use this tool versus alternatives such as bluesky_user_following or search_bluesky_users. The only directive, 'Provide exactly one of username or url', is a parameter constraint, not a tool-selection guideline.

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

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

The description carries the full burden because no annotations are present. It transparently discloses billing per page, newest-first ordering, and the need to provide exactly one identifier, which goes beyond the schema. It does not mention error behavior or response shape, but for a straightforward read operation this is reasonably complete.

Agents need to know what a tool does to the 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 exceptionally concise: two short sentences pack purpose, ordering, cost, and the critical input constraint with no filler. Each sentence contributes distinct 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?

All three parameters are fully described in the schema, and the description covers purpose, ordering, cost, and input constraints. It lacks explicit error behavior and output shape, but given the simplicity of the tool and the absence of an output schema, the definition provides enough context for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics by stating the mutual-exclusivity rule for username and url, which the schema alone does not enforce or explain, and it reinforces the billing implication of 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 action ('Get the accounts ... follows') on a well-defined Bluesky resource, and clarifies the result ordering ('newest first'). This clearly distinguishes it from the sibling bluesky_user_followers by indicating the direction of the 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?

No guidance is given on when to use this tool versus alternatives such as bluesky_user_followers or other user-related Bluesky endpoints. The only usage rule, 'Provide exactly one of username or url,' concerns parameter selection rather than tool selection.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It reveals ordering ('newest first') and cost ('Billed $0.003 per page'), and 'Get' implies a read operation. However, it does not mention authorization requirements, rate limits, or error behavior, leaving some behavioral gaps.

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

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

The description is two concise sentences with no filler. It front-loads the main purpose, then adds billing and parameter constraint. Every part 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?

The description covers the core purpose, output ordering, cost, and the key invocation constraint. The remaining parameter behaviors (pages, get_sentiment) are in the schema. Minor gaps like authentication or error handling do not prevent correct invocation.

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

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

Schema coverage is 100%, so parameter descriptions are already complete. The description adds a crucial constraint beyond the schema: 'Provide exactly one of username or url', which prevents invalid calls. This is meaningful semantic guidance.

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

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

The description uses a specific verb ('Get') and resource ('posts a Bluesky user has liked'), and adds ordering ('newest first'). It clearly distinguishes from sibling tools like bluesky_user_posts (posts by a user) and bluesky_post_likes (likes on a post) without needing to inspect schemas.

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

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

The description gives clear context for when to use the tool: retrieving liked posts for a user. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough for an agent to select it over 'bluesky_user_posts' or 'bluesky_post_likes'.

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

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

With no annotations provided, the description carries the full burden. It discloses the feed ordering, flags, billing per page, and the input constraint. It does not mention error cases, rate limits, or authentication, but for a read-only tool these are minor. It adds useful behavioral context beyond the schema.

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

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

The description is a single, densely packed sentence that front-loads the purpose and includes key flags and billing. No wasted words; every part earns its place.

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

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

Given no output schema, the description conveys the output content (posts, replies, reposts with flags) adequately. It misses potential error behavior or what happens when both username and url are provided, but for a simple feed tool it is largely complete.

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

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

Schema coverage is 100%, so parameters are well documented. The description adds the essential 'exactly one of username or url' rule, which is not captured in the schema, and clarifies billing implications for pages. This adds meaningful value beyond the schema.

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

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

The description clearly states the verb ('Get'), the resource ('a user's feed by handle'), and the specific content ('posts, replies, and reposts' with flags). It distinguishes itself from siblings like bluesky_user_profile (profile info) and post-specific tools by focusing on the feed.

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

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

The description gives a critical usage constraint ('Provide exactly one of username or url') and mentions billing per page, but it does not explicitly name alternatives or specify when to use this tool over siblings. The context is clear, but no exclusions are 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does add useful behavior context: the per-request cost ('Billed $0.003 per request') and the exclusivity requirement ('Provide exactly one of username or url'). However, it does not disclose potential error conditions, rate limits, data freshness, or whether the operation is read-only, leaving meaningful gaps.

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

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

Two sentences with no fluff: the first states the core operation and accepted identifiers, the second states cost and input constraint. The most important information is front-loaded, and every clause earns its place.

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

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

For a simple two-parameter read tool with no output schema and no annotations, the description gives enough to invoke correctly: what it returns ('full profile'), how to specify inputs, and cost. It lacks error-handling and output-format details, but these are minor for a straightforward profile fetch.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic constraints beyond the schema. The schema lists both parameters as optional, while the description explicitly requires exactly one of them, and clarifies that the username parameter can be a handle, DID, or with/without leading '@'—the latter echoed in the schema but the exclusivity rule is new.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Get'), resource ('a Bluesky user's full profile'), and input methods ('by handle, DID, or profile URL'). It clearly distinguishes this from sibling tools like bluesky_user_posts or bluesky_user_followers, which target different aspects of a user's data. The platform and scope are immediately unambiguous.

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

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

There is no guidance on when to prefer this tool over alternatives such as search_bluesky_users or bluesky_user_followers. It does not mention when not to use it or name sibling tools. The only usage instruction—'Provide exactly one of username or url'—is about input constraints, not tool selection, so the tool-choice guidance is effectively absent.

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

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

No annotations are present, so the description must carry the full burden. It only states 'Get', which implies a read-only operation, but provides no details about authentication requirements, rate limits, error behavior, or whether the group must be public. This lack of behavioral disclosure is a significant gap for a tool with no annotation support.

Agents need to know what a tool does to the 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, clear sentence that immediately states the tool's purpose and key outputs. Every word earns its place, with 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?

For a simple 1-parameter read tool, the description gives a fair overview but omits an exhaustive list of return fields (uses 'including'), and does not mention edge cases like invalid URLs or access restrictions. Given the absence of an output schema, the description is minimally viable but has clear gaps in behavioral and output completeness.

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

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

The schema already provides 100% coverage by describing 'url' as 'Facebook group URL'. The description adds no extra meaning about the parameter, such as URL format or validation rules. Since schema coverage is high, the baseline is 3, and the description does not exceed that.

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

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

The description uses the specific verb 'Get' with the resource 'Facebook group details' and explicitly lists the key attributes returned (name, description, members count, privacy setting). This clearly distinguishes it from sibling tools like facebook_page_details or facebook_group_posts.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention scenarios where this tool is appropriate (e.g., retrieving metadata for a specific group) or when to prefer sibling tools like facebook_group_posts. No exclusions or alternative recommendations are provided.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure, but it only mentions 'public' as a limitation. It does not warn about pagination/billing per page, return format, rate limits, or any side effects, even though 'pages' is documented as billed per page in the schema.

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

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

The description is a single, front-loaded sentence with no wasted words. It is efficient, though it leans heavily on the schema and sibling names for context; slightly more detail would not be padding but useful elucidation.

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

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

For a tool with four parameters, no annotations, and no output schema, the description is too thin to be complete. It does not mention that output is a paginated list of posts, how sorting or sentiment affect results, or what fields are returned, leaving agents to infer too much from the schema alone.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little parameter meaning beyond implying that group_id is the target group; it does not clarify how pages, sort_by, or get_sentiment affect the results beyond what the schema already states.

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

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

The description states a specific verb ('Get'), resource ('posts'), and scope ('public Facebook group'), clearly distinguishing it from sibling tools like facebook_group_details and facebook_page_posts. The qualifier 'public' also adds immediate selection context that the tool only works with publicly accessible groups.

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

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

There is no guidance about when to use this tool versus alternatives such as search_facebook_posts, facebook_page_posts, or facebook_post_comments. No exclusions, prerequisites, or contextual cues are provided beyond the bare statement of what the tool does.

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

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

With no annotations, the description carries the burden of disclosing behavior. It implies a read-only operation via 'Get' and lists return fields, but does not explicitly mention that it has no side effects, handles invalid URLs, or requires authentication. The description adds some value but lacks explicit safety or error context.

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

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

The description is a single sentence, immediately front-loaded with the verb and resource, and lists all relevant output fields without redundancy. Every word contributes meaning.

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

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

For a simple single-parameter tool with no output schema, the description adequately conveys what it does and returns. It does not mention error behavior or explicit read-only status, but given the low complexity and clear focus, it is nearly complete.

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

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

Schema coverage is 100% with a single 'url' parameter well-described in the schema (including an example). The tool description does not add extra parameter semantics beyond the schema, which is acceptable given full schema coverage. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Get') and resource ('detailed information about a Facebook page'), listing specific fields (name, followers, categories, contact info, verification status). This distinguishes it from sibling tools like facebook_page_posts and facebook_page_photos, which target different content types.

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

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

The description provides clear context about what information this tool retrieves, making it obvious for page metadata. While it does not explicitly mention alternatives or exclusions, the field list (e.g., followers, contact info) differentiates it from content-specific siblings, so the usage intent 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention pagination behavior, the fact that pages are billed per page, authentication needs, rate limits, or what the returned data looks like. The 'pages' parameter hints at pagination but the description itself is silent.

Agents need to know what a tool does to the 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, clear sentence with no filler or redundancy. It front-loads the core action and resource immediately, making it easy to parse.

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

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

The description is minimal and lacks information an agent would need for effective use: no mention of pagination implications, billing, return value shape, or relationship to page_id requirements. Even for a simple getter, a sentence about pagination or the meaning of 'pages' would meaningfully improve completeness.

Complex tools with many parameters or behaviors need more documentation. 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 parameter descriptions already document page_id and pages clearly. The tool description itself adds no extra semantic meaning about the parameters, but this is acceptable because the schema carries that burden.

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

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

The description clearly states the operation ('Get photos') and the resource (a Facebook page). It is distinguishable from sibling tools like place_photos or search_facebook_pages because the target platform and resource type are explicit, though it does not contrast itself with any sibling.

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

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

The description gives no guidance on when to use this tool versus alternatives, nor does it mention any exclusions, prerequisites, or context in which a different tool would be more appropriate. The only implied usage is the literal action 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?

There are no annotations, so the description carries the burden. It communicates a non-destructive 'get' operation and a recency/ordering behavior, but it omits details like pagination behavior, billing per page, and return shape—though some of those appear in parameter descriptions.

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

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

A single, front-loaded sentence contains the core action, resource, and required parameter with no filler. It is as concise as possible while remaining informative.

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

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

The description gives the minimum needed for selection and invocation, and the schema handles parameter meaning. However, with no output schema and no annotations, the agent is left without explicit information about returned post fields or response structure.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The tool description adds no new parameter-level detail but does not need to, given the rich schema 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 action (Get), a resource (recent posts from a Facebook page), and the required identifier (by page ID). This clearly distinguishes it from sibling tools like facebook_page_photos or facebook_page_reels.

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

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

The intended use is implied by the description: an agent should call this when it needs recent page posts for a given page_id. However, there is no explicit when-not-to-use guidance or named alternatives, leaving the choice 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It reveals one dependency (reels_page_id from page details) but says nothing about pagination behavior, billing per page, the sentiment surcharge, authentication, rate limits, or error conditions. Billing details appear only in the parameter schema, not in the tool description.

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

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

The description is concise and front-loaded, with no filler or redundancy. It could still use its spare capacity to mention a sibling alternative or expected output, but as a standalone action statement it is appropriately tight.

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

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

For a simple three-parameter fetch with no output schema, the description identifies the resource and the required ID source. However, without annotations it leaves return shape, pagination expectations, and billing/cost implications unstated except in the parameter schema, and it does not help the agent choose between this and facebook_page_videos.

Complex tools with many parameters or behaviors need more documentation. 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 input schema already documents all three parameters adequately. The description merely restates that reels_page_id is required and its source, adding no meaning beyond the schema. Baseline 3 is appropriate here.

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

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

Description names the specific action ('Get reels') and resource ('Facebook page'), which is clear and generally distinct from sibling tools like facebook_page_posts or facebook_page_photos. However, it does not explicitly differentiate reels from the closely related facebook_page_videos, so it stops short of full sibling differentiation.

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

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

The description gives an explicit prerequisite: the reels_page_id must come from the page details endpoint, which usefully tells the agent to call facebook_page_details first. However, it never states when to prefer this tool over alternatives or adds exclusions, so usage guidance is only partially explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, yet it only says 'Get reviews' and reveals nothing about pagination, billing per page, or the shape of the returned data. The read-only nature is implied but not substantiated by any behavioral detail.

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

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

The description is a single front-loaded sentence with no filler or redundant restatement of the tool name. Every word contributes to the core purpose, making it easy to parse quickly.

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

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

For a simple fetch operation, the description plus a fully documented schema is minimally viable, but no output schema exists and the description doesn't hint at return contents or optional features like sentiment. An agent can call the tool correctly, but would need to infer expected results.

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

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

Schema description coverage is 100%, so the schema already explains page_id, pages, and get_sentiment, including billing and sentiment behavior. The description adds no parameter meaning beyond mapping the tool to page_id, which is why the schema baseline of 3 applies.

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

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

The description states a specific action ('Get reviews') and a clear resource ('a Facebook page'), which distinguishes it from sibling tools like facebook_page_posts or facebook_page_photos. Even without reading the schema, an agent knows exactly what this tool 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?

The description implies the tool should be used when an agent needs Facebook page reviews, but it provides no explicit conditions, exclusions, or comparisons to sibling tools. There is no guidance on when to prefer this over facebook_page_details or place_reviews, so usage context is only inferred.

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

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

No annotations are provided, so the description carries the full burden. It discloses a prerequisite (delegate_page_id) but doesn't mention pagination behavior, rate limits, billing implications beyond the schema's 'Billed per page' note, or what the response contains. The description adds minimal behavioral context beyond the schema.

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

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

The description is two sentences with no fluff. The core action is front-loaded, and the prerequisite is stated concisely. It earns a 4 because it's efficient, though it could have added a bit more context without becoming verbose.

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

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

For a tool with no annotations and no output schema, the description is thin. It doesn't explain what the returned videos look like, how pagination works, or how this differs from facebook_page_reels. An agent would need to infer a lot or inspect the schema. The prerequisite is helpful but not enough for full completeness.

Complex tools with many parameters or behaviors need more documentation. 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. The description adds the origin of delegate_page_id ('from the page details endpoint'), which is useful. However, it doesn't add meaning beyond the schema for pages or get_sentiment, so baseline 3 is appropriate.

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

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

The description states a clear verb and resource: 'Get videos from a Facebook page.' It distinguishes itself from siblings like facebook_page_posts and facebook_page_photos by naming the resource type (videos). However, it doesn't explicitly differentiate from facebook_page_reels, which is a close sibling, so it's not a perfect 5.

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

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

The description mentions a prerequisite: 'Requires the delegate_page_id from the page details endpoint.' This gives some usage context. However, it doesn't explicitly state when to use this tool versus alternatives like facebook_page_reels or search_facebook_videos, nor does it provide exclusions or conditions.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly communicates a read-style operation ('Get') and specifies the response contents, including reaction/reply counts and any attachment. Pagination and auth are not discussed, but the core behavior and return shape are transparent enough for a straightforward fetch tool.

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

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

The description is a single front-loaded sentence with no filler. It states the primary action first and then lists the return fields efficiently, earning every word.

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

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

For a simple three-parameter tool with a fully documented schema and no output schema, the description provides enough return-value detail to make the tool usable without ambiguity. Nothing critical 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 descriptions cover 100% of parameters, including pages, post_id, and get_sentiment, so the baseline is 3. The description adds little parameter-level meaning beyond the schema, though it reinforces that post_id is the required key and suggests the post_id source.

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

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

The description names the exact operation and resource: 'Get comments on a Facebook post by post ID.' It also enumerates the returned data (text, author details, reaction and reply counts, date, and attachment), making the tool's purpose concrete and distinguishable from platform-specific sibling comment tools.

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

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

The description clearly indicates when to use the tool: when comments are needed for a known Facebook post ID. The post_id parameter further contextualizes by naming the upstream Facebook post sources. It does not explicitly list exclusions, but there is no competing same-platform comment fetch tool among siblings.

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

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

With no annotations, the description carries full disclosure burden. It explains the tool fills in user inputs, returns an ordered recipe to execute, and tells the agent to ask the user for inputs if omitted. It doesn't elaborate on return format or execution semantics, but covers the core behavior well.

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

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

Four sentences, each serving a distinct purpose: definition, return value, usage preference, and parameter routing. The front-loaded sentence captures the essence, and the structured guidance is dense without being verbose.

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

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

Given no output schema, the description compensates by explicitly stating the return value ('ordered recipe of tool calls') and the workflow with list_skills. It prepares the agent to execute the playbook and handle unnamed skills, covering all functional gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving a concrete example of inputs and skill_id, and clarifies that inputs are optional and what happens if omitted — going beyond the schema's static descriptions.

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

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

The description opens with a specific verb+resource: 'Get a ready-made skill's step-by-step playbook' and clarifies it returns an 'ordered recipe of tool calls'. This clearly distinguishes it from sibling data-fetching/search tools and positions it as a meta-tool that produces executable instructions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'PREFER running a matching skill over improvising raw searches' and provides a decision tree: if the user names a skill, pass the skill_id directly; otherwise call list_skills first. This is textbook usage guidance with clear alternatives.

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

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

With no annotations, the description carries the full burden. It discloses a notable operational trait—billing $0.005 per page—and the limitation that only up to 5 preview replies are returned. This goes beyond a bare operation statement, though it does not discuss error cases, rate limits, or access prerequisites.

Agents need to know what a tool does to the 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 no filler. The primary action and return contents are front-loaded, and the cost caveat is placed at the end. 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?

The absence of an output schema raises the burden on the description, and it does enumerate the returned fields and reply preview limit. It also tells the agent about cost, while the schema covers paging and sort options. Missing are the top-level response shape and any failure modes, but these are minor for a simple read tool.

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

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

Schema description coverage is 100%, so the baseline is 3 even without parameter details in the description. The description does not add new meaning for url, pages, or sort_by beyond what the schema already says; it only reinforces pagination through the per-page billing mention.

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

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

The description opens with a specific verb and resource: 'Get comments from a YouTube video.' This clearly targets comments rather than video metadata, distinguishing it from youtube_video_details and search tools, and the listed return fields (text, author, likes, replies, date, link) make the exact purpose unambiguous.

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

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

The description provides clear context: use this tool when you need the comment feed of a YouTube video, including preview replies. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the wording leaves little ambiguity against sibling comment tools for other platforms.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context about the response format (paragraphs, headings, lists, images, citations) and session continuation, but it omits details about rate limits, authentication, or potential side effects. The added transparency is adequate but not comprehensive.

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

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

The description is two sentences, front-loaded with the primary action and output, followed by essential continuation guidance. Every sentence earns its place and there is zero 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?

Given the tool's moderate complexity and absence of output schema/annotations, the description covers the core input (prompt) and output structure explicitly. It also explains conversational state via session_token. Minor gaps remain, such as optional parameter behavior or error handling, but the description is largely sufficient for an agent to invoke the tool correctly.

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

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

The schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter-level meaning beyond what the schema already states; session_token is mentioned in both, but no new semantics (e.g., formatting, constraints) are introduced in the description.

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

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

The description states a specific verb ('Send a prompt') and resource ('Google's AI Mode') and clearly defines the output (structured conversational reply with reply_parts and reference_links). It distinguishes itself from sibling search tools by emphasizing conversational context and structured citations, leaving 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 tool provides usage context by describing how to continue conversations via session_token, but it does not explicitly explain when to choose this tool over sibling search tools like search_web. Usage is implied rather than stated with alternatives or exclusions, so it only partially meets the bar for clear guidance.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses billing behavior ('Billed per page'), the empty-result edge case ('Returns an empty list when the comment has no replies'), the mutual exclusivity of url/code, and notable return content (including the AI-generated profile label). It stops short of mentioning auth requirements, rate limits, or behavior on invalid comment IDs, which keeps it from a 5.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place: identification method, return shape, billing/edge case, and parameter constraint. It is slightly loose in combining the final short sentences, but overall it is well-structured for an agent to parse quickly.

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

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

Given no output schema and no annotations, the description compensates well by detailing the return shape (text, author details, like count, date, link, parent comment) and edge behavior. It covers the essential calling constraints but leaves minor gaps around pagination mechanics relative to the pages parameter and no mention of authentication prerequisites.

Complex tools with many parameters or behaviors need more documentation. 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 meaning beyond the schema: it clarifies that url and code are mutually exclusive alternatives (a constraint the schema does not encode), and it specifies that comment_id comes from instagram_post_comments. This elevates the parameter semantics above the schema alone.

Input schemas describe structure but not intent. Descriptions should explain 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 the replies to one Instagram comment (its thread)') and precisely scopes how to identify the target ('by post URL or shortcode plus the comment ID from instagram_post_comments'). It is clearly distinguishable from siblings like instagram_post_comments (comments on a post) and instagram_post_likes (likes on a post), and it names its prerequisite sibling explicitly.

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

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

The description provides clear context: this is for fetching the reply thread beneath a single comment, and it establishes the workflow by noting the comment ID comes 'from instagram_post_comments'. It also enforces the operational constraint 'Provide exactly one of url or code'. However, it does not explicitly state when not to use this tool or compare it against alternatives.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses pagination behavior ('up to about 30 new posts per page'), billing implications ('billed per page'), the tab-selection mechanism of sort_by, and the exact composition of returned objects. For a read-only retrieval endpoint, this is strong disclosure, though rate limits and auth requirements are not mentioned.

Agents need to know what a tool does to the 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, with the core purpose front-loaded and each sentence earning its place: return-format grounding, pagination/billing disclosure, and tab control. The enumerated field list is slightly verbose but justified since no output schema exists to define the return shape.

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

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

For a 4-parameter tool with 100% schema coverage, no annotations, and no output schema, the description covers purpose, output composition, pagination, billing, and sort behavior. It even enumerates the returned fields to compensate for the missing output schema. Minor omissions like rate limits and authentication are the only gaps, making this substantially complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds marginal value beyond the schema: it clarifies that sort_by selects the 'hashtag page tab' and adds billing-per-page context for the pages parameter that the schema omits. But the schema already documents hashtag formatting, page ranges, enum options, and the sentiment surcharge, so the description is not doing heavy lifting here.

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

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

The description opens with a specific verb+resource+scope construction: 'Get Instagram posts and reels for a hashtag.' It also anchors the return format to a named sibling ('Returns the same post objects as search_instagram'), which immediately distinguishes this hashtag-scoped tool from user-scoped siblings like instagram_user_posts and search-scoped search_instagram. An agent can tell what it does 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 its use case through the hashtag scope and the sort_by tab mechanics (top/recent/reels), but it never explicitly states when to choose this over alternatives or when not to use it. The reference to search_instagram is about return shape, not routing ('use this for hashtags, use search_instagram for keyword search'). Usage context is clear but exclusions and alternative routing are left to inference.

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

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

With no annotations, the description carries the full behavioral burden. It discloses a useful operational trait: media URLs are temporary (~6-24 hours). It also enumerates the returned fields, giving the agent a clear expectation of behavior. It stops short of mentioning privacy, authentication, or rate limits, but is solid for a read-style retrieval tool.

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

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

The description is three sentences with no filler. It front-loads the core action, then enumerates return details, then adds the temporary-URL caveat. 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?

There is no output schema, so the description must explain return values, and it does so in detail: highlight title/cover and each story's media URLs, timestamps, stickers, mentions, tags, location, audio, and AI detection. It also covers the practical expiry of media URLs, making it complete 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%, so the schema already documents the highlight_id parameter. The description reinforces that the value can be an ID or URL and points to instagram_user_highlights as the source, but it adds little beyond the schema's own parameter description.

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

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

The description names a specific verb and resource: 'Get the stories saved in one Instagram highlight' by ID or URL. It clearly lists the returned data and names the source function 'instagram_user_highlights', distinguishing this tool from sibling highlight/story tools.

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

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

The description tells the agent to pass a highlight ID from instagram_user_highlights or a highlight URL, establishing the workflow and indicating when this tool is relevant. It does not explicitly mention exclusions such as 'use instagram_user_stories for non-highlight stories', but the context is clear enough.

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

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

Despite having no annotations, the description discloses pagination (up to 15 per page), billing behavior (per page), sort modes, pinned-comment inclusion, and a full list of returned fields including the unusual 'AI-generated profile' label. It does not discuss error handling, authentication, or rate limits, so it falls just short of complete transparency.

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

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

Every sentence in the description carries operational value—scope, return payload, pagination/billing, sort behavior, alternative tool, and input constraint. It is front-loaded with the core purpose and contains no filler or repeated boilerplate.

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

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

The description is complete for an agent to call this tool: it specifies how to identify the target (URL or code), what fields to expect, how pagination and sorting work, cost implications, and which sibling to use for replies. No output schema exists, but the description covers the key response content.

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

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

Schema coverage is 100%, so the schema already documents each parameter; the baseline is 3. The description adds meaningful extra constraints: url and code are mutually exclusive, pages are billed per page, and the default sort includes pinned comments, which goes beyond 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 ('Get') and resource ('comments on an Instagram post or reel') and identifies access modes (URL or shortcode). It clearly distinguishes itself from sibling tools like instagram_comment_replies and instagram_post_likes by describing exactly what it returns.

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

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

Explicitly tells the agent when to use it: to fetch comments on a post/reel, and directs it to instagram_comment_replies for a comment's replies. Also gives an input-selection rule ('Provide exactly one of url or code'), leaving no ambiguity about invocation choice.

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

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

With no annotations at all, the description carries the full burden and does well: it enumerates the exact fields returned (caption, counts, media URLs, carousel slides, audio info, tagged users, location, author details, AI label) and imposes the exactly-one input constraint. It does not disclose error behavior, rate limits, or what happens if both/neither url and code are supplied, which keeps it from a 5.

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

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

Two focused sentences with no filler. The first sentence states what the tool gets and how to specify the target; the second sentence enumerates the return payload. Everything 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?

Even though there is no output schema, the description enumerates the expected return fields, giving the agent a solid mental model of the response. The input selection rule is explicit, and the tool is a simple single-post fetch, so 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 value above the schema by stating 'Provide exactly one of url or code' — an exclusivity constraint the schema does not enforce. It also reinforces the semantics of url/code by saying 'by post URL or shortcode.' It does not elaborate on get_sentiment, but the schema already documents that fully.

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

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

The description opens with a specific verb ('Get full details') and a precise resource ('a single Instagram post, reel, or IGTV video'), then names the input forms (URL or shortcode). It clearly differentiates from sibling tools like instagram_post_comments and instagram_post_likes by promising the full post payload rather than a subset.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 makes the selection context clear: this is the 'full details' tool for any single Instagram post, as opposed to the comments, likes, or user-posts siblings. It also gives the key invocation rule, 'Provide exactly one of url or code,' which is operational guidance. It does not explicitly name sibling alternatives or state when not to use it, 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?

With no annotations provided, the description carries the full disclosure burden. It goes beyond the schema by stating the scope ('every liker Instagram exposes'), typical volume ('typically several hundred'), and that results arrive 'in a single request.' It does not discuss rate limits or authentication, but for a read-only retrieval tool the key behavioral traits are disclosed.

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

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

Three efficient sentences cover the action, the returned data, and the input constraint. There is no filler and no repetition of schema field descriptions.

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

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

Since there is no output schema, the description sufficiently explains what the caller will receive: username, full name, user ID, verification and privacy status, profile picture, and total like count. It also resolves the one-of parameter ambiguity. Nothing essential for making the call correctly is missing.

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

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

The input schema already describes url and code with 100% coverage, so the baseline is 3. The description adds the crucial mutually-exclusive rule ('Provide exactly one of url or code') and clarifies that the tool accepts both posts and reels, which is not captured by the schema's empty required list.

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

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

The description opens with a specific verb and resource: 'Get the users who liked an Instagram post or reel,' and states the two accepted input forms, URL or shortcode. It clearly distinguishes itself from sibling tools like instagram_post_comments and instagram_post_details by focusing on the list of likers.

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

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

The intended use case is clear: call this when you need the users who liked a specific Instagram post or reel. It does not explicitly name alternatives or exclusion conditions, but the purpose is specific enough that an agent can infer when it applies and when a sibling like instagram_post_details would be more appropriate.

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

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

With no annotations, the description carries the full transparency burden, and it excels: it discloses pagination size (50 per page), billing behavior ('billed per page returned'), the verified-account first-page-only limitation, and that query mode ignores pages. These are non-obvious behavioral traits an agent needs to avoid unwanted costs or incorrect expectations.

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

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

Five compact sentences, front-loaded with the core purpose and followed by return-field, pagination, billing, and query-mode details. Every sentence carries operationally relevant information without filler or repetition of schema text.

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

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

For a 4-parameter tool with no output schema, the description covers input selection, mode selection, return fields, pagination, billing, and a critical limitation. There is no output schema, so the explicit list of returned fields is essential and provided. Nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant semantic value beyond the schema by stating 'Provide exactly one of username or url' — critical because no parameters are required in the schema. It also reinforces that query mode replaces pagination, though this is already in the schema.

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

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

Description opens with 'Get an Instagram user's followers by username or profile URL,' naming a specific verb and resource. It also lists the exact returned fields (username, full name, user ID, verification/privacy status, profile picture), making it unmistakable from siblings like instagram_user_following or instagram_user_profile.

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

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

The description gives clear context on how to use query mode vs paginated browsing ('Pass query to search the followers instead'), the verified-account limitation, and the mutual-exclusion constraint ('Provide exactly one of username or url'). It does not explicitly compare against sibling tools such as instagram_user_following, but the purpose wording makes the differentiation evident.

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

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

No annotations are provided, so the description carries the full burden. It discloses billing per page returned, pagination of 50 per page, and the distinct behavior of the query parameter (single request, ignores pages). It does not mention rate limits or errors, but the core behavioral aspects relevant to selection and invocation are covered.

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

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

The description is concise and front-loaded, with the primary purpose stated first. Each sentence adds useful information (fields returned, pagination, billing, query alternative, parameter constraint). No filler or repetition.

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

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

With 4 parameters, no output schema, and no annotations, the description covers the key operational aspects: required parameter choice, pagination, billing, and query behavior. It does not specify error scenarios or access prerequisites, but these are not essential for basic invocation and are not expected given the tool's simplicity.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema by explaining the mutual exclusivity of username/url, the interaction of query with pages, and the pagination semantics. This helps the agent understand how to combine parameters correctly.

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

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

The description clearly states the tool retrieves the accounts an Instagram user follows, by username or URL, and lists the returned fields. This distinguishes it from siblings like instagram_user_followers (which gets followers) and instagram_user_profile (which gets a single user's profile).

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

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

The description gives explicit usage constraints: 'Provide exactly one of username or url' and clarifies that the query parameter searches within the following list, with pages ignored. It does not name sibling tools as alternatives, but the tool's purpose is self-evident from its name and description, so the context is clear without 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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly discloses the operation type ('Get'/'Returns') and lists the returned fields (ID, title, story count, cover image, dates, link), which conveys read-only behavior and output shape. It does not mention edge cases like private accounts or rate limits, but for a simple read tool this is reasonably transparent.

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

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

Three short sentences with no filler. The action and input method are front-loaded, then return fields are listed, and the sibling-tool routing and the one-of constraint are stated last. Everything earns its place.

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

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

For a simple two-parameter read-only tool with 100% schema coverage, the description covers what the tool does, its inputs, its output fields, and the relationship to the companion tool. No critical information 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% and already explains URL and username formats. The description adds meaningful value by specifying the mutually exclusive requirement 'exactly one of username or url,' which is not encoded as a required field in the schema. This reduces ambiguity about how to select between the two parameters.

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

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

The description uses a specific verb and resource: 'Get an Instagram user's story highlights tray by username or profile URL.' It clearly distinguishes from the sibling instagram_highlight_stories by noting that the tray is the top-level collection and referencing the sibling for stories inside a highlight.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states exactly when to use the alternative: 'Use instagram_highlight_stories with a highlight_id to fetch the stories inside a highlight.' It also enforces an input rule with 'Provide exactly one of username or url,' making the calling contract explicit.

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

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

With no annotations, the description carries the behavioral burden and does substantial work: it discloses pagination ('Up to 12 posts per page'), billing ('billed per page'), identifier exclusivity ('Provide exactly one'), and the specific content fields returned. It does not mention rate limits or authentication, but the core behavior is well disclosed.

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

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

The description is compact and front-loaded, starting with the action and resource, then listing return fields, then pagination/billing, then the exclusivity constraint. Every sentence adds operational value, and there is no fluff or repetition.

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

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

Despite having no output schema or annotations, the description provides enough to invoke the tool correctly: how to identify the user, what is returned, pagination limits, cost implications, and the required one-of constraint. No critical operational detail is missing for making 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 coverage is 100%, so the baseline is 3, but the description adds a critical constraint not present in the schema: 'Provide exactly one of url or username.' It also clarifies page-level behavior and cost, going slightly beyond the schema's individual parameter descriptions.

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

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

The description states a clear action ('Get') and a specific resource: a single Instagram user's recent posts and reels. It lists the identifier options (profile URL or username) and enumerates the returned data, making it readily distinguishable from sibling tools like instagram_user_profile or instagram_user_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?

The description gives clear context for use: fetching one user's feed, with posts and reels, by URL or username. It does not explicitly name alternative tools or when not to use this one, but the scope is clear enough for an agent to select it over profile, story, highlight, or hashtag tools.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly conveys this is a read operation, enumerates the returned profile fields in detail, and warns that exactly one identifier must be supplied. It does not discuss rate limits or error cases, but for a read-only profile lookup the behavioral expectations are well conveyed.

Agents need to know what a tool does to the 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 resource, then delivers a compact but complete list of return fields and a clear usage constraint in only two sentences. No verbose or redundant wording is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 simple two-parameter schema and no output schema, the description covers the input constraint and enumerates the key return fields, which is sufficient for an agent to invoke the tool and understand the response. It does not specify behavior for private/deactivated profiles or error handling, but these are minor gaps for this straightforward lookup.

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

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

The schema already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantic value by specifying that exactly one of username or url is required and framing the url as a profile URL, which helps an agent choose between the two parameters correctly.

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

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

The description opens with a specific verb and resource ('Get the full profile for a single Instagram user') and clearly distinguishes this from sibling tools like instagram_user_followers or instagram_user_posts by focusing on the complete profile. It also names the accepted input forms, username or profile URL, making the tool's scope 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 gives clear context for when to use the tool: fetching a single user's profile data. It also provides an explicit usage rule, 'Provide exactly one of username or url,' which prevents ambiguous calls, though it does not explicitly name alternative tools for scenarios like follower lists or 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?

With no annotations provided, the description carries the transparency burden and does well: it discloses the return fields, states that media URLs are temporary (~6-24 hours), and explains the empty-list behavior for users without active stories. It does not mention error cases for private accounts or invalid username/URLs, but the provided disclosures are substantive and useful.

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

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

The description is compact yet information-dense: it states the main action, result contents, temporal constraints, the empty-list case, and the key parameter rule in four sentences. Every sentence contributes actionable information without repetition or fluff.

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

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

For a two-parameter read tool with no output schema, the description fully covers the essential invocation context: input format ('username or profile URL'), required parameter exclusivity, returned data fields, URL expiry, and empty-result behavior. An agent has enough information to select and call this tool correctly.

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

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

The input schema already documents both parameters with useful examples)Skip, so baseline is 3. The description adds meaningful semantic value by stating 'Provide exactly one of username or url,' which establishes mutual exclusivity not present in the schema. This clarifies a likely edge case and helps the agent invoke the tool correctly.

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

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

Description clearly states the tool retrieves currently active Instagram stories from the last 24 hours by username or profile URL. The phrase 'currently active stories' distinguishes it from permanent or archived stories (e.g., instagram_highlight_stories, instagram_user_highlights). It also enumerates the returned content, leaving 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 clear temporal context—stories are only those active in the last 24 hours—and notes the empty-list case, which helps an agent decide when to call this tool. However, it does not explicitly name alternatives like instagram_highlight_stories or instagram_user_highlights for non-active stories, so it stops short of full when-not-to-use guidance.

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

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

With no annotations, the description carries the burden of disclosing behavior. It lists the exact return fields, which is useful, but it does not disclose potential failure scenarios (e.g., invalid URL, missing data) or whether any special permissions are required. The behavior is a simple read, but edge cases are not addressed.

Agents need to know what a tool does to the 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 sentence that directly states the action and lists the return fields. Every word contributes to understanding, with no redundancy or unnecessary detail.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers input (URL) and output (specific fields). It does not mention error handling or the need for prior search, but given the low complexity, the description is sufficiently complete.

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

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

The input schema already provides 100% coverage for the url parameter with a description ('LinkedIn company page URL'). The tool description merely repeats 'by URL' without adding extra meaning, such as URL format examples or constraints. Since schema fully documents the parameter, baseline 3 is appropriate.

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

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

The description explicitly states 'Get detailed information about a LinkedIn company page by URL' and enumerates the specific fields returned (name, description, employee count, etc.). This clearly distinguishes it from siblings like linkedin_company_posts (posts) and search_linkedin_companies (search).

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

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

The description clearly implies the use case: you need a LinkedIn company URL to retrieve detailed metadata. It mentions the URL requirement but does not explicitly contrast with alternatives such as search_linkedin_companies or note when not to use the tool. Context is clear, but exclusions are missing.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It states that the tool returns engagement metrics, which is useful, but it does not disclose URL format requirements, ordering of posts, meaning of 'recent', rate limits, authentication needs, or error behavior. For a read operation this is a moderate gap, but not a complete black box.

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

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

The description is two sentences with no redundancy. The core action, input, and output summary are all front-loaded in the first sentence, and the second sentence adds relevant detail about the returned engagement metrics.

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

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

The tool is relatively simple with one required parameter and schema-covered optional parameters, but there is no output schema and no annotations. The description partially covers return values by listing engagement metrics, yet it leaves ambiguity around pagination semantics, the meaning of 'recent', and expected URL format. Sufficient for a straightforward call, but not fully 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 all three parameters and their defaults. The description adds minor context by indicating the result focuses on engagement metrics, but it does not meaningfully expand on the meaning of page or get_sentiment beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('recent posts from a LinkedIn company page by URL'), clearly distinguishing this from sibling tools like linkedin_company_details, linkedin_person_posts, and linkedin_post_details. The 'by URL' qualifier reinforces exactly what input is expected.

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

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

There is no guidance about when to use this tool versus alternatives. It does not mention that company details should use linkedin_company_details, that individual posts should use linkedin_post_details, or that person posts should use linkedin_person_posts. Any such distinction is only implied by the tool name and resource wording, 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?

With no annotations provided, the description carries the full burden. It discloses that the tool returns a comprehensive set of fields (title, company, location, date, type, etc.), giving the agent a clear picture of the response behavior. The word 'Get' implies a read-only operation, though it does not explicitly state non-destructiveness or error conditions. Still, it provides substantial behavioral context.

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

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

The description is a single, focused sentence that front-loads the action ('Get detailed information') followed by the resource and a concise list of returned fields. Every word adds value, with no redundant or verbose phrasing.

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

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

This is a simple single-parameter read tool with no output schema and no annotations. The description fully covers what the tool does, how it is invoked (URL or ID), and what it returns (all major job attributes). For its complexity level, the description is complete and self-sufficient.

Complex tools with many parameters or behaviors need more documentation. 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 the url parameter already described as 'LinkedIn job URL ... or numeric job ID.' The tool description adds no new parameter semantics beyond repeating that the input can be a URL or numeric ID. This meets the baseline for parameters already well-documented in the schema, but does not elevate it.

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

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

The description uses a specific verb and resource: 'Get detailed information about a specific LinkedIn job listing.' It clearly differentiates from sibling tools like search_linkedin_jobs by focusing on a specific listing by URL or ID. It also enumerates the returned data fields, making the tool's purpose unambiguous.

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

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

The description clearly implies when to use this tool: when you have a LinkedIn job URL or numeric job ID and need detailed information. It does not explicitly mention alternatives or exclusions, but the 'by URL or numeric job ID' qualifier provides clear context that this is for retrieving a single job's details, not for searching or listing jobs.

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

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

With no annotations, the description carries the full burden. It explains the return payload (posts, engagement metrics, author info, images, videos, articles), which gives a reasonable model of a read-only list endpoint. However, it does not disclose limitations such as how 'recent' is defined, rate limits, pagination bounds beyond the schema, or failure 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?

A single dense sentence front-loads the action and resource, then efficiently lists the return contents. There is no filler or redundant phrasing, so every word earns its place.

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

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

For a low-complexity list endpoint with a fully documented schema, the description covers the core inputs and gives an adequate summary of the output shape since no output schema exists. It is missing minor edge-case context like authentication or error behavior, but is not critically incomplete.

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

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

Schema description coverage is 100%, so the schema already documents url, page, and get_sentiment. The description mostly restates the url parameter ('profile URL or public slug') and adds no meaningful parameter semantics beyond the schema, which is the baseline case.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Get'), resource ('recent posts authored by a LinkedIn person'), and method of identification ('profile URL or public slug'). It clearly differentiates from sibling tools like linkedin_company_posts (company vs person) and linkedin_post_details (single post vs list of recent 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?

The description establishes a clear usage context: use this when you need recent posts from a specific LinkedIn person and have their profile URL or slug. It does not explicitly state exclusions or name alternative tools, but the context is clear enough for an agent 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?

No annotations are provided, so the description carries the behavioral burden. It does convey that this is a retrieval operation and previews the return payload, which is useful. However, it does not mention authentication requirements, rate limits, public-post accessibility, or failure behavior, leaving a moderate transparency gap for a no-annotation tool.

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

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

The description is a single, well-structured sentence with no filler. It front-loads the core purpose and immediately specifies what the caller can expect in the response. Every part earns its place.

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

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

For a straightforward two-parameter retrieval endpoint, the description combined with the schema is largely sufficient: it names the required input, scopes the target, and describes the expected output categories. It omits edge-case caveats such as URL validity or privacy restrictions, but these are not essential for basic tool selection and 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?

The schema already covers both parameters at 100%: 'url' has a direct description and 'get_sentiment' has a detailed explanation. The tool description adds little beyond restating the URL requirement and does not clarify sentiment behavior. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states a specific action and resource: 'Get detailed information about a specific LinkedIn post by URL.' It also enumerates the return contents, which distinguishes it from event-like siblings such as linkedin_company_posts or search_linkedin. The scope is unambiguous and immediately actionable.

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

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

The description implies the use case: call this when you already have a LinkedIn post URL and need post-level detail. However, it does not name alternatives or explain when not to use it, such as when looking for company posts or person posts. The 'by URL' condition provides context, but explicit routing guidance is missing.

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

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

With no annotations, the description carries the burden. It explains that the tool lists skills and details the return contents (id, name, category, description, inputs), plus it clarifies that the tool is a starting point and that skills are playbooks. It does not disclose potential pagination, rate limits, or error behavior, but for a simple listing tool, the behavioral transparency 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?

The description is front-loaded with 'START HERE' and clearly structured in four sentences covering purpose, usage, return value, and next step. It is somewhat verbose due to long enumerations of outcomes and use cases, but every sentence contributes value, so it earns a 4 rather than a 5.

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

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

The description is complete for a simple tool: it explains what the tool does, when to use it, what it returns, and how to proceed (via get_skill). Since there is no output schema, the description's explicit mention of return fields adequately compensates. The guidance about common goals and playbooks adds rich context.

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

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

The schema description fully covers the only optional parameter 'category' with examples ('sales', 'recruiting', etc.), so schema coverage is 100%. The main description does not add anything about the parameter, but the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states that the tool 'Lists the ready-made API Direct skills' and explicitly enumerates what it returns ('each skill's id, name, category, what it does, and its inputs'). It also distinguishes itself from siblings by positioning as the entry point and referencing get_skill for running a skill, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Whenever the user's request looks like lead-gen, competitor/brand monitoring, recruiting, due diligence, deal sourcing or market research, call this FIRST to check for a matching playbook before improvising your own searches.' It names an alternative (improvising searches) and suggests a follow-up action (get_skill), though it does not explicitly state when not to use the tool.

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

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

With no annotations, the description carries the full burden. It discloses the read-only nature ('Get'), and details the return payload including a website scrape, photos sample, owner info, and more, giving a transparent behavioral picture.

Agents need to know what a tool does to the 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 sentence, front-loaded with the core purpose, followed by a detailed yet relevant list of return fields. Every clause adds value and the length is justified by the tool's comprehensive nature.

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

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

Given no output schema or annotations, the description is exceptionally complete: it enumerates the return fields, mentions the website scrape, and ties the input to search_places. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable semantics by explaining that place_id is the ChIJ... value from search_places, clarifying how agents should source this parameter. It also implies that country and language affect the returned details.

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

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

The description starts with 'Get full details for a Google Maps place by place_id', using a specific verb and resource. It clearly identifies the input (ChIJ... value from search_places) and distinguishes itself from sibling tools like place_photos and place_reviews by returning a comprehensive set of data.

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

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

The description states that place_id is the value returned by search_places, providing clear prerequisite context. It does not explicitly name alternative tools or when-not-to-use, but the 'full details' scope makes the tool's niche 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that photos and videos are returned together, that pagination works in pages of up to 10 items billed per request, and that results include URLs, coordinates, and timestamps. It stops short of discussing rate limits, authentication, or the meaning of 'type' values, but the disclosed behavior is substantial and accurate.

Agents need to know what a tool does to the 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, all information-dense and front-loaded. The first sentence states the primary purpose, the second details return fields and the media-type caveat, and the third explains pagination. No filler or repetition of schema fields.

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

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

Given the absence of an output schema, the description does well to mention the key returned fields (URLs, coordinates, timestamps) and clarify that the type field must be filtered client-side. It also explains pagination and billing. It could have added error conditions or examples of valid place_id, but for a read-only listing tool this is quite complete.

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

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

The input schema already provides 100% coverage for all four parameters, so the description's additional value on parameters is limited. It does reinforce the meaning of the pages parameter ('each page returns up to 10 items and is billed as one request'), but this information already exists in the schema description. Baseline 3 is appropriate when the schema is comprehensive.

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

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

The description opens with a specific verb ('Get') and resource ('photos and videos for a Google Maps place by place_id'), clearly differentiating from sibling tools like place_details or place_reviews. It also lists the main return fields (URLs, coordinates, timestamps), leaving 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 provides clear context for use: it is keyed by place_id, returns both photos and videos together, and instructs the client to filter by type. It also explains pagination behavior with the pages parameter. However, it does not explicitly state when to use this tool versus alternative media-fetching tools (e.g., if sibling tools also return media), though this is minor given the clear scope.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses pagination behavior (10 reviews per page), language filtering semantics (original language, not translation), and the effect of combining language with sort_by. It also mentions billing implications indirectly via the pages parameter description. It does not disclose rate limits or failure modes, but the disclosed behaviors are meaningful and non-obvious.

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

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

The description is three sentences and front-loads the core purpose. The first sentence states the verb, resource, and key input. The second adds return contents and pagination. The third explains language filtering and the sort_by tip. Every sentence earns its place, though the third sentence could be slightly tighter.

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

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

For a 7-parameter tool with no output schema and no annotations, the description covers the main behavioral aspects: what is returned, pagination, language filtering, and sort_by interaction. It doesn't describe the output structure in detail, but the absence of an output schema makes that a minor gap. The description is sufficient for an agent to call the tool correctly for common use cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the practical effect of the language parameter (filters to original language, not translated) and the strategic tip to combine language with sort_by. It also clarifies the pagination/billing relationship. This exceeds the baseline but doesn't fully explain all parameter interactions.

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

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

The description clearly states the tool retrieves user reviews for a Google Maps place by place_id, and enumerates the review contents (rating, text, author info, timestamps, photos, owner response). It distinguishes itself from siblings like place_details and place_photos by focusing specifically on reviews, and from facebook_page_reviews/trustpilot_company_reviews by naming the Google Maps place context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 concrete usage guidance: it explains pagination (up to 10 reviews per page), how the language parameter filters reviews, and recommends combining language with sort_by to surface a larger pool. It does not explicitly state when not to use this tool versus place_details or search_places, but the context is clear enough for an agent to select it for review retrieval.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses the return fields (ASIN, title, price, rating, Prime status, etc.), pagination behavior (~16 results per page), and available filters, which gives an agent a solid behavioral model of a read-only search operation. It does not go into rate limits or data freshness, but the disclosed behavior is substantially more than minimal.

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

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

The description is three tightly written sentences: what it does, what it returns, and what filters/pagination to expect. Every sentence adds value and the core action 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?

Given the tool's complexity (14 parameters, no output schema), the description covers the key contextual gaps: return fields, marketplace scope, filters, and page size. It does not enumerate every parameter, but the schema already handles that. A short mention that queries can also be ASINs would have made it fully complete, but the current level is strong.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents all 14 parameters. The description provides a useful high-level summary of filter categories and page size, but it does not add meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Search Amazon products by keyword') and adds a concrete scope ('across 24 marketplaces'). This clearly distinguishes it from sibling tools like amazon_product_details or amazon_seller_products, which target different lookup modes.

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

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

The description implies usage for keyword-based Amazon product discovery and lists filter capabilities, but it never explicitly states when to prefer this tool over alternatives like amazon_best_sellers or amazon_seller_products. There are no exclusions or when-not-to-use conditions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose a cost behavior ('Billed $0.003 per page'), which is useful for an agent making economical calls, and the schema already documents pagination and page size. However, it omits other behavioral context like rate limits, auth requirements, or response shape. The cost signal is real but limited.

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

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

Two sentences with zero waste; the core action is front-loaded and the billing caveat follows naturally. This is a model of concise, scannable tool description—every word 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?

The schema covers all parameter meanings, and the tool is a straightforward keyword search. However, with no output schema or annotation, the description does not tell the agent what fields/results to expect, nor does it mention any preconditions beyond the billing note. For a simple search tool this is minimally viable, but it leaves the return payload undocumented.

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

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

Schema description coverage is 100%, so the schema fully documents the six parameters and their formats. The description adds no parameter-specific semantics beyond the schema, such as query syntax or date formats, but it is not required to do so because the schema is complete. This aligns with the baseline of 3.

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

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

The description states a specific verb, resource, and scope: 'Search Bluesky posts by keyword.' The resource 'posts' distinguishes it from the sibling search_bluesky_users, though it does not explicitly name the alternative. It is clear but lacks an explicit sibling differentiation, so it does not earn a 5.

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

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

The description provides no guidance on when to choose this tool over the many alternative search tools (e.g., search_bluesky_users, search_twitter). It does not state exclusions, prerequisites, or context that would help an agent decide between this and a sibling. The only extra signal is billing, which is cost-related rather than usage-direction.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds the per-page billing detail, which is useful and not present in the schema's exact form, and 'Search' implies a read operation. However, it does not describe response contents, pagination limits beyond the schema, or any side effects or rate-limit considerations.

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

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

The description is two short sentences with the core action first and the cost signal second. There is no redundant or filler language; every word 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?

The tool is low-complexity and its schema covers parameters well, but there is no output schema or annotation, and the description does not explain what a returned page of users contains or how this differs from the generic search_bluesky tool. It is sufficient for invoking correctly but lacks full operational context.

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

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

The input schema already documents both parameters fully, including default, max length, page size, and billing per page. The description adds no new parameter-level meaning beyond restating that the search is by keyword.

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

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

The description uses a specific verb and resource ('Search Bluesky users') and clearly identifies the target as user accounts rather than posts or profiles. It does not explicitly name a sibling tool it replaces, but the platform/resource scope is enough to avoid most ambiguity.

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

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

No guidance is given about when to use this tool instead of similar siblings such as search_bluesky, bluesky_user_profile, or search_twitter_users. There are no exclusions, preconditions, or distinguishing use cases beyond what the name already implies.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It communicates keyword search and optional place scoping, but says nothing about pagination/billing behavior, date filtering, result format, ordering, or limits. For a search tool with no output schema, this is a notable gap.

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

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

The description is one short sentence that front-loads the primary action ('Search Facebook events by keyword') and then adds the single most important optional modifier. Every word earns its place with no fluff.

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

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

For a 5-parameter tool with no output schema and no annotations, the description covers the core query and optional location scoping but omits the date-range options, pagination semantics, and what the response looks like. It is minimally viable but not fully complete for agent decision-making.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds value for location_id by directing the agent to search_facebook_locations, though the schema already says the same thing, so it contributes limited new semantic meaning.

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

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

The description states a specific verb ('Search'), a clear resource ('Facebook events'), and the matching criterion ('by keyword'). It also distinguishes itself from sibling Facebook search tools (pages, posts, videos, locations) by naming 'events' and by pointing to the companion location tool for place-scoped searches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 invocation context: search by keyword, and optionally scope to a place using location_id resolved via search_facebook_locations. It doesn't explicitly state when not to use this tool or contrast it with other facebbook search siblings, but the event-specific resource and location resolution guidance make the intended usage 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?

No annotations exist, so the description is the only behavioral disclosure. It explains the output's purpose but does not mention handling of ambiguous names, multiple matching locations, no-result cases, or exact return format—important gaps for a resolver.

Agents need to know what a tool does to the 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, purpose first, every word earns its place. It is brief and highly scannable.

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

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

For a single-parameter resolver, the description fully covers purpose, input scope, and output usage via downstream tool references. No output schema is needed when the description points to the exact consumers.

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

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

Schema already defines 'query' with a description and max length. The description adds semantic narrowing by specifying accepted entity types (city, region, country), which is extra value beyond the schema.

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

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

The description uses a specific verb 'Resolve' and clearly states the resource (place name to Facebook location IDs). It distinguishes this from sibling content-search tools by framing it as a preparatory lookup step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when to use the tool (to obtain a location ID for scoping searches) and names two direct consumer tools (search_facebook_posts, search_facebook_events). This provides clear integration context and implicitly contrasts with alternative search tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Search Facebook pages by keyword' and does not mention result shape, pagination behavior, rate limits, or scope limitations like public pages only. This is a minimal statement rather than a transparent behavioral disclosure.

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

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

The description is a single sentence with no filler and the core action is front-loaded. It is structurally efficient, though slightly under-specified for the broader selection context; still, this is a genuine conciseness strength rather than a verbosity problem.

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

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

With no output schema and no annotations, the description is the only behavioral context available. It omits what returned page results look like, how results are ordered, and when this search should be preferred over neighboring Facebook search tools. This is too thin for confident tool selection among many siblings.

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

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

Schema description coverage is 100%, so the parameters are already documented and the baseline is 3. The description's 'by keyword' vaguely maps to the query parameter but adds no new information about pages, pagination, or billing. It neither improves nor harms parameter understanding.

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

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

The description clearly identifies the action: search Facebook pages by keyword. It is unambiguous about the resource type, but it does not differentiate this tool from siblings like search_facebook_posts, search_facebook_videos, or search_facebook_events, so an agent may need extra inference to pick the right one.

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

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

There is no guidance about when to use this tool versus alternatives such as search_facebook_posts, facebook_page_details, or search_facebook_locations. The description only restates the operation and provides no context, exclusions, or routing hints.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention any side effects, rate limits, pagination behavior, output structure, or whether the search is read-only. The schema already covers parameter descriptions, but the description adds no information about what happens when calling the tool (e.g., result format, potential errors, billing implications beyond what schema mentions).

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

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

The description is two sentences, front-loaded with the primary purpose. The optional location scoping is placed second, and the pointer to the sibling tool is efficient. There is no fluff or redundant detail.

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

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

With 7 parameters, no output schema, and no annotations, the description is too sparse. It does not state what the returned data looks like (list of posts with fields), how pagination works (pages param is billed per page but no indication of what a page contains), or any caveats about sentiment analysis. The agent would have to guess the response format, which is a significant gap for a search 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 all 7 parameters already have descriptions. The description adds value only for location_id by pointing to search_facebook_locations as the resolver, which is helpful but not present in the schema. It does not explain date formats, pagination semantics, or how sort_by interacts with date filters. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly states the action ('search Facebook posts'), the scope ('across all of Facebook'), and the optional location scoping via location_id, which also points to the sibling search_facebook_locations tool. This distinguishes it from other Facebook search tools (pages, videos, events) without requiring schema inspection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one explicit usage hint: use location_id to scope results, and resolve it via search_facebook_locations. However, it does not explain when to choose this tool over alternatives like facebook_page_posts (for a specific page) or search_facebook_videos. The 'across all of Facebook' phrase implicitly contrasts with page-specific tools, but it is not explicit about exclusions or preferred contexts.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Search Facebook videos by keyword' and does not mention pagination behavior, billing per page (though the pages parameter description mentions billing), rate limits, or what happens with invalid dates or empty results. The schema's pages parameter notes 'Billed per page,' which is useful, but the main description adds no behavioral context beyond the basic operation.

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

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

The description is a single, concise sentence that front-loads the core action and resource. It is efficient and not padded, though it could add a brief usage hint without becoming verbose.

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

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

For a search tool with six parameters and no output schema, the description is thin. It does not explain what fields the results contain, how pagination works, or how the sentiment option affects output. The schema covers parameter semantics, but the overall tool behavior and result shape are left unspecified, which is a notable gap for an agent deciding whether and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description itself adds no parameter-level meaning beyond the schema, but the schema's parameter descriptions are fairly clear (e.g., pages, sort_by, get_sentiment). Baseline 3 is appropriate because the description doesn't need to compensate for missing schema coverage.

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

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

The description 'Search Facebook videos by keyword' clearly states the action (search) and resource (Facebook videos), and the query parameter is the primary input. It is distinguishable from siblings like facebook_page_videos (which targets a specific page's videos) and search_facebook_posts (which targets posts), though it doesn't explicitly name those alternatives.

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

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

The description implies usage for keyword-based search across Facebook videos, and the schema provides sort/date/sentiment options that clarify how to refine a search. However, it does not explicitly state when to choose this over search_facebook_posts or facebook_page_videos, nor does it mention 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys a read-only web search, but gives no operational detail about result format, pagination, rate limits, platform coverage, or the sentiment-analysis surcharge mentioned in the schema.

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

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

The description is only one sentence with no filler, and the core action is front-loaded. It is suitably lean, though slightly under-specified for a tool with five parameters and many closely related sibling search tools.

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

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

With no output schema and no annotations, the description should explain more about what the agent can expect and how to choose this tool. It omits behavioral context, result expectations, and any differentiation from the many other search_* siblings, leaving the description incomplete for reliable tool selection.

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

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

Schema description coverage is 100%, and each parameter already has a clear description (page range, time filter, country code, query length, sentiment option). The tool description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

States a specific action ('Search'), a resource ('forum posts'), and a scope ('across the web'), making the core function clear. However, it does not explicitly distinguish itself from overlapping siblings like search_reddit or search_web, so it stops short of full sibling differentiation.

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

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

There is no guidance about when to use search_forums versus alternatives such as search_reddit, search_news, or search_web. The description only implies the use case through the resource name and provides no exclusions, prerequisites, or routing hints.

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

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

No annotations are provided, so the description carries the full burden. It discloses one useful behavioral detail (each post includes an AI label), but says nothing about pagination behavior, rate limits, authentication, or the overall structure of results. This is minimal for a tool with no annotation safety net.

Agents need to know what a tool does to the 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 purposeful: the first states the core action and resource, the second highlights a distinctive output field. No filler or redundancy. The most important information is front-loaded.

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

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

With no output schema and no annotations, the description is the only source of behavioral context. It covers the core function and one output detail, but omits what a typical result set looks like, whether pagination is automatic, and how errors are surfaced. Adequate for a simple search tool, but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. 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 all three parameters (query, pages, get_sentiment), so the baseline is 3. The description adds no additional parameter-level meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Search Instagram posts by keyword.' This clearly distinguishes it from sibling tools like search_instagram_users and instagram_hashtag_posts. The added detail about AI labels further clarifies what the tool returns.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention exclusions (e.g., hashtag searches should use instagram_hashtag_posts) or any context that would help an agent choose between this and other Instagram search tools.

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

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

Without annotations, the description carries the burden of behavioral disclosure. It usefully discloses that the result includes verification status and AI-generated profile labeling, which is more than a generic search description. However, it does not mention pagination, result limits, authentication requirements, or any other runtime behavior.

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

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

A single, well-formed sentence communicates the action and the key output fields without any filler. Every phrase earns its place and the core purpose is front-loaded.

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

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

For a simple one-parameter search tool with no output schema, the description is fairly complete: it specifies the input and summarizes the return fields. It could be more complete by noting result count or pagination behavior, but nothing critical is missing for invoking the tool correctly.

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