AIsa Go-To-Market

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

Annotations already declare destructiveHint=true and openWorldHint=true, so safety is covered. The description adds valuable behavior: independence of items (one failure doesn't cancel others) and per-call billing. These are not derivable from annotations and help the agent set expectations.

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

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

Three short sentences with zero filler. The action and limit are front-loaded. The phrase 'tool-router's batch_use' is redundant since it restates the tool name, but it's a minor flaw. Overall it is concise and well-structured.

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

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

With annotations covering destructive behavior and an output schema presumably describing results, the description covers the key operational aspects: concurrency limit, independence, and billing. It doesn't mention error reporting formats, but those likely live in the output schema. It is sufficiently complete for a batch tool.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no parameter-specific details. The calls parameter's description already explains the structure and batching context, so the baseline of 3 applies; the description doesn't need to compensate.

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

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

The description states a clear action (execute) and resource (operations) with a concrete limit (up to 20) and concurrency. It doesn't explicitly name the sibling 'use' for single operations, but the distinction is clear enough from the concurrency and limit. The redundancy of 'tool-router's batch_use' is minor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious context by disclosing the $0.02 per-call billing and that 4xx/5xx responses are not charged.

Agents need to know what a tool does to the 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 behavior and the billing caveat with no filler. The main purpose is front-loaded and every clause adds information.

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

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

For a simple read-only tool with only two required parameters, an output schema, and rich annotations, the description is complete: it states the returned metrics, target/date scope, and cost behavior. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both 'target' and 'date' are already fully documented in the schema. The description restates these concepts without adding new format, default, or edge-case details, so the baseline of 3 applies.

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

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

The description names a specific verb ('Return'), a specific resource (Ahrefs Domain Rating and Ahrefs Rank), and the exact scope (target domain, given date). It clearly differentiates from siblings like get_semrush_domain_overview and get_similarweb_ranking by calling out the Ahrefs-specific metric.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 choose this tool over the many sibling SEO/metric tools, nor does it mention exclusions or alternatives. The use case is only implied by the Ahrefs-specific naming.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the domain must be bare (not a URL), and the returned organization object contains a specific set of fields. It also notes that the returned id is needed for a sibling tool, which is valuable operational context. It doesn't mention rate limits or error behavior, but the annotations carry the main safety burden.

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

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

The description is compact and front-loaded: the core action and constraint appear in the first sentence, followed by the return shape and routing guidance. Every sentence earns its place, and the sibling references are concise 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?

For a single-parameter, read-only, idempotent tool with a full output schema, the description is complete. It covers the input constraint, the return object, the entry-point use case, and the alternatives. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents the domain parameter well. The description adds value by reinforcing the bare-domain requirement and clarifying that the parameter is the only one, plus explaining what the return object contains. This goes slightly beyond the schema's example and format guidance, so it earns above the baseline 3.

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

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

The description states a specific verb ('Enrich'), a specific resource ('one company by domain'), and the exact input format ('bare domain, not a full URL'). It also distinguishes itself from sibling tools by naming the alternatives for bulk enrichment and full-record retrieval, so an agent can tell it apart without opening schemas.

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

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

The description explicitly says to use this tool as the entry point when all you have is a domain, and names two alternatives with their conditions: post_apollo_organizations_bulk_enrich for several domains, and get_apollo_organizations_id for the full record including funding and technology detail. This is clear when-to-use and 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: the data is live, sourced specifically from Apollo's job board, and absence of postings is not proof of no hiring. This supplements the annotations without contradicting them.

Agents need to know what a tool does to the 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 carrying distinct value: what the tool returns, why it is useful, how to get the required ID, and a data-source caveat. No redundant words or filler.

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

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

The description covers the prerequisite, the use case, and the key caveat, while the output schema handles return values. For a tool with three simple parameters and rich annotations, 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 description coverage is 100% — all three parameters (page, per_page, organization_id) are fully documented with examples. The description adds nothing beyond the schema for these parameters, 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?

Description states the tool retrieves live job postings for a company by Apollo organization ID, specifying the exact resource (job postings) and the method (organization ID from Apollo). It also distinguishes the data source (Apollo's job board) from the company's career page, which differentiates it from other organization-related tools.

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

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

The description gives a clear use case (hiring signal) and a prerequisite (get organization ID from get_apollo_organizations_enrich). It also provides an important caveat about interpreting missing postings. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops just short of full guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context: it is free, stops before any spend, and explains how price.model varies (quoted, list, dynamic, composed). It also clarifies that suggested_max_price_usd has headroom. This goes beyond the annotation flags and gives the agent a clear model of what happens.

Agents need to know what a tool does to the 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 moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly 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?

The tool has an output schema, so return values need no description. The description covers the key behavioral aspects (no spend, pricing models, max_price headroom) and clarifies edge cases like routes without a price. For a read-only informational tool, this is complete enough for an agent to use it correctly.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds some nuance, such as how arguments affect pricing and that required parameters may be needed before a price can be quoted. It also clarifies with_quote's purpose (one round trip, spends nothing). These are useful but not essential given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain 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 purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

The description implies the tool is used to assess an operation before spending (e.g., 'A quote authenticates like a call but stops before any spend'), and the schema says 'One operation_id from search', hinting at a flow. However, it never explicitly states when to choose this over siblings like use or search, nor does it give exclusions. The guidance is implied, 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses that it searches via Google, returns a normalized shape consistent with a sibling tool, notes that the cursor is a Google page number (not an Instagram cursor), and gives an approximate response size (~78 KB). This adds substantial behavioral context beyond what annotations provide.

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

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

The description is a single paragraph that front-loads the core purpose, then adds critical usage details (media_type, cursor semantics, size) and a routing note. It is informative without being bloated, though it could be tightened by removing the size measurement which may be overly specific for an agent's selection decision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 4-parameter schema with enums, an output schema, and rich annotations, the description covers the search method, parameter nuances, sibling differentiation, and performance expectation. An agent has all necessary information to select and invoke this tool correctly without missing context.

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

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

Schema coverage is 100%, so every parameter is documented in the schema. The description adds meaningful nuance for the cursor parameter (explaining it is a page number) and clarifies media_type options ('narrow to reels'), which go slightly beyond the schema's basic descriptions. This justifies a score above 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 ('Finds') and resource ('public posts carrying a hashtag through Google'), and explicitly distinguishes it from the sibling get_instagram_reels_search by contrasting the search method. The purpose is unambiguous and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when to use this tool versus the alternative: 'To search caption keywords rather than a hashtag, use get_instagram_reels_search.' It also explains the media_type option for narrowing results, providing explicit usage context without leaving anything to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds measurable operational context ('Measured at about 18 KB and 13 seconds') and discloses that the tool relies on Google search results, which an agent can factor into cost and reliability decisions. No contradiction with annotations.

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

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

The purpose, cost, downstream chaining, and sibling routing are each valuable and the description is front-loaded. However, the first sentence enumerates roughly fifteen output fields, which is largely redundant with the existing output schema and makes the description longer than needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the output schema documenting return fields and annotations covering safety and open-world semantics, the description fills the remaining gaps: cost, search mechanism, and downstream integration. An agent has everything needed to decide whether and how to 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?

Schema coverage is 100%, and the description adds little beyond it: 'keyword or bio phrase' restates the schema's 'Bio or caption keyword/phrase to search for,' and the cursor behavior is already documented ('next Google results page number'). Baseline 3 is appropriate when the schema carries the parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain 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 scope: 'Searches Google for public Instagram profiles matching a keyword or bio phrase' and enumerates exactly what is returned. It differentiates from sibling search tools by naming get_instagram_search_hashtag and get_instagram_reels_search for post search, so an agent can distinguish profile-search from post-search without opening schemas.

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

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

Explicit when-not guidance is given: 'To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search.' The description also gives a downstream chaining instruction ('The numeric id feeds get_instagram_basic_profile directly'), which helps an agent plan multi-step workflows.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses pagination via cursor, page size semantics, payload sizes (104 KB vs 28 KB), exactly what trim=true keeps, and the relative-URL prefixing requirement. These are valuable behavioral details an agent needs to call the tool correctly and interpret results.

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

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

The description is dense but every sentence contributes: scope, pagination, field differences, size/trim tradeoff, URL provenance, and sibling routing. It is not overly long per the value it delivers, though the field list could arguably be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a rich output schema, annotations already covering safety, and this description covering pagination, payload size, field trim behavior, and URL construction, the agent has everything needed to select and invoke the tool correctly. No important gap remains.

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

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

Schema coverage is 100% with examples, so the baseline is 3. The description goes beyond the schema by explaining trim=true's effect on field subset and size, cursor-based pagination, and how to construct or validate the url parameter (relative board URLs need https://www.pinterest.com prefix). This adds meaningful context.

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

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

The description states a specific action ('Returns one page of pins') on a specific resource ('from a board URL') and explicitly distinguishes the result field subset from search results and pin detail. It also names the sibling get_pinterest_user_boards as the different tool for board lists, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on when to use this tool; it explains that board URLs come from search results' board.url or from get_pinterest_user_boards, and it directly routes the agent to get_pinterest_user_boards when a board list rather than one board's pins is needed. This is clear when-to-use and alternatives 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?

Beyond the readOnlyHint and idempotentHint annotations, the description reveals concrete behavioral details: approximate response size for 17 pins, the 28 KB trimmed size, exactly which fields trim retains and drops, and the fact that results include a paging cursor. This is additive and highly useful 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 dense but every sentence earns its place: a clear one-sentence purpose, a compact field enumeration, measurable size guidance, and sibling routing. It front-loads the core behavior before diving into payload details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 pagination, an optional trim mode, and a rich output shape, the description covers all essential operational context: result contents, size implications, field trade-offs, cursor usage, and related endpoints. The presence of an output schema further reduces any missing return-value ambiguity.

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

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

Although the schema already documents all three parameters, the description adds meaning beyond the schema: trim's field-level impact, the cursor's role in pagination, and the keyword matching behavior. It also clarifies the response shape per pin, making parameter choices more informed.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Searches Pinterest for pins matching a keyword and returns pins plus a cursor to page.' It clearly distinguishes the tool from sibling Pinterest tools by stating it is keyword-based and explicitly routes follow-ups to get_pinterest_board and get_pinterest_pin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 decision guidance: use trim only when full fields are needed, feed board.url to get_pinterest_board, and use get_pinterest_pin for engagement counts on a single pin. This tells an agent exactly when this tool and its alternatives are 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?

Beyond the readOnly/idempotent hints, it reveals the exact top-level paging shape ('more.has_more and more.cursor'), the nested replies structure, and an empirical size ('21 KB for 19 top-level comments'). This gives an agent concrete expectations for response shape and cost.

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

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

The core behavior and paging warning are front-loaded, but the first sentence lists many fields that the output schema likely already specifies, making it longer than necessary. The size estimate and routing guidance earn their place.

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

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

For a read-only post-comments tool, it covers the URL input, response fields, paging mechanism, result size, and the relationship to search siblings. Given the annotations and output schema cover safety and structured return values, 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?

Input schema coverage is 100%, with the url, trim, and cursor parameters already described. The description adds context around cursor/paging, but does not materially change how the parameters are invoked, 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?

Opens with 'Returns one post and its discussion from a post URL', naming the verb, resource, and input. It enumerates post and comment fields, and contrasts paging with get_reddit_search/get_reddit_subreddit_search, so an agent can tell it apart from sibling search tools.

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

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

Explicitly tells the agent to 'start from get_reddit_search or get_reddit_subreddit' to find posts worth opening, which frames when this tool is the follow-up. It also warns that paging differs from those siblings. It does not spell out exclusion cases such as when get_details would be preferred, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds substantial behavioral context beyond that: it discloses performance characteristics ('Measured at 8 to 16 seconds and 8 to 26 KB, the slowest endpoint here'), the pagination mechanism (after token), and the full list of fields returned. No contradictions with annotations.

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

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

The description is dense but front-loaded: the core purpose and paging mechanism appear first, followed by output details and parameter behavior, then performance and alternatives. Each sentence contributes information without redundancy. It's longer than minimal but justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 output schema is provided, the description doesn't need to enumerate return types, but it still lists key fields. It covers scope (all public subreddits), pagination, sorting, timeframe, performance, and alternatives. An agent has everything needed to decide when and how to 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning to sort ('accepts relevance, new, top and comment_count') and timeframe ('narrows the window'), and explains the after token's role in pagination. It does not explicitly describe trim, but the schema already documents it, and the description provides enough added value to warrant a 4.

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

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

The description opens with a specific verb and resource: 'Searches every public subreddit for posts matching a query and returns posts plus an after token to page.' It clearly distinguishes itself from sibling tools by naming get_reddit_subreddit_search and get_reddit_post_comments, so an agent can immediately tell this is the global search endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states when to use alternatives: 'To stay inside one community use get_reddit_subreddit_search, which is faster and pages with cursor rather than after; to read one post's discussion use get_reddit_post_comments.' This gives direct routing guidance with clear conditions, leaving nothing to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses page size ('about 18 KB for 24 posts'), the constraint error behavior (400 rather than ignoring timeframe), case sensitivity of subreddit names, and that results use an after token for pagination. No statement contradicts the annotations.

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

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

The description front-loads the purpose and then packs in field names, accepted sort values, a constraint, and sibling routing. It is largely efficient, though the sort value list and field list slightly overlap with schema/enum information.

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

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

With an output schema present and rich annotations, the description covers the remaining essentials: pagination token, sort/timeframe constraint, case sensitivity, response size, and related tools. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful parameter context beyond the schema: subreddit names are case-sensitive, timeframe only works with sort=top and the failure mode is a 400, and after is the pagination token.

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

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

The opening sentence specifies a concrete action and resource: 'Returns the post stream of one subreddit with an after token to page.' It also names sibling tools for search and metadata, so an agent can distinguish it from get_reddit_subreddit_search and get_reddit_subreddit_details.

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

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

The description gives explicit routing: use get_reddit_subreddit_search for searching inside the same subreddit and get_reddit_subreddit_details for metadata. It also warns that timeframe is only valid with sort=top and that other combinations return 400, so the agent knows when not to supply timeframe.

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

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

Beyond annotations declaring the call safe/read-only, the description adds important behavioral context: the $0.30 billing per successful call, no charge for 4xx/5xx responses, and semicolon-delimited response format. This is exactly the kind of non-obvious behavior an agent needs before invoking.

Agents need to know what a tool does to the 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 no filler: the core purpose and output fields come first, then cost/billing caveat, then response format. Every sentence earns its place and the most important operational detail (cost) is included without bloating.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-argument read-only tool with rich annotations and an output schema, the description covers output contents, billing behavior, error-charge behavior, and response format. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter target is already clearly documented with format and an example. The description adds no deeper parameter semantics, but the schema carries the full burden adequately, 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?

States a specific verb ('Return') and resource ('backlink profile summary for a root domain') and enumerates the exact fields returned. The description clearly distinguishes this from domain-overview or competitor tools in the sibling list, even without naming 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?

There is no guidance on when to choose this tool over alternatives such as get_semrush_domain_overview or get_ahrefs_domain_rating. The description defines what the tool does but does not state usage conditions, exclusions, or preferred alternative scenarios.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive, and the description adds genuinely useful behavioral context: it is billed $0.09 per successful call, 4xx/5xx responses are not charged, and the response is semicolon-delimited text. These are non-obvious facts an agent needs before calling.

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

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

Three short sentences with no filler: the core purpose is front-loaded, followed by billing terms and response format. Every sentence earns its place.

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

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

With a rich output schema, strong annotations, and an output schema present, the description covers the remaining operational context: cost, error billing behavior, and response format. Nothing required to safely call 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 description coverage is 100%, with domain and database already documented with examples and a default. The description restates the regional-database idea but does not add parameter-level meaning or constraints beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Return'), a clear resource ('organic search overview for a domain'), and enumerates the exact metrics returned. This lets an agent distinguish it from sibling tools like get_semrush_backlinks_overview or get_semrush_keyword_overview.

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

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

The intended use case is implied: retrieving domain-level organic search metrics for a given regional database. However, there is no explicit when-to-use guidance or exclusions compared to sibling SEMrush or Ahrefs tools, so the agent must infer routing.

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

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

Annotations already declare readOnly/openWorld/idempotent/not-destructive, and the description adds valuable context beyond them: the per-call billing cost ($0.09, with 4xx/5xx not charged) and the semicolon-delimited response format. No contradiction with the annotations.

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

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

Three tight sentences with zero filler. Purpose is front-loaded first, followed by billing disclosure and response format — each sentence earns its place and nothing is redundant.

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

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

For a simple 2-parameter read-only tool with a full output schema and comprehensive annotations, the description covers purpose, cost, and format. The only thing missing is routing guidance to related siblings, but the tool's simplicity and structured fields carry the rest.

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

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

Schema coverage is 100%, so the schema already documents both phrase and database parameters with examples. The description only reinforces this with 'keyword phrase in a given regional database', adding marginal value beyond the schema 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?

States a specific verb (Return) + resource (search metrics for a keyword phrase) + scope (regional database), and enumerates the exact metrics returned (volume, CPC, competition, results). This distinguishes it from siblings like get_semrush_backlinks_overview and get_semrush_domain_overview without needing to open their 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?

Provides no guidance on when to choose this tool over alternatives. Siblings get_semrush_organic_competitors, get_similarweb_keywords, and get_similarweb_keyword_competitors overlap in keyword topics, yet the description never tells an agent which to prefer or under what conditions. This is a clear gap.

Agents often have multiple tools that could apply. Explicit usage 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 adds substantial behavioral context beyond the annotations: per-row billing, a 20-row cap, no charges for 4xx/5xx responses, and semicolon-delimited text output. These details are not present in any structured field and are critical for cost-aware invocation.

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

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

Three short sentences, each earning its place: purpose, cost/limits, and response format. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

For a low-complexity tool with two primitive required parameters and an output schema, the description covers everything an agent needs: what it returns, cost constraints, row limits, and response formatting. 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%, with both `domain` and `database` having descriptions and examples. The description does not add parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly identifies the resource ('domains competing with a target') and the context ('Google organic search'), which distinguishes it from SEMrush backlinks, domain overview, and Similarweb tools. However, it lacks an explicit verb like 'Returns' or 'Lists,' so it falls just short of a 5.

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

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

The intended use case is implied: use this when you need domains competing with a target in Google organic search. But the description never explicitly states when to prefer this over sibling tools such as get_similarweb_keyword_competitors or get_semrush_domain_overview, and gives no exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds one useful behavioral detail: the response follows the SimilarWeb v5 envelope (meta + data). This is genuinely helpful context beyond the annotations, but nothing more is disclosed about pagination, error behavior, or data coverage limits. A 3 is appropriate given the moderate added value.

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

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

The description is a single short sentence, which is efficient, but it is under-specification rather than helpful conciseness. It front-loads a label but provides almost no operational information. For a 10-parameter tool, the terseness leaves the agent with nearly nothing to act on.

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

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

Despite having an output schema and rich parameter descriptions, the tool is complex (10 parameters, 3 enums) and the description contributes almost nothing. An agent cannot tell what data this returns (beyond the generic envelope), what makes it distinct from sibling SimilarWeb and Semrush tools, or when it is the right choice. The description is inadequate for the complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The input schema already documents every parameter with descriptions (e.g., web_source noting the 400 rejection for mobile_web/total, limit being billed as 20 if exceeded). The description adds no parameter semantics beyond what the schema provides, which is acceptable given the high schema coverage.

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

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

The description is essentially a label ('Keyword Competitors') that restates the tool name without stating what the tool does with a verb and resource. It mentions the response envelope format, which is useful, but it does not explain what 'keyword competitors' means operationally nor how it differs from siblings like get_similarweb_organic_competitors or get_similarweb_similar_sites.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 such as get_similarweb_keywords, get_semrush_organic_competitors, or get_similarweb_similar_sites. No context is given about the use case for keyword competitor data, and no exclusions or prerequisites are mentioned.

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

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

Annotations already declare the operation read-only and idempotent, and the description adds a surprising array-of-arrays response grouping, a 1–3 monthly-bucket date restriction, and a billing rule that counts rows across all groups. These are exactly the kind of non-obvious behaviors an agent needs before invoking.

Agents need to know what a tool does to the 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 two substantive sentences are dense and valuable, but the opening 'Website Keywords' is a tautological filler that occupies the front-loaded position. It should have been replaced with an actual action statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 100% schema coverage, an output schema, and safety-focused annotations, the description covers the remaining non-obvious contract details: date-range span, response grouping, and billing. Nothing needed to call the tool correctly appears missing, though the absent purpose statement lowers the overall 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?

With 100% schema description coverage, the baseline is met. The description goes beyond the schema by constraining the start_date/end_date span to 1–3 monthly buckets, which cannot be inferred from any individual 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 opening phrase 'Website Keywords' simply restates the title and implies an action only through the tool name. The rest of the description covers response shape and date constraints, not what the tool actually retrieves. It also does not differentiate it from the sibling get_similarweb_keyword_competitors.

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

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

No guidance is given about when to choose this tool over alternatives such as get_similarweb_keyword_competitors or other SimilarWeb siblings. The date constraint is a precondition for a valid call, not a usage rule.

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

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

Annotations already establish the operation as read-only, idempotent, and non-destructive, so the description's extra notes are valuable rather than redundant. It adds a concrete behavioral contract: the response follows the SimilarWeb v5 envelope (meta + data) and the date span must cover 1 to 120 monthly buckets.

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

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

The description is very short and front-loads the key constraint after a terse title-like opening. The first phrase 'Website Ranking' is redundant with the title, but the remaining two sentences are packed and free of filler.

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

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

Although the schema, annotations, and output schema are rich, the description itself fails to establish what the tool actually returns or when to prefer it over closely related SimilarWeb ranking tools. An agent gets the constraint details but not enough context to confidently select this tool among many similar 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 baseline is 3, but the description adds a useful constraint not present in the schema: start_date and end_date must span between 1 and 120 monthly buckets. This gives the agent actionable validation semantics beyond the individual field descriptions.

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

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

The description opens with 'Website Ranking,' which merely restates the tool title and name without a verb or a specific resource. It never states what the returned ranking means or what domain-related data is fetched, so an agent must infer the purpose from the name and 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?

There is no guidance about when to use this tool versus the many SimilarWeb siblings such as get_similarweb_website_traffic_trend or get_similarweb_traffic_engagement. The only stated constraints are the response envelope and a date-range rule, neither of which helps an agent decide between 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?

It discloses the SimilarWeb v5 response envelope, the exact-3-month upstream constraint, the specific upstream errors (120 and 101), the rolling monthly window, and a practical example. This goes well beyond the readOnly/idempotent annotations and clarifies the main non-obvious behavior of the API.

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

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

The description is dense and focused; the date-window guidance, error codes, and /describe pointer all earn their place. The opening one-word fragment 'SimilarSites.' is somewhat redundant with the title, but overall the section is tight and information-rich.

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

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

For a 10-parameter tool with a strict rolling date constraint and an output schema, the description thoroughly covers the one truly non-obvious behavior, gives an actionable example, and points to /describe for state that changes monthly. The schema covers parameter defaults/enums and the output schema covers return values, 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 description coverage is 100%, so the baseline is 3. The description adds real value for the date parameters—concrete example, exact error codes, and rolling-window semantics—rather than repeating schema text. Other parameters are left to the schema, which is complete.

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

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

The name and title ('get_similarweb_similar_sites' / 'SimilarSites') make the resource clear and distinguish it from sibling SimilarWeb tools. However, the description itself never explicitly states a verb+resource action like 'returns a list of similar sites for a domain'; it opens with the one-word title and moves straight to response envelope and date constraints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 date-usage guidance: request the three most recent completed months, and call the /describe endpoint to discover the exact currently-supported range. It does not discuss when to prefer this tool over sibling SimilarWeb tools, but the context is clear enough to prevent obvious misuse.

Agents often have multiple tools that could apply. Explicit usage 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 annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful behavioral context beyond that: the response follows the SimilarWeb v5 envelope and the date span must cover between 1 and 120 monthly buckets. These are concrete operational constraints an agent would need. It does not go into pagination or rate limits, but the output schema reduces the burden.

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

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

The description is short and front-loaded and avoids unnecessary prose, but the first sentence 'Traffic & Engagement.' adds no value because it just repeats the title. The envelope and date-constraint sentences are useful, so overall it is efficient but not every sentence earns its place.

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

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

For a 9-parameter tool, the description provides one key operational constraint and the response envelope, and the input/output schemas cover parameter details and return structure. However, it does not differentiate this tool from closely related SimilarWeb siblings, leaving an agent to infer when this specific 'traffic & engagement' call is appropriate. It is minimally adequate but with clear contextual 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 documentation covers 100% of parameters, so the baseline is 3, and the description adds meaningful semantic value to start_date and end_date by specifying the allowed 1–120 monthly-bucket span. This is beyond the schema's basic YYYY-MM format info, though no other parameters receive additional description-level clarification.

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

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

The description begins with 'Traffic & Engagement.', which simply restates the title and does not use a verb to state what the tool does. The envelope and date constraint sentences add operational detail, but the core purpose—'retrieves traffic and engagement metrics for a domain'—is only implied by the tool name.

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

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

The description gives no guidance on when to use this tool versus sibling tools such as get_similarweb_website_traffic_snapshot or get_similarweb_website_traffic_trend. The date-range constraint is a validity condition, not a usage guideline, and there are no stated exclusions, prerequisites, or 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: latest available month, maximum 10 rows, field names, and fixed worldwide scope. No contradiction with annotations is present.

Agents need to know what a tool does to the 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. The core output and constraints are front-loaded, and every clause adds information: time period, row cap, fields, coverage, and parameter restriction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 single-parameter tool with a rich output schema and strong annotations, the description is fully sufficient. It covers the relevant behavioral constraints and return-shape details without requiring an agent to open the schema or infer hidden limitations.

Complex tools with many parameters or behaviors need more documentation. 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% for the single required `domain` parameter, so the baseline is already covered. The description adds extra semantic value by clarifying that a country parameter is not accepted and that the fixed worldwide scope is part of the endpoint's behavior.

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

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

The description clearly identifies the resource (a domain's traffic) and the specific metric (top countries by share for the latest available month), and specifies the returned fields and row limit. It also distinguishes this endpoint from alternatives by stating that geography coverage is worldwide and fixed, with no country parameter accepted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 invocation: it returns country-level traffic share for the latest month and explicitly tells agents that a country parameter is not accepted, implying this tool is for worldwide breakdowns rather than country-filtered reports. It does not name a specific alternative tool, but the exclusion 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety. It adds useful behavioral context: the tool automatically selects the most recent available month and echoes the date range in meta.start_date/meta.end_date, which helps the agent interpret results. No contradiction with annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose and metrics; the second explains the automatic month selection and meta fields. 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?

With an output schema present, the description need not detail return fields. It covers the essential behavioral nuance (auto-selected month, meta echoing) and scope (domain + country). No missing information that an agent needs to call the tool correctly.

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

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

Schema coverage is 100%: both domain and country have descriptions, including the enum and default for country. The description adds no parameter-specific detail beyond what the schema already provides (e.g., it doesn't explain domain format or country restrictions beyond the schema). Baseline 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 states a specific verb ('get') and resource ('website traffic snapshot') and enumerates the exact metrics returned: visits, average visit duration, bounce rate, pages per visit. It is clearly distinguishable from sibling tools like get_similarweb_website_traffic_trend (trend) or get_similarweb_traffic_engagement (broader engagement) by the 'latest-month' qualifier and the single-object format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 retrieving the most recent month's snapshot ('latest-month traffic snapshot') and notes that the month is auto-selected, but it does not explicitly contrast with alternatives or state when not to use it. The guidance is implicit rather than explicit, so a 3 is 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds valuable context that the time window is selected automatically and echoed in meta.start_date/meta.end_date, which is beyond what annotations provide. It does not contradict any annotations.

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

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

The description is a single, focused sentence that front-loads the core purpose (monthly traffic time series) and includes the key behavioral detail about the window. No wasted words or redundancy.

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

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

With an output schema present and annotations covering safety, the description sufficiently explains the response structure and automatic window behavior. It could be more complete by noting when to prefer this tool over related Similarweb tools, but given the schema and annotations, it's adequate for 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?

Both parameters (domain and country) have full descriptions in the schema, covering their meaning and allowed values. The description text adds no additional semantic value beyond the schema, so the baseline of 3 for 100% schema coverage 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 returns a monthly traffic time series for a domain, which is specific and unambiguous. It differentiates from snapshot-style tools by emphasizing the time-series nature, though it doesn't explicitly name sibling alternatives like get_similarweb_website_traffic_snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the many similar Similarweb tools in the sibling list. There are no prerequisites, exclusions, or comparative use cases mentioned, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the return structure ('trend names and volumes under `trends`') and a usage flow, which goes beyond what annotations state. No contradictions.

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

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

The description is four sentences, each carrying relevant information: the core action, the use case, the return structure, and the next-step pointer. It is efficient and front-loaded, with no wasted words, though slightly longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with an output schema, the description covers the essential usage, return format, and follow-up action. It doesn't mention pagination or rate limits, but those are not critical for a read-only, idempotent tool and are not expected given the annotations.

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

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

Schema description coverage is 100%, so the schema already documents both `woeid` and `count` with descriptions and defaults. The description repeats the default count and WOEID reference but adds no new meaning beyond the schema, so a 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 states a clear verb and resource: 'Get the trending topics for a location' and specifies the output under `trends`. It distinguishes itself from siblings by naming the follow-up tool `get_twitter_tweet_advanced_search` for searching posts, so an agent can tell this is about trends, not tweets.

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

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

It provides an explicit use case ('real-time read on what a specific market is talking about... useful for timing content or spotting emerging stories') and directs the agent to a specific alternative tool for the next step. This clearly routes the agent to the right tool for the job.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable functional behavior: cursor-paginated with has_next_page and next_cursor, and sorting by Latest or Top. It does not contradict annotations. It could have mentioned rate limits or error behavior, but those are not essential given the annotations.

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

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

The description is compact, front-loaded with the core purpose, then provides operator support, pagination behavior, and sibling routing. Every sentence earns its place, and 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 an output schema and rich annotations, the description covers all necessary context: purpose, usage, operators, pagination, and alternatives. Nothing an agent needs 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description enhances the query parameter by listing supported advanced operators (`from:`, `to:`, `since:`, `until:`, `min_faves:`, `-filter:replies`), and explains cursor pagination. This adds meaning beyond the generic schema description 'The query to search for.'

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

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

The description clearly states the tool's purpose: 'Search X posts by keyword or query with X's advanced search operators'. It explicitly identifies itself as the primary entry point for content research when no tweet IDs or handles exist, and differentiates from sibling tools like get_twitter_user_search and get_twitter_user_tweet_timeline by naming them directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: 'This is the primary entry point for X content research when you do not yet have tweet IDs or handles.' It also gives clear alternatives: 'To search accounts rather than posts use get_twitter_user_search. To read one account's own posts use get_twitter_user_tweet_timeline.' No ambiguity remains.

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

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

Beyond the annotations that already mark it read-only, idempotent, and non-destructive, the description discloses cursor-based pagination, the default-only ordering constraint, and the return shape of full tweet objects with engagement counts. This gives the agent a clear behavioral model.

Agents need to know what a tool does to the 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: core action first, then use case, return behavior, and sibling routing. Every sentence contributes and none are redundant.

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

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

With an output schema present and rich annotations covering safety, the description supplies everything else an agent needs: purpose, alternatives, pagination, ordering behavior, and return contents. Nothing important 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 covers both parameters fully at 100% coverage, so the baseline is 3. The description mentions cursor-paginated behavior and the default ordering but does not add deeper parameter-level detail beyond the schema.

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

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

The description names a specific verb and resource: 'Get the direct replies to a tweet'. It also distinguishes this tool from get_twitter_tweet_replies_v2 and get_twitter_tweet_thread_context, making its scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when to use this tool ('read the discussion under a post'), when to prefer a sibling instead ('Prefer get_twitter_tweet_replies_v2 when you want to control ordering'), and when to use another tool for the opposite direction ('To follow a conversation upward... use get_twitter_tweet_thread_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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: pagination via has_next_page and next_cursor, default page size of 200, and the full user object fields returned. It does not mention rate limits or error handling, but that is not required given the annotation coverage and the read-only nature.

Agents need to know what a tool does to the 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 well-structured: it starts with the core action and ordering, then the return format and pagination, then use cases, and finally alternatives. Every sentence adds value, with no fluff. The key information is front-loaded, and the alternative references are concise yet complete.

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

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

Given the tool's moderate complexity (3 parameters, output schema present), the description covers purpose, usage, alternatives, return structure, and pagination. It even highlights a subtle trap (verified followers tool uses user_id, not handle). Nothing an agent needs to correctly call this tool is missing.

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

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

Schema description coverage is 100%, so all three parameters (cursor, pageSize, userName) have descriptions. The tool description reiterates that userName is a @handle and mentions the pageSize default and max, which are already in the schema. It does not add significant new meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool lists followers of a given X user identified by @handle, with ordering ('newest follower first') and pagination details. It explicitly differentiates from siblings by naming get_twitter_user_followings for the reverse direction and get_twitter_user_verified_followers for the verified subset, noting the latter's user_id requirement.

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

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

It provides explicit use cases ('audience analysis, mapping a competitor's follower base, or finding influential followers') and directs to alternatives with conditions (reverse direction → get_twitter_user_followings; verified subset → get_twitter_user_verified_followers, with a crucial caveat about handle vs. user_id). This leaves no ambiguity about when to use this tool versus 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds value by listing the specific returned fields (display name, bio, counts, verification, dates, etc.), which is useful context not in annotations.

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

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

The description is well-structured: it leads with the core purpose, gives usage context, lists returns, and then routes alternatives. Every sentence earns its place with no filler; the length is justified by the need to differentiate among siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read-only lookup with an output schema present, the description fully covers the call context, return fields, and alternatives. Nothing an agent needs to correctly invoke it is missing.

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

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

Schema coverage is 100% (the only parameter 'userName' is described as 'The screen name of the user'). The description reinforces this with '@handle (screen name)' but adds no substantive new meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('Look up') and resource ('one X (Twitter) user's public profile by @handle'). It explicitly differentiates from three sibling tools by naming them and the conditions that select each, making its 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?

Provides explicit when-to-use ('when you need to know who an account is — identity, reach, or credibility') and when-not-to-use conditions with named alternatives for numeric IDs, extended metadata, and posts. This fully routes the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those: it discloses that the endpoint is cursor-paginated and specifies the response shape under `data` with `has_next_page` and `next_cursor`. This is useful for an agent deciding how to call and consume the tool, even though it does not mention rate limits or error conditions.

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

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

The description is two sentences with no filler. It front-loads the core purpose, immediately mentions the primary input choices, and ends with the valuable alternative guidance. Every sentence contributes to the agent's decision-making.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 modest complexity (4 optional parameters), strong annotations, and full schema coverage, plus an output schema that documents the return structure, the description covers all needed context: usage trigger, alternative tool, pagination, and where the data lands. There is no missing information an agent would need to call it correctly.

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

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

Schema description coverage is 100%, so the parameter names and types are already documented. The description adds meaning by explaining the relationship between `userName` and `userId` (accepting either), and by framing `includeReplies` as optional in context. This goes beyond the raw schema, clarifying the intended usage of the 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 states a specific verb ('Get') and resource ('a user's most recent tweets'), and clearly distinguishes this tool from the sibling `get_twitter_user_tweet_timeline` by naming the exact alternative. It also clarifies the input types (userName or userId), 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 explicit guidance: use this tool when you have not resolved the handle to an ID, and use `get_twitter_user_tweet_timeline` when you already have the numeric ID and want the full profile-order timeline with parent-tweet expansion. This gives clear when-to-use and when-not-to-use instructions, naming the alternative directly.

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

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

Annotations already cover read-only and idempotent safety. The description adds pagination details (20 per page, has_next_page, next_cursor) and the unique time-window capability, which are valuable beyond the annotations. It doesn't mention rate limits or auth, but annotations cover the safety profile, so a 4 is appropriate.

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

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

Four sentences with zero waste. The core purpose is front-loaded, followed by a unique feature, usage guidance, return format, and an alternative — all in a tight, logical structure.

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

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

With an output schema present and annotations covering safety, the description provides all necessary operational context: pagination behavior, time window, usage scenarios, and a clear alternative. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minor context (e.g., that sinceTime/untilTime bound the range and are Unix timestamps), but it doesn't go beyond the schema's own descriptions. Baseline 3 is correct.

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

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

States precisely what it does: 'Get tweets that mention a given @handle' with a specific verb and resource. It also distinguishes from the sibling by naming get_twitter_user_tweet_timeline as the alternative for own posts, so an agent can tell them apart.

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

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

Explicitly says when to use: 'Use this for monitoring — brand mentions, inbound replies, reputation tracking' and gives the when-not with the alternative tool name. This is clear routing guidance.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: it is cursor-paginated, returns full user objects under `users`, and searches accounts rather than posts. This enriches the agent's mental model without contradicting annotations.

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

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

The description is concise and front-loaded with the core action, then adds only high-value details: usage scenario, pagination/return format, and the sibling alternative. Every sentence earns its place with no filler or repetition.

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

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

For a two-parameter, read-only tool with full schema coverage, an output schema, and rich annotations, the description covers everything needed to invoke it correctly: when to use it, what to pass, how pagination works, and what comes back. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents both `query` and `cursor` clearly. The description reinforces the meaning of `query` with examples like 'a company name, a topic, a partial handle', which adds slight context, but it does not substantially elevate understanding beyond the schema.

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

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

The description states a specific action ('Search X user accounts by keyword') and a clear resource, and explicitly distinguishes itself from tweet search by saying 'This searches accounts, not posts'. It also names the sibling `get_twitter_tweet_advanced_search` as the alternative, 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 gives explicit use conditions: 'Use this when you know roughly who you are looking for... but not the exact @handle.' It also directly states when not to use it by pointing to `get_twitter_tweet_advanced_search` for tweet content searches, providing both positive and negative guidance.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and open-worldchers. The description adds value by clarifying the required `engine` and `q` parameters)Skip; wait, that's parameter info. More importantly, it discloses the mapped path and that the upstream canonical path is not mounted, which is a useful behavioral caveat. No contradiction with annotations exists.

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

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

The description is four sentences and stays on-topic. It front-loads the main purpose)Skip; then provides required parameters, optional parameters, use cases, and a path note. It is slightly redundant with the schema's required fields and `engine` enum, but overall each sentence earns its place.

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

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

With an output schema present, the description need not explain return values. It adequately covers input requirements, optional parameters, practical use cases, and the mapped-path caveat. It could additionally mention pagination limits or token freshness, but for a read-only YouTube search tool this is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly paraphrases the schema by restating that `engine` and `q` are required and that `gl`, `hl`, and `sp` are optional. It adds a small amount of extra meaning by giving examples of advanced filters for `sp` (upload date, duration, result type), but not enough to raise the score significantly.

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

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

The first sentence identifies a specific action and resource: 'Search YouTube and get back matching videos, channels, and playlists.' This clearly distinguishes it from sibling tools for Instagram, Reddit, Pinterest, and Twitter search. The tool name and title reinforce the same purpose without 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?

The description explicitly lists three use cases: find video content on a topic, track a channel's recent uploads, and gauge video coverage. It does not name an alternative tool or explicitly say when not to use it, but the given contexts are clear enough for an agent to select it appropriately among sibling 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?

The description goes well beyond the annotations (readOnlyHint=true, openWorldHint=true). It discloses exactly what is kept per post (code, caption, counts, etc.), what is dropped (resolution variants, dash manifests, internal flags), the measured size reduction (632 KB to 20 KB), and confirms nothing is summarised or dropped. It also details pagination behavior with `next_max_id` and `more_available`. This is rich behavioral context that significantly aids an agent.

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

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

The description is well-structured and every sentence adds value. It opens with the core purpose, then details the content and size reduction, then clarifies exclusions and the alternative, and ends with pagination. It is front-loaded and free of fluff, making it efficient for an agent to parse.

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

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

Given the tool's complexity and the presence of an output schema, the description is complete. It covers the returned fields, exclusions, size reduction, pagination, and the alternative tool. An agent would have all necessary information to call it correctly and interpret the response without missing context.

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

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

The input schema has 0% coverage (no descriptions). The description explicitly explains the `next_max_id` parameter: 'Page with `next_max_id` from the previous response; `more_available` says whether another page exists.' However, the `handle` parameter is not explicitly described, though it is implicitly clear from 'public account' and the tool's name. Since coverage is low, the description compensates for one parameter but not the other, warranting a 4 rather than a 5.

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

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

The description clearly states the tool's function: 'One page of a public account's timeline, projected down to what fits a context window.' It explicitly contrasts itself with `get_instagram_user_posts`, making the purpose unambiguous and distinguishing it from siblings. The verb 'projected down' and the resource 'timeline' are specific and clear.

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

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

The description provides explicit guidance on when to use this tool versus the alternative: 'If you need any of those — downloading every resolution, building a player, forensic detail — call `get_instagram_user_posts` instead.' It also implies the appropriate use case (a compact digest for context windows) and explains pagination with `next_max_id`, leaving no ambiguity about selection criteria.

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

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

Annotations already mark this as read-only and non-destructive, and the description adds meaningful behavior beyond that: field flattening with a concrete path mapping (`edge_followed_by.count` → `followers`), measured size reduction from 380 KB to 15 KB, what is retained vs. dropped, and the one-display-URL-per-post rule. No contradiction with annotations.

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

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

Four compact sentences, front-loaded with the core purpose, followed by the field list, measured size, flattening detail, and alternative routing. Every sentence adds operational value with no wasted words.

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

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

The description plus the existing output schema cover almost everything an agent needs: scope, field semantics, size characteristics, relation to siblings, and return shape. The only meaningful gap is the undocumented `handle` input and any format restrictions. For a one-parameter public read tool, this is very close to complete.

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

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

The only parameter, `handle`, is never described in the definition. With 0% schema-description coverage, the description should at least state that `handle` is the Instagram username and whether a leading `@` is accepted, but it only mentions `username` as an output field. The input contract is left to inference.

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

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

Defines the resource (a public Instagram profile) and the transformation (a compact flat-card projection), then enumerates exactly which fields are kept. It explicitly contrasts itself with `get_instagram_profile`, so an agent can distinguish it from that upstream tool and from `instagram_posts_digest`.

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

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

Gives an explicit when-not signal: if the agent needs the untouched upstream response with every field and wrapper, call `get_instagram_profile` instead. It also explains that the returned numeric `id` feeds `get_instagram_basic_profile`, enabling intentional chaining for bulk enrichment. The size framing tells the agent when the compact digest is the right 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the tool is free, requires no key, and can direct users to a category-specific endpoint that lists tools directly rather than through search.

Agents need to know what a tool does to the 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 moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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

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

For a zero-parameter, read-only tool with an output schema and safety annotations, the description is complete. It covers what the tool returns, the free/no-key access model, and provides the category endpoint for specialized use, leaving no essential gap for an agent to call it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description includes a <category> placeholder only in the endpoint examples, not as a tool parameter, which is appropriate supplementary guidance rather than a parameter-semantics gap.

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

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

The description clearly states what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via 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 provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral detail: the side-by-side organizations/accounts return structure, pagination, and breadcrumbs that echo applied filters. It does not discuss rate limits or data freshness, but the annotations carry most of the safety burden.

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

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

Three sentences deliver action, return format, and usage guidance with zero filler. The key behavior is front-loaded and the sibling routing comes last, making the description easy to scan.

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

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

For a complex 18-parameter, 0-required-field search tool, the description covers what the tool does, what it returns, how results are scoped, and when to prefer a cheaper sibling. The output schema and rich input schema cover the remaining details, so nothing an agent needs to invoke it correctly is missing.

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

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

The description provides a high-level summary of filter categories ('name, domain, headcount, industry, location, funding stage and technologies'), which helps orient an agent but adds no syntax, formatting, or interaction details beyond what the input schema already documents. With 67% schema description coverage, the schema does most of the parameter-level heavy lifting, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Find companies matching criteria') and enumerates the filter dimensions, so an agent immediately knows what this tool does. It also clarifies the unusual 'mixed' behavior: results include both Apollo's global organizations and workspace-specific accounts, which distinguishes it from a simple company search. The explicit contrast with get_apollo_organizations_enrich further disambiguates it from a close 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 states the intended use case directly: 'Use it to build a target list.' It also names the alternative and gives the exact condition for choosing it: 'When you already know the domain, get_apollo_organizations_enrich answers directly and costs less.' This is clear when-to-use and when-to-use-something-else 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?

Despite annotations already declaring readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds non-obvious behavioral context: entries return 'last_name_obfuscated' and boolean flags ('has_email', 'has_direct_phone', etc.) instead of actual values, and 'Search tells you a match exists; enrichment reveals the contact details.' This shapes agent expectations about response content and cost in a way the annotations do not.

Agents need to know what a tool does to the 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 sentences with no filler: purpose first, then filter categories, return shape, deliberate withholding, and routing to enrichment. Every sentence earns its place and the most important distinction (search vs. enrichment) 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?

The description is strong overall, covering purpose, filtering, return structure, obfuscation behavior, and downstream tool usage. Minor deduction: it mentions 'industry' as a filterable dimension, but the input schema contains no explicit industry parameter, which could briefly mislead an agent looking for that parameter in the schema.

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

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

Schema description coverage is high at 85%, so the input schema already provides detailed semantics for page, per_page, person_titles, person_seniorities, and the rest. The description only summarily lists filter categories and mentions pagination, adding little beyond what the schema says. This matches the baseline of 3 when the schema does the heavy lifting.

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

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

Description opens with 'Find people matching criteria rather than enriching someone you already identified,' using a specific verb and resource that separates it from the people_match and bulk_match siblings. It lists concrete filter dimensions (title, seniority, location, domain, headcount) and explicitly names the sibling tools for enrichment, so the agent can distinguish this search tool without opening schemas.

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

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

The description explicitly states when to use this tool ('Find people matching criteria') and when not to ('rather than enriching someone you already identified'). It goes further by routing to alternatives: 'Feed the ids into post_apollo_people_match or post_apollo_people_bulk_match to get emails and phone numbers,' and clarifies that credits are spent at enrichment, not search.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a concrete behavioral detail beyond annotations: omitting organization_ids returns HTTP 422 with the exact error message. It also discloses the return contract (news_articles and pagination), which helps the agent predict the outcome.

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

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

Five short sentences, each carrying a distinct piece of information: scope, required parameter and failure mode, filter options, return shape, and intended use case. There is no filler or unnecessary repetition of schema details.

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

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

Given that a full output schema exists and the input schema is rich, the description still adds missing call context: prerequisite resolution, mandatory parameter behavior, filtering axes, pagination control, and the 422 failure condition. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 80% and the input schema already provides detailed documentation for all five parameters. The description adds the required-status consequence for organization_ids and sample categories, but mostly restates what the schema already covers. This matches the baseline expected for high schema coverage.

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

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

The description clearly identifies the resource as news coverage for specific companies and scopes it by required organization_ids, distinguishing it from generic search siblings like get_reddit_search or get_twitter_tweet_advanced_search. However, the action verb 'search' is supplied by the tool name/title rather than explicitly in the description, so it misses 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?

It explicitly tells the agent to resolve companies first, naming get_apollo_organizations_enrich and post_apollo_mixed_companies_search as prerequisite alternatives. It also explains when to use the tool: to catch a trigger event before reaching out. This is strong, actionable routing 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?

The description reveals that the call may not return a record for every domain and explicitly instructs comparing requested vs enriched counts. It also communicates a scale limit ('up to 10'). These behaviors go beyond the readOnly/idempotent annotations, giving the agent essential expectations about partial successes.

Agents need to know what a tool does to the 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 cover a distinct necessity: the core action, the input, the output/caveat, and the single-domain alternative. No fluff; the most important info 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 bulk read-only tool with an output schema, the description covers purpose, payload, count-obsessed output semantics, and sibling routing. It gives an agent everything needed to select and call the tool correctly.

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

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

The schema already documents `domains` as an array of bare domains with format guidance, so the description adds little on domain format. However, 'Enrich up to 10 companies' adds a max array-size hint not present in the schema, raising it above baseline.

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

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

The description states a concrete action ('Enrich up to 10 companies in one call'), ties it to the `domains` array, and explicitly contrasts with `get_apollo_organizations_enrich` for a single domain. This clearly distinguishes the bulk POST from its sibling GET.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 specifies the bulk use case ('up to 10 companies in one call') and directs single-domain needs to `get_apollo_organizations_enrich`. It also warns that not all input domains will resolve, which affects how the agent evaluates results.

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

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

Annotations already carry readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious behavior: credit consumption per record rather than per call, and the instruction to read `missing_records` because not every input may match. It does not contradict annotations.

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

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

Four tight sentences, each earning its place: purpose, request shape, response caveat, credit economics, and sibling comparison. The most important facts are front-loaded and there is no filler.

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

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

For a tool with 6 params (1 required), full schema coverage, an output schema, and annotations covering safety, the description adds the remaining decision-relevant context: batch size, credit costing, partial-match handling, and when to prefer this over the single-match sibling. Nothing an agent needs 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 description coverage is 100%, so the schema fully documents all six parameters. The description adds light clarity by explaining that `details` accepts the same identifier objects as `post_apollo_people_match`, and it ties credit cost to enriched records rather than the call itself. This is helpful but not transformative, so a 3 at baseline 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 'Enrich up to 10 people in one call' – a specific verb, resource, and scope. It explicitly differentiates from the single-person sibling post_apollo_people_match by noting the same identifier objects and pointing to the simpler single call for one person, so an agent can distinguish tools without opening schemas.

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

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

It gives a clear decision rule: 'Use this over a loop of single calls: same credits, one round trip,' and explicitly states the boundary case, 'For a single person post_apollo_people_match is simpler.' This is direct when-to-use versus alternative guidance with no ambiguity.

Agents often have multiple tools that could apply. Explicit usage 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 adds substantial behavioral context beyond the annotations: personal emails and phone numbers are withheld unless reveal flags are set, those reveals cost extra credits, phone numbers are delivered asynchronously to a webhook, and HTTP 200 can still mean no match. These details meaningfully inform an agent's expectations without contradicting the readOnly, idempotent, and non-destructive annotations.

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

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

The description is long but every sentence earns its place: the identifier list, the match-likelihood heuristic, the returned object shape, the hiding/credit behavior, the response caveat, and the sibling routing. It is front-loaded with the core action and uses the sibling distinction where it matters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 14 parameters, zero required parameters, and a rich input schema, the description covers all non-obvious behavior an agent needs to call it correctly: match probability, hidden data, costs, webhook delivery, match-failure semantics, and alternatives. The output schema exists, so return values do not need duplication in prose.

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

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

Since schema description coverage is 100%, the individual parameter documentation already carries the load. The description still adds value by grouping identifiers as a set, stating that supplying more identifiers increases match likelihood, and by explaining the credit/cost implication of reveal_personal_emails and reveal_phone_number.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Enrich one person' against Apollo's people records, and clearly states the input-to-output contract (identifiers in, full record back). It also explicitly names sibling tools, such as post_apollo_people_bulk_match and post_apollo_mixed_people_api_search, so an agent can distinguish this tool without opening schemas.

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

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

The description provides explicit when-to-use guidance: use this for single-person enrichment when you have at least one identifier, use post_apollo_people_bulk_match for up to 10 people, and use post_apollo_mixed_people_api_search when no identifier exists and candidates must be found first. It also warns that a 200 response does not guarantee a match, telling the agent to check the returned person object.

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

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

Annotations carry the safety profile (destructiveHint=true, readOnlyHint=false, idempotentHint=false, openWorldHint=true), so the description's smaller burden is partly met by adding 'real-time' and 'top 20 blocks' scope. However, a data-retrieval tool described as 'providing data' sits uneasily beside destructiveHint=true, and the description never reconciles this or notes that live calls incur cost. With annotations present, a 3 is warranted.

Agents need to know what a tool does to the 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, front-loaded with the data scope and followed by the location/language dependency. The 'see the List of Locations/Languages' cross-references earn their place; nothing is redundant, though it could be one clause shorter.

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

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

An output schema exists, so return-value detail is not required, and the 'top 20 blocks' note adds useful scope. Still missing for a single-nested-param live tool are the request body structure and any signal about when this YouTube SERP pull is preferred over its 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?

The description gestures at the location and language settings covered by the body array, but does not explain the body-array-of-objects structure, that keyword is required, or that location_code/name and language_code/name are paired alternatives. With reported schema description coverage at 0%, it only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain 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 resource and output shape: real-time YouTube search engine results, top 20 blocks. The YouTube qualifier implicitly separates it from the many Google/Bing SERP siblings, though it never names an alternative explicitly. A clear verb+resource, but not a deliberate sibling differentiation.

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

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

No when-to-use guidance, no mention of alternatives among the large SERP family (google_organic, bing_organic, google_maps, etc.), and no cost/quota context for a live call. It only notes that results depend on location/language settings, which is a constraint rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context beyond these: cost per successful result ($0.001), non-billing on certain error codes, typical latency (4–8s), the passthrough nature of the request body, and the returned content (AI answer text and cited URLs). It also discloses the 422 error for unsupported sources, all of which materially affect how an agent should use the 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 compact but information-dense: it opens with the core purpose and endpoint, then covers required fields, pricing, latency, error behavior, and explicit alternatives in a logical flow. Every sentence carries unique value, and the exclusion of LLM sources is front-loaded so the agent doesn't have to read far to avoid a wrong call.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 this complexity—passthrough behavior, cost, latency, error handling, and a clear sibling alternative—the description covers all essential aspects an agent needs to call it correctly and safely. It also references the output (AI answer text and cited URLs), and with an output schema present, the agent has complete information to integrate it.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value by prescribing how to combine parameters ('Send query with render: "html", parse: true, and a country-level geo_location') and by explaining the meaning of the source values. While the schema already documents each parameter, the description gives practical usage guidance that clarifies expected values and their interplay.

Input schemas describe structure but not intent. Descriptions should explain 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 ('query'), a precise resource (Google AI answer engines: AI Overviews and AI Mode), and the exact upstream endpoint. It clearly distinguishes this tool from the related LLM tools by explicitly naming post_oxylabs_llm and get_oxylabs_llm_job as the correct alternatives, so an agent can immediately tell what this tool is for.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it states that LLM sources are no longer served and instructs to use post_oxylabs_llm instead, including the exact HTTP 422 error that will be returned if misused. It also gives operational guidance on required fields (render, parse, geo_location) and a minimum client timeout of 30s based on expected latency, leaving no ambiguity about when and how to invoke it.

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

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

Annotations already cover the read-only/idempotent safety profile, but the description adds genuinely non-structured behavior: not_found with null value is a normal result rather than an error, and it is still billed as one valid lookup. It also states the one-creator-per-call constraint.

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

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

Four tight sentences, front-loaded with the core action, then parameter/response, then the billing caveat, then the sibling routing. No filler.

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

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

For a single-parameter lookup with an output schema and full annotation coverage, the description supplies everything an agent needs: input, normal-vs-error semantics, billing implication, cardinality, and sibling routing.

Complex tools with many parameters or behaviors need more documentation. 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 there is a single required parameter, so the schema already documents profile_url fully. The description only says 'Pass profile_url' and otherwise spends its words on output shape, adding little meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb (looks up), resource (contact email), scope (one creator), and the supported platforms (Instagram, TikTok, YouTube). An agent can distinguish this from the batch/search siblings without opening schemas.

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

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

Explicitly routes the agent: assemble a creator list with Similar Creators or AI Search first, then call this endpoint for the ones that return null emails. Names the alternatives and the condition that selects this tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world). The description adds genuinely non-obvious behavior: results are sorted by relevance score descending, and billing is per delivered creator tied to data.count, which is important cost context. It does not mention rate limits or error behavior, but the additions go meaningfully beyond the annotations.

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

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

Front-loaded with the purpose, then parameters, then return shape in three dense sentences with no filler. The enumerated field list is somewhat long and partly duplicates the output schema, which costs a bit of efficiency.

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

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

Covers purpose, required inputs, filter knobs, sorting, and billing, which is more than enough for a read-only search with a full output schema. The return-field enumeration is redundant given the output schema exists, but nothing an agent needs 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 description coverage is 100%, so the baseline is 3. The description goes further by summarizing limit's default and range and by grouping the filter families (regions, languages, follower/play-count ranges, gender, ethnicity, creator type, face visibility, workspace dedup) into a scannable overview that helps the agent plan a call without reading the nested schema.

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

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

States a specific verb and resource (finds creators similar to a seed account) and names all three supported platforms, so the agent immediately knows the scope. It is clearly distinguishable from the Apollo/Similarweb siblings and from the other waveinflu tools (ai_search, email_lookup).

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

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

Usage is implied by the purpose statement (find lookalike creators given a seed), and required vs optional inputs are spelled out. However, it never says when to prefer this over the sibling post_waveinflu_ai_search, nor any when-not conditions, so the routing guidance is left to inference.

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

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

The description discloses meaningful behavior beyond annotations: search spans the entire AIsa catalogue, candidates may belong to modules other than the current one, multiple providers for the same metric are surfaced, and no API key is required. This gives the agent a clear picture of scope and output behavior.

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

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

The description is front-loaded with the core purpose and is dense with useful information: scope, no-auth requirement, response shape, and relationship to the catalogue. Each sentence adds operational value, and the structure makes the tool's behavior predictable.

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

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

For a complex discovery tool with output schema, the description is unusually complete: it explains the response modalities, candidate fields, direct pass-through to `use`, full-catalogue search behavior, and cross-provider visibility. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining that the category parameter is not a hard boundary—search spans the full catalogue—and that queries are plain-language task descriptions, which clarifies how to use the tool effectively.

Input schemas describe structure but not intent. Descriptions should explain 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 finds AIsa data operations across many categories via a plain-language query. It distinguishes itself from siblings like get_details and use by emphasizing that search covers the full catalogue, not just the pinned category.

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

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

The description conveys when to use search: when you need to discover operations across the full catalogue, even those not in the current tools/list. It also implicitly contrasts with get_details by noting that returned candidates already include input_schema, so they can be passed directly to `use` without an extra call.

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

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

Annotations already provide readOnly=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavior beyond that: billing per call, the BatchCallResult response shape, and the error structure with retryable status. It does not spell out side effects, but the destructive flag is already carried by annotations, so the additional context is sufficient.

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

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

Three short sentences, each earning its place: purpose, cost, response shape, and routing guidance. Key behavioral facts are front-loaded, and nothing is redundant with the schema or annotations.

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

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

Given that an output schema exists and all parameters have descriptions, the tool description is complete enough for correct invocation. It covers cost, return/error contracts, and how routing to this tool differs from calling pinned tools directly, leaving no practical gap.

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

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

Schema description coverage is 100%, and each parameter is already clearly documented: operation_id as returned by search, search_id provenance, arguments matching input_schema, and max_price_usd as a spend guard. The description does not need to add parameter detail, 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 opens with 'Execute one AIsa operation,' a specific verb+resource statement. The word 'one' distinguishes it from the sibling batch_use, and the closing note distinguishes it from calling pinned tools directly. An agent can tell what this tool is for immediately.

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

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

It explicitly states when to use the tool: 'this is the way to call anything found through search.' It also gives the alternative: 'Pinned tools in tools/list can also be called directly.' This is clear when-versus-alternative guidance with no ambiguity.

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