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?

Annotations already mark the tool read-only, idempotent, open-world, and non-destructive, and the description adds meaningful behavioral context beyond that: it searches via Google, returns a specific normalised shape aligned with get_instagram_reels_search, uses Google page numbers as cursors, and mentions a typical response size of about 78 KB for ten posts. 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?

Dense but efficient: each sentence contributes unique value, from the post shape and optional '#' to media_type filtering, cursor semantics, payload size, and the alternative tool. The most important operational caveat (cursor is a Google page number) is explicitly called out, 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 read-only search tool with four parameters, a 100%-covered schema, an output schema, and rich annotations, this description is fully sufficient. It flags the Google-based search nature, clarifies the cursor meaning, gives sizing expectations, and points to the right alternative, leaving no operational gap 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 description coverage is 100%, so the baseline is 3; the schema already explains hashtag, cursor, media_type, and date_posted. The description repeats and reinforces key semantics like the optional '#' and the Google-page cursor, but adds little new parameter meaning beyond what the schema provides.

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

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

States a specific verb and resource: 'Finds public posts carrying a hashtag through Google,' and details the exact normalised return shape. It also differentiates itself from get_instagram_reels_search ('To search caption keywords rather than a hashtag, use...') and from the Instagram cursor semantics, making the tool's identity 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 usage guidance: set media_type=reels to narrow, or all for posts and reels, and names the alternative tool for caption-keyword searches. It also clarifies that cursor is a Google page number rather than an Instagram cursor, preventing a common 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds performance characteristics ('Measured at about 18 KB and 13 seconds'), explains the matched_from field's provenance, and clarifies the cursor semantics (next Google results page). It does not contradict annotations and adds meaningful behavioral context beyond the structured fields.

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

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

The description is moderately long but every sentence earns its place: purpose, field list, performance, downstream use, and alternatives. It is front-loaded with the core purpose and differentiators. The field enumeration is extensive but justified given the tool's rich output. Slightly more conciseness could trim redundancy, but structure is logical.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 present output schema and annotations covering safety, the description adds the performance, pagination behavior, and downstream linkage. It does not cover error cases or rate limits, but for a read-only search tool with a clear input schema, the missing details are minor. An agent has enough to call it correctly and interpret results.

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

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

Schema description coverage is 100% – both query and cursor are described accurately. The description adds little beyond the schema for parameters; it reiterates that query is a 'Bio or caption keyword/phrase' and the cursor is a page number, but doesn't provide extra nuance such as formatting or edge cases. Baseline 3 is appropriate when schema fully covers 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?

States a specific verb (Searches), resource (public Instagram profiles), and method (via Google), then enumerates the returned fields. It explicitly names sibling tools for posts, so an agent can distinguish it from get_instagram_search_hashtag and get_instagram_reels_search without inspecting 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?

Explicitly says when NOT to use it: 'To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search.' Also explains that the numeric id feeds get_instagram_basic_profile directly, giving downstream usage context. This is clear, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value beyond that. It discloses pagination via cursor, the trim behavior with concrete size measurements (104KB vs 28KB), and the specific field subsets returned. This is rich behavioral context not covered by 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 and informative, but it is longer than strictly necessary. However, every sentence contributes value—function, pagination, field differences, size, trim, URL source, and alternative tool. It is front-loaded with the core purpose and structured logically, so the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3 parameters, an output schema, and annotations covering safety, the description is exceptionally complete. It covers pagination, trim details, field subsets, URL construction, and the alternative tool. 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?

Although schema coverage is 100%, the description adds significant meaning to each parameter: url is explained as a board URL (relative and needing prefix), trim is described with its effect on response size and retained fields, and cursor is tied to pagination. This goes well beyond the schema's simple field names and descriptions.

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

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

The description states a specific verb ('Returns') and resource ('one page of pins from a board URL'), and explicitly differentiates from siblings like get_pinterest_search and get_pinterest_user_boards by mentioning the field subset differences and the alternative tool. An agent can immediately tell what this tool does and how it differs from others.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on when to use this tool: when you need pins from a specific board, and explicitly says to use get_pinterest_user_boards for a user's board list. It also explains where board URLs come from (search results or get_pinterest_user_boards) and how to handle relative URLs, which is critical for correct usage.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior. The description adds substantial context beyond that: response size measured at about 110 KB for 17 pins, exact size reduction with trim=true (28 KB), which fields are dropped, and the field-level return structure. This is exactly the kind of behavioral disclosure the dimension asks for.

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

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

Every sentence earns its place: purpose, return structure, size trade-off, and sibling routing are packed into a concise description. The main action is front-loaded, and the trim guidance is structured as a clear conditional.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 rich annotations, a complete output schema, and detailed return-field documentation in the description, nothing essential is missing. The description covers return shape, size implications, pagination, and onward navigation to related Pinterest tools.

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

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

Schema coverage is 100% and includes parameter descriptions, so the baseline is 3. The description adds real value by clarifying that trim=true cuts response size to 28 KB and changes the field set, and by explaining the cursor as a pagination mechanism. This goes beyond the schema's terse 'Cursor' definition.

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

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

The description states a specific verb and resource: 'Searches Pinterest for pins matching a keyword'. It clearly distinguishes return shape (pins plus cursor) and explicitly routes to sibling tools get_pinterest_board and get_pinterest_pin, so an agent can tell it apart without opening other 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 names the alternatives and the conditions that select them: 'board.url on each result feeds get_pinterest_board' and 'for one pin's engagement counts use get_pinterest_pin'. It also explains when to use the trim parameter and when to skip it, giving clear operational 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, covering safety. The description adds valuable behavioral context: the response has three shapes (post, comments, paging), the paging mechanism uses more.has_more and more.cursor, and it provides a size estimate (~21 KB for 19 comments). This goes beyond annotations by explaining the response structure and paging 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 detailed but well-structured: it opens with the primary purpose, then covers response content, paging, size, and routing. Every sentence adds information, and it avoids redundancy with the schema. The routing suggestion is placed at the end, which is acceptable since the main purpose is front-loaded.

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

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

Given the tool's complexity (three response shapes, paging variants), the description covers the essential aspects: what data is returned, how paging works, and how to use it alongside sibling tools. The output schema handles return-value details. It doesn't mention error cases or rate limits, but annotations already signal safety, and the description is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents url, trim, and cursor. The description enhances the cursor parameter by explaining its role in the paging mechanism and contrasting it with the 'after' and 'cursor' used in sibling tools. This adds meaningful semantic value beyond the schema's one-line description.

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

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

The description clearly states the tool returns a post and its discussion from a post URL, enumerates the exact fields (title, author, selftext, etc.) and distinguishes itself from sibling tools by explicitly naming get_reddit_search and get_reddit_subreddit as alternatives for finding posts. The verb 'Returns' plus the resource 'one post and its discussion' makes 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 explicitly routes users to start from get_reddit_search or get_reddit_subreddit to find posts, implying this tool is for fetching comments once a post URL is known. It also clarifies that the paging shape differs from these alternatives. While it doesn't explicitly state 'when not to use', the routing suggestion provides clear contextual 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 performance details (8-16 seconds, 8-26 KB) and pagination behavior via the after token, which is useful context beyond the structured annotations. 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?

The description is well-structured: purpose first, then return fields, then sort/timeframe, then performance, then alternatives. It is concise without redundancy, each sentence adds value, and it is front-loaded with the core action.

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

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

Given the tool's complexity (5 params, 2 enums, output schema exists), the description covers the essential aspects: what it does, key fields, sort options, pagination, performance, and when to use alternatives. It is comprehensive for an agent to decide whether and how 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 all five parameters are already documented. The description adds minimal extra semantics: it reiterates sort options and mentions the after token for pagination, but these are also in the schema. It does not introduce new parameter meaning beyond what the schema provides.

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

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

The description clearly states the tool searches every public subreddit for posts, returning posts and a pagination token. It explicitly distinguishes itself from get_reddit_subreddit_search (single community) and get_reddit_post_comments (post discussion), making the purpose unambiguous.

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

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

The description explicitly names alternatives and the conditions to choose them: 'To stay inside one community use get_reddit_subreddit_search...' and 'to read one post's discussion use get_reddit_post_comments.' It also notes performance characteristics (slowest endpoint) to inform usage decisions.

Agents often have multiple tools that could apply. Explicit usage 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 only say readOnlyHint=true and idempotentHint=true, which is safe but minimal. The description adds crucial behavior: paging via 'after' token, case-sensitivity of subreddit names, error handling for invalid timeframe/sort combos (400), and an approximate response size ('about 18 KB for 24 posts'). These go well beyond the structured 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 concise sentences, each earning its place: function, output fields, sort values + critical constraint, and alternatives. The most important constraint (timeframe with sort=top) is emphasized with 'Important:'. 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 5-parameter tool with only one required, the description covers the key operational details: paging, sort options, the error case, case-sensitivity, response size, and routing to sibling tools. Since an output schema exists, it correctly avoids restating return values. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100% with per-parameter descriptions, so baseline is 3. The description adds value by explaining the paging mechanism ('with an after token to page'), the error condition for timeframe (already in schema but reinforced), and the size estimate. It does not redundantly repeat each parameter's description but provides contextual meaning beyond the schema.

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

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

The description opens with a clear verb-resource pair: 'Returns the post stream of one subreddit with an after token to page.' It also distinguishes itself from sibling tools by explicitly naming get_reddit_subreddit_search and get_reddit_subreddit_details for alternative uses, and ties its output fields to get_reddit_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?

Explicitly states when to use alternatives: 'To search inside the same subreddit use get_reddit_subreddit_search, and for its metadata use get_reddit_subreddit_details.' Also gives a hard constraint: 'timeframe is only accepted together with sort=top, and any other combination returns 400 rather than ignoring the parameter.' 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 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?

The description discloses several behavioral traits beyond annotations: synchronous execution, the DataForSEO envelope structure (data in tasks[0].result, outcome in tasks[0].status_code), the fact that a rejected request still returns HTTP 200, and the measured payload sizes for different result depths. It also warns about the 'html' depth being 2.4 MB. The annotations only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=true, and the description adds substantial context about response size, cost, and error handling. 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 dense but well-structured: it starts with the core purpose, then lists return fields, then provides size measurements, then cost, then envelope details. Every sentence adds value, though the size and cost details are somewhat lengthy. It is front-loaded with the most important information and uses formatting (⚠️, 💰) to draw attention to caveats. Slightly over-long but justified by the 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 exists and the annotations provide some hints, the description is complete enough for an agent to call this tool correctly. It explains the response envelope, the synchronous behavior, the cost implications, and the result depth options. The only minor gap is that it doesn't explicitly list all parameters, but the schema already does that. For a complex tool with one body parameter, this is comprehensive.

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

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

Schema description coverage is 0%, so the description must compensate. The description does not explain individual parameters like language_code or location_code, but it does clarify the 'keyword' parameter by stating it returns ranked results for a keyword on YouTube. The description also mentions 'three result depths' which likely maps to a parameter not shown in the schema (maybe a 'depth' field), but the schema only shows one parameter 'body' with nested properties. Since the description adds context about the query and result structure but doesn't fully document each parameter, a 4 is appropriate rather than 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 opens with a specific verb and resource: 'Returns the ranked results for a keyword on YouTube, synchronously.' It then lists the exact fields returned, which distinguishes it from sibling tools like get_youtube_search and other search tools. The title 'Live YouTube Organic Advanced' is also clarified by the description's mention of result depths and the 'advanced' default.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 versus alternatives: 'advanced is the default choice; take regular when only the ranked list matters and html only to check what the parser dropped.' It also mentions the cost advantage relative to other search data sources, which helps an agent decide when this tool is appropriate. This is clear usage guidance with explicit alternatives and conditions.

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

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

Beyond the annotations, the description reveals critical behavior: the request body is passed through unchanged, responses include cited source URLs, billing is $0.001 per successful result with specific non-billing conditions, and latency expectations differ by source type. This is exactly the kind of operational detail agents need and it is consistent with readOnlyHint/idempotentHint.

Agents need to know what a tool does to the 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 dense sentences, each adding unique value: first defines the action and passthrough, second explains the response, third addresses billing, and the final covers latency and timeout. No wasted words and the most important constraints are front-loaded.

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

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

Given the complexity of the tool and the rich schema plus output schema, the description is complete: it covers endpoint, request behavior, response contents, billing semantics, latency expectations, and client timeout guidance, while the schema covers parameters and the output schema handles return format. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter and its source-specific behavior, including enum values. The description adds context that sources accept subsets of parameters and that the body passes through unchanged, but it does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource (Synchronous passthrough to the upstream Oxylabs Realtime endpoint (POST /v1/queries)) and states the functional outcome: tracking how a brand or product is surfaced and cited across AI answers. It also naturally distinguishes itself from sibling tools since none of the listed siblings target AI answer engines.

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

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

The description gives clear operational context: pick a source via `source`, pass through the parameters that source expects, and use a client timeout of at least 90s due to source-specific latency. It does not explicitly contrast this tool against alternative sibling tools, but no sibling offers overlapping functionality, so an explicit when-not is not necessary.

Agents often have multiple tools that could apply. Explicit usage 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, idempotent, and non-destructive hints. The description adds valuable behavioral details: the response structure, the null/empty email behavior as a normal result (not an error), the single-creator-per-call limit, and performance metrics (533 bytes, ~2 seconds). 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 thorough but organized: main purpose first, then return fields, edge case, performance, and finally usage guidance. Each sentence earns its place, though it could be trimmed slightly without losing value. It is front-loaded with the core purpose.

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

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

Given an output schema exists and only one parameter is present, the description covers everything needed: return shape, edge cases, performance expectations, and how it relates to a sibling tool. Nothing an agent needs to correctly invoke 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 coverage is 100%, so the parameter 'url' is already well-described as a TikTok/Instagram/YouTube profile URL. The description reinforces this and adds the constraint that it handles one creator per call, which clarifies the parameter's scope. This slightly exceeds the baseline.

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

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

The description opens with a specific verb ('Looks up') and resource ('contact emails for one TikTok, Instagram or YouTube creator from a profile URL'), and lists the full set of returned fields. It also distinguishes itself from the sibling post_waveinflu_similar_creators by stating that this endpoint handles Instagram creators and fills email gaps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: use post_waveinflu_similar_creators first to build a list, then call this endpoint for creators with null emails and for Instagram creators. It clearly states when not to use this tool, leaving 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?

Beyond annotations (read-only, idempotent, non-destructive), the description adds meaningful behavior: the response echoes the resolved mode (homepage, direction, homepage_direction), sets sourceUserId only when a seed resolves, and describes how field shape varies by platform (YouTube adds channelId/channelTitle, TikTok adds userId/uniqueId/nickname/averageLikeCount). It also includes response size and latency measurements. This goes well beyond the annotation hints.

Agents need to know what a tool does to the 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 first sentence gives purpose, the second iterates required inputs and constraints, the third explains mode resolution, the fourth lists match fields, the fifth covers platform-specific field differences, the sixth gives performance metrics, and the seventh provides an alternative tool. It is front-loaded with the core purpose and efficiently 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?

Considering the tool's complexity — nested filters, platform-specific output, multiple modes, and alternative tools — the description covers all critical aspects an agent needs: input constraints, output shape differences, performance expectations, and an explicit fallback. The presence of an output schema further supports that the description is complete enough; no knowing would lead to incorrect invocation.

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

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

Schema coverage is 80%, but the description adds relational semantics: it explains that seedProfileUrl and contentDirection can be used 'or both,' and that the response mode depends on which is provided. It also clarifies that filters apply to regions, languages, follower and average-view ranges. This adds meaning beyond individual parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Finds creators similar to a seed profile, a natural-language content direction, or both, on YouTube or TikTok.' This clearly distinguishes it from siblings, especially post_waveinflu_email_lookup, and notes it does not match Instagram creators. The title 'Similar Creators' alone would be vague, but the description fully disambiguates it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides usage conditions: platform is required, supply a seedProfileUrl or contentDirection or both, and states the limit range. It also gives a specific alternative: 'use post_waveinflu_email_lookup for the ones that come back null and for Instagram creators, which this endpoint does not match.' This covers when to use and when not to use, including a named sibling.

Agents often have multiple tools that could apply. Explicit usage 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.