AIsa Go-To-Market

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which annotations cannot convey.

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

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

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing 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 zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret 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 tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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

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

The description states a concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling 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?

Explicit triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

Agents often have multiple tools that could apply. Explicit usage 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, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below a 5.

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

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

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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

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

For a read-only batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded in the schema.

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

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

States a specific verb and resource ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative 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?

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this tool.

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

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

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly wasted.

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

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

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed to call it correctly.

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

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

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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

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

States a specific verb and resource ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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

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

Explicitly names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

Agents often have multiple tools that could apply. Explicit usage 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 mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

Agents need to know what a tool does to the 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 front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better 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?

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient 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 coverage is 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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

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

The description clearly states the verb and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little 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?

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds genuinely new behavioral context not in the annotations: error responses (4xx/5xx) are not charged, which matters for an agent deciding whether to retry or validate inputs before spending money.

Agents need to know what a tool does to the 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 functional sentence is front-loaded, concise, and information-dense. The appended pricing block is boilerplate rather than definitional content, which slightly dilutes the structure but does not bury the core 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?

With an output schema present and rich annotations, the description only needs to cover purpose and cost behavior, both of which it does. Missing only a word on which related domain tool to choose when the agent wants broader metrics.

Complex tools with many parameters or behaviors need more documentation. 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 date format and target example already documented in the schema, so baseline 3 applies. The description adds only the DR score range, which describes the return value rather than either parameter.

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

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

States a specific verb (Return) plus two named outputs (Domain Rating, Ahrefs Rank) and defines DR's 0-100 range, so the agent knows exactly what comes back. It does not distinguish itself from sibling tools like get_ahrefs_site_metrics or get_semrush_domain_overview, which is the only gap.

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

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

No guidance on when to prefer this over the adjacent Ahrefs/Semrush domain tools, and no prerequisites or alternative named. The only contextual statement is a billing note, which is not usage guidance.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description adds real value beyond that: the chaining contract that get_apollo_organizations_id consumes the id this call returns, plus billing context. The return-field enumeration is largely redundant with the output schema, keeping it from a 5.

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

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

Front-loaded with purpose, then alternatives, then chaining guidance. Slightly padded by the long list of return fields that the output schema already defines, plus an injected pricing block, but overall tight and well-ordered.

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

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

Covers what it does, when to use it, its two alternatives, and the id hand-off to the detail sibling. With an output schema present, return values need not be documented, and 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 coverage is 100%, so the baseline is 3. The description reinforces the single-parameter contract and adds a caveat beyond the schema ('must be the bare domain (apple.com), not a full URL'), which sharpens the format requirement rather than merely restating it.

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

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

States a specific verb and resource ('Enrich one company by domain'), and explicitly names the siblings it is not (post_apollo_organizations_bulk_enrich, get_apollo_organizations_id). An agent can select it without opening any schema.

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

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

Gives explicit routing: 'Use it as the entry point when all you have is a domain,' bulk for 'several domains at once,' and get_apollo_organizations_id for 'the full record including funding and technology detail.' Conditions for choosing alternatives are all spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the data-source disclosure: it reads Apollo's job board, not the company's careers page, so absence of postings is not proof the company isn't hiring. That is a genuinely useful caveat beyond the annotations, though return format and pagination behavior are left to the output schema.

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

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

Front-loaded with the core purpose, followed by payload contents, the sourcing prerequisite, and the honesty caveat in a compact block. The appended pricing blockquote is boilerplate rather than tool guidance, but it is clearly demarcated and does not obscure the useful text.

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

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

With an output schema present, the description need not explain return values, and it covers purpose, id source, and the interpretive limitation well. Remaining gaps are minor, e.g. no note on pagination limits or how many postings to expect.

Complex tools with many parameters or behaviors need more documentation. 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 page, per_page and organization_id are already documented in the schema; baseline is 3. The description adds a hint about where to source organization_id, though it points at get_apollo_organizations_enrich while the schema's own organization_id description says to use the Organization Search endpoint, a minor inconsistency rather than added clarity.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Live job postings for one company, by Apollo organization id') and enumerates what each posting carries (title, location, posted date, source URL). An agent can distinguish this from sibling organization tools like get_apollo_organizations_id and get_apollo_organizations_enrich without opening a schema.

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

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

Gives an explicit prerequisite ('Get the organization id from get_apollo_organizations_enrich first') and frames the use case as a hiring signal. It does not enumerate when-not-to-use or name a competing sibling, but the workflow context is clear.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive, yet the description adds non-obvious behavior: results are Google-indexed rather than direct Instagram data, the cursor is a Google results page number rather than an Instagram cursor, and payload size is about 78 KB for ten posts. The cursor quirk in particular is exactly the kind of detail that prevents misuse.

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

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

Purpose, return shape, enum behavior, the cursor caveat and the alternative are all front-loaded with no filler. It is densely packed into a single block rather than cleanly segmented, and the injected pricing block adds bulk, but every sentence of the authored text 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, full annotation coverage and 100% schema description coverage, the description already goes further by naming the normalized return fields and the size/cursor behavior. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents hashtag, cursor, media_type and date_posted; the description mostly restates them (optional '#', all vs reels). It adds little parameter meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Finds public posts carrying a hashtag through Google') plus the exact scope of coverage. It names the sibling it is not (get_instagram_reels_search) and explains the shared normalized shape, so an agent can distinguish it without opening the schema.

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

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

Gives clear routing guidance: media_type=reels vs all, and an explicit alternative ('To search caption keywords rather than a hashtag, use get_instagram_reels_search'). It stops short of stating exclusions or prerequisites (e.g., hashtag is not required), so it is strong context rather than a full when/when-not matrix.

Agents often have multiple tools that could apply. Explicit usage 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, openWorld, non-destructive), yet the description still adds meaningful traits: the source is Google (open-world scraping, not the Instagram API), the measured payload/latency (~18 KB, ~13 s), and the matched_from field that explains why a profile appeared. Rate limits and failure behavior are not covered, which keeps it short of a 5.

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

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

Purpose and routing are front-loaded and the performance metrics are compact, but the long enumeration of return fields is largely redundant with the existing output schema and consumes most of the description's length. It could be trimmed to keep only the fields that inform selection.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the source of the data, cost/latency expectation, sibling routing, and the chaining target for the returned id. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description adds no syntax or format detail beyond restating 'keyword or bio phrase'. The cursor/pagination parameter is not addressed at all. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Searches Google for public Instagram profiles matching a keyword or bio phrase') and enumerates the returned identity fields, so the agent knows exactly what it gets back. It also distinguishes itself from siblings by naming the post-search alternatives, so an agent can pick correctly without opening a schema.

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

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

Gives an explicit exclusion ('To search posts rather than people, use get_instagram_search_hashtag or get_instagram_reels_search') and a downstream chaining rule ('The numeric id feeds get_instagram_basic_profile directly'). Both when-to-use and when-not-to-use are stated rather than inferred.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered elsewhere. The description adds substantial behavioral context beyond that: pagination via cursor, concrete payload sizes (104 KB for 16 pins; 28 KB trimmed) and the exact field subsets returned. It stops short of stating rate limits or error behavior, so a 4 rather than 5.

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

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

Front-loaded with the core action and paging behavior, and every sentence carries information. The two inline field enumerations ('node_id, link, domain...' and the trim field list) are dense and slightly bloat the text, and the injected pricing boilerplate sits outside the definition's control.

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

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

An output schema already exists, so return values need no further explanation, and annotations cover the read-only/idempotent profile. Between the URL-source guidance, paging semantics and field-set/size notes, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: url must be absolute, with relative board paths needing an https://www.pinterest.com prefix, and trim=true is quantified as cutting 104 KB to 28 KB while enumerating the retained fields. This goes well beyond the schema's one-line parameter docs.

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

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

States a specific verb and resource — 'returns one page of pins from a board URL' — and immediately differentiates from siblings by noting it also emits a paging cursor and that board pins use a distinct field subset from search results and pin detail. An agent can distinguish it from get_pinterest_search and get_pinterest_user_boards without opening schemas.

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

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

Explicitly routes the agent: 'For a user's board list rather than one board's pins, use get_pinterest_user_boards,' and explains where valid URLs originate (board.url on search results, or get_pinterest_user_boards). Both when-to-use and the alternative are named.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), so the description is not obligated to restate that. It adds genuinely useful behavioral facts instead: measured payload size (~110 KB for 17 pins), the trimmed 28 KB size, and exactly which six fields survive trim. It stops short of documenting rate limits or cursor expiry.

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

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

Front-loaded with purpose, then return shape, then the size/trim tradeoff, then routing — a sensible priority order with no padding in the sentences themselves. The embedded pricing comment block is boilerplate noise that dilutes an otherwise tight entry.

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

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

An output schema exists, so the exhaustive per-pin field listing (images in five sizes, board, pinner sub-fields) is partly redundant with what the schema already exposes. The non-redundant parts — payload size, trim economics, and cross-tool field handoffs — are exactly what the agent needs before calling, making the description sufficient overall.

Complex tools with many parameters or behaviors need more documentation. 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 75% and the schema barely describes trim ("trimmed down version") and not at all limit. The description compensates by quantifying the trim tradeoff and enumerating the dropped fields (title, link, board, domain), which is meaning the schema does not carry. limit and cursor remain unelaborated.

Input schemas describe structure but not intent. Descriptions should explain 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 (searches Pinterest for pins by keyword) plus the return shape (pins plus a pagination cursor). It also explicitly distinguishes itself from the two closest siblings, get_pinterest_board and get_pinterest_pin, and from other platform search tools in the list.

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

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

Gives a concrete when-to-use rule for trim ("only skip trim when you need those") and routes follow-up work to get_pinterest_board and get_pinterest_pin with the exact field that feeds each. It does not, however, state when a caller should prefer this over other search tools (e.g., get_reddit_search), so the routing is sibling-aware but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new behavioral detail: the paging shape differs from both sibling search tools (more.has_more/more.cursor vs after vs cursor), and the payload cost is quantified ('about 21 KB for 19 top-level comments'). That size estimate and paging divergence are exactly the traits an agent cannot get from structured fields.

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

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

The core content is a single run-on sentence that enumerates every post and comment field even though an output schema already exists, which is redundant rather than informative. Routing guidance that an agent most needs is buried at the end, and the appended pricing boilerplate further dilutes it.

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

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

Because an output schema exists, the field enumeration is unnecessary and the description would be complete without it; what remains (routing from search tools, paging semantics, response size) is the information an agent genuinely needs. It is slightly over-complete rather than under-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 75%, so the baseline is already near 3. The description clarifies what cursor does ('more comments, or replies') and implies the url input, but it never explains trim or accounts for the undocumented 'trimmed' string parameter, so it adds only marginal 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?

Opens with a specific verb and resource: 'Returns one post and its discussion from a post URL.' It also explicitly differentiates itself from the search siblings by positioning them as the discovery step, so an agent can distinguish this tool from get_reddit_search and get_reddit_subreddit without opening any schema.

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

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

Gives a clear entry condition: 'To find posts worth opening, start from get_reddit_search or get_reddit_subreddit,' and describes the cursor path for continued paging. It stops short of stating any when-not-to-use case, so it is clear context rather than a full routing 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 declare readOnly/openWorld/idempotent/destructive=false, so safety is covered. The description adds substantial non-annotation behavior: latency (8-16s, slowest endpoint), payload size (8-26 KB), pagination via an after token, and the full returned field list. It stops short of documenting rate limits or failure behavior, but adds real context beyond the annotations.

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

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

Front-loaded with the core action, then alternatives, then performance. The 19-field enumeration is verbose but informative for a search result. The pricing block is boilerplate appended by the platform rather than the author's prose, so it doesn't count against 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?

An output schema exists, so the field list is somewhat redundant, yet the description still supplies pagination, performance expectations, sorting semantics and routing to siblings. It omits auth/prerequisite notes and does not flag that 'query' is practically required despite required=[], a minor gap for a 10-param tool.

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

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

Schema coverage is 60%, so the description must compensate for some gaps. It meaningfully enriches 'sort' (relevance, new, top, comment_count) and 'timeframe' (narrows the window) and explains 'after' for paging, but leaves limit, count, trim/trimmed, filter and query semantics to the schema. Adequate but partial.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Searches every public subreddit for posts matching a query') with scope ('every public subreddit') and names what it returns. It explicitly distinguishes itself from get_reddit_subreddit_search and get_reddit_post_comments, so an agent can tell them 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?

Names two alternatives with the exact conditions that select them: use get_reddit_subreddit_search 'to stay inside one community' and get_reddit_post_comments 'to read one post's discussion'. This is explicit when-to-use-each guidance rather than implied 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 establish the read-only, idempotent, non-destructive profile, so the description is free to add runtime behavior instead. It does: the timeframe/sort=top 400 error (rather than silent ignoring), case-sensitive subreddit names, pagination via the after token, and a concrete ~18 KB / 24 posts size figure. Auth and rate-limit behavior are still unstated, so it falls short of a 5.

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

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

Front-loaded with the core purpose and scope, then constraints, then routing. Every sentence carries information, including the size estimate and error edge case. The appended pricing boilerplate adds length without helping tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 6-param, unpaginated-boundary tool with an output schema, this covers purpose, constraints, paging, alternatives and approximate payload size. Minor gaps remain: the trim payload reduction and cache_max_age are not clarified in narrative form. Nothing an agent needs to call it successfully 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 83%, so the schema already documents sort, timeframe, after and trim; the description largely restates the sort enum and the timeframe constraint. It adds the genuinely useful case-sensitivity note for subreddit, but leaves cache_max_age and the semantics of trim (what gets removed) unexplained. Baseline 3 is appropriate when the schema carries most of the load.

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

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

States a specific verb+resource and scope: the post stream of one subreddit. It explicitly distinguishes itself from the three nearest siblings (get_reddit_search, get_reddit_subreddit_search, get_reddit_subreddit_details), so an agent can route correctly without opening any schema.

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

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

Names the alternatives and the exact conditions that select them: use get_reddit_subreddit_search to search inside the same subreddit, get_reddit_subreddit_details for its metadata. It also states the sort=top pairing rule for timeframe, giving explicit when-to-use behavior rather than leaving it to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The only real contribution is the pricing disclosure ($0.004 per successful request), which is genuinely useful cost context, but the description says nothing about what the call does, what it returns, or any limits.

Agents need to know what a tool does to the 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 text is short and cleanly formatted, but it is entirely off-topic relative to the tool's function; every sentence is about pricing rather than the operation. Brevity here reflects missing content, not efficient writing.

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

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

An output schema exists, so return-value explanation is not required, yet the description omits purpose, usage context, and parameter meaning for a live external-API tool. It is not remotely complete for an agent to select and invoke it.

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

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

Schema coverage is 0% and the single required parameter 'target' has no description anywhere. The description does not clarify whether 'target' is a domain, URL, or path — the one piece of information that would most help an agent invoke this correctly.

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

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

The description contains no functional statement at all — it is purely a pricing notice. Nothing tells the agent that this tool returns a Semrush backlinks overview for a target, nor how it differs from siblings like get_semrush_backlinks or get_semrush_referring_domains.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no prerequisite information, and no reference to any alternative among the many sibling backlink tools. The agent has to infer applicability from the tool 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description does add one genuine behavioral fact not in the annotations – a per-request price of $0.001 USD – which is useful cost context, but it discloses nothing about auth requirements, rate limits, or response 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?

It is short, but the content is boilerplate HTML-comment pricing markup that does not help an agent select or invoke the tool. Length is minimal while relevance is near zero, so it is under-specified rather than concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 domain-overview tool with a required 'domain' parameter and an undocumented 'database' parameter, the description leaves the agent without the essential information needed to call it correctly. The presence of an output schema excuses explaining return values, but nothing else compensates for the missing purpose and parameter detail.

Complex tools with many parameters or behaviors need more documentation. 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% for two parameters ('domain' and 'database'), and the description supplies no meaning, format, or defaults for either. It does not compensate for the schema gap at all, and notably omits that 'database' defaults to 'us'.

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

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

The description never states what the tool does; it contains only a pricing notice wrapped in HTML comments. An agent must infer the purpose entirely from the tool name 'get_semrush_domain_overview'. It provides no verb+resource statement and no differentiation from siblings like get_semrush_domain_organic_keywords or get_semrush_domain_vs_domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no exclusions, and no mention of alternatives among the many semrush/ahrefs/dataforseo siblings. The text is solely about cost, not about selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and open-world behavior, so the safety profile is covered. The only added behavior is the per-request price ($0.001 USD per successful request), which is genuinely useful cost context beyond the annotations, but it is the sole non-template content.

Agents need to know what a tool does to the 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 blurb is short but consists entirely of an HTML-comment pricing artifact that does not earn its place for tool selection. It is not front-loaded with any purpose 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?

Although an output schema and annotations exist, the description supplies zero information on what the tool returns or when to call it. For a keyword-lookup tool surrounded by dozens of similar siblings, this is completely inadequate for correct selection.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate and instead says nothing about the required 'phrase' or the 'database' default. There is no hint about accepted phrase format or database values such as 'us'.

Input schemas describe structure but not intent. Descriptions should explain 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 contains only a pricing banner and never states what the tool does. Nothing indicates it returns Semrush keyword overview metrics for a phrase, nor distinguishes it from siblings like get_semrush_keyword_difficulty or post_dataforseo_labs_google_keyword_overview_live.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no mention of alternatives, and no conditions for selecting this tool over the many keyword-data siblings. The agent is left to infer everything from the tool name.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The one genuine addition is cost disclosure (predicted ~$0.08 per request, usage-based, not fixed), which is real behavioral context an agent cannot get from annotations. However, the description says nothing about what the call returns, rate limits, or data freshness.

Agents need to know what a tool does to the 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 text is short, so length is not the problem; the problem is that every line is HTML-commented billing boilerplate rather than front-loaded tool purpose. Legitimate conciseness here would be a single sentence stating what the tool returns.

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

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

Even granting that an output schema exists and return values need not be explained, the definition omits purpose, usage context, and the meaning of both required parameters. An agent cannot call this correctly from the description alone.

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

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

Schema description coverage is 0% and both parameters (domain, database) are required yet completely undocumented in the schema. The description does not mention either parameter or its expected format, so it fails to compensate for the coverage 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 never states what the tool does — it contains only a pricing/billing banner with no verb, resource, or scope. The title 'Organic Competitors' is the only hint, and the tool must be distinguished from many siblings like get_semrush_domain_overview and post_dataforseo_labs_google_serp_competitors_live with no help from the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use, when-not-to-use, or alternative-tool guidance at all. Given a large set of competing Semrush/DataForSEO competitor tools, an agent gets zero routing signal from this description.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description's only added behavioral content is cost disclosure ($0.075 per similarweb_credit, estimate not fixed), which is genuinely useful but says nothing about what the operation returns or how it behaves.

Agents need to know what a tool does to the 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 text is short, but it is entirely boilerplate pricing wrapped in HTML comment markers rather than a front-loaded purpose statement. Being brief here reflects omission of the essential content, not disciplined conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 4 required params and 10% schema coverage, the description is completely inadequate. Although an output schema exists (relieving the need to explain return values), nothing else an agent needs to call this correctly is provided.

Complex tools with many parameters or behaviors need more documentation. 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 only 10% across 10 parameters, so the schema leaves most parameters (domain, start_date, end_date, limit, offset, web_source, granularity, traffic_source, main_domain_only) undocumented. The description compensates for none of this, adding zero parameter meaning.

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

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

The description never states what the tool does. It contains only a pricing boilerplate block ('Usage-based billing; Default request estimate: $0.075 USD...') with no verb, resource, or scope describing keyword competitor retrieval. An agent must rely entirely on the tool name to infer purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 siblings such as get_similarweb_keywords or get_similarweb_similar_sites. No context, prerequisites, or exclusions are offered anywhere in the text.

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

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

Annotations already cover the operational profile (readOnly, idempotent, openWorld, non-destructive). The description's only additive behavioral content is the billing model — usage-based, ~$0.075 per similarweb_credit — which is genuinely useful cost context. However, it discloses nothing about data freshness, result size, or what the returned keyword records contain.

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

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

It is short, but the brevity is under-specification rather than efficiency: the entire body is boilerplate pricing with zero functional content. The one useful sentence (per-credit rate) is buried in a compliance block rather than front-loaded as tool guidance.

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

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

An output schema exists, so return values need not be described, but for a 9-parameter, 5-required tool with 11% schema coverage and a crowded sibling namespace, the description supplies no purpose, no usage routing, and no parameter semantics — it is functionally empty.

Complex tools with many parameters or behaviors need more documentation. 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 11% (only 'country' is documented), and there are 9 parameters including five required ones (domain, start_date, end_date, granularity, limit). The description explains none of them — no date format, no domain input convention, no meaning for granularity or web_source — leaving the agent to guess.

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

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

The description contains no statement of what the tool does — it is entirely a pricing/billing notice. An agent must infer from the name and title alone that this retrieves SimilarWeb keyword data, and it cannot distinguish this from the many get_semrush_* and get_dataforseo_keywords_* siblings.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. The pricing block states cost but not the conditions under which this tool should be chosen over the adjacent get_similarweb_landing_pages or the Semrush/DataForSEO keyword 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description does add one genuinely useful behavioral fact not present in structured data: this call is billed (default estimate $0.15 USD, unit rate $0.075 per credit, account-specific pricing may differ). That cost disclosure is analogous to a rate-limit note and is worth credit, but nothing else about behavior is described.

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

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

It is short, but the entire content is auto-generated billing boilerplate wrapped in HTML comment tags, which is off-topic for tool selection and invocation. Length is fine; the content does not earn 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 7-parameter tool with three required inputs, 14% schema coverage and a large sibling set, this description is functionally empty. An output schema exists so return values need not be described, but the agent has no basis for choosing or parameterising the call.

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

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

Schema description coverage is only 14% — just the 'country' parameter — while there are 7 parameters including required domain, start_date and end_date. The description supplies no parameter meaning at all, so the many undocumented fields (data format for dates, web_source, granularity, main_domain_only) get no compensation.

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

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

The description never states what the tool does. It contains only a usage-based pricing block (default estimate $0.15, $0.075 per similarweb_credit) with HTML comment markers. Nothing tells the agent that this returns website ranking data, for which domain, or over what period, so it cannot be distinguished from siblings like get_similarweb_top_sites_ranking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 zero guidance on when to call this versus the 30+ sibling tools (e.g. get_similarweb_top_sites_ranking, get_similarweb_website_traffic_trend, the website_analysis variants). No prerequisites, no exclusions, no alternative named.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint and destructiveHint=false, so the safety profile is covered elsewhere. The one piece of added context is billing information (mentioned pricing, per-credit rate, account-specific settlement), which is genuinely useful for a paid external API and is not in the annotations. However, it says nothing about rate limits, latency, data freshness, or failure modes.

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

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

The text is short and formally well-delimited by HTML comment markers, so it is not bloated. But it is entirely boilerplate that does not serve the tool-selection task; 'conciseness' by omission of all substance is under-specification, not efficiency.

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

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

Given 10 parameters, 4 of them required, near-zero schema coverage, and a crowded sibling namespace, the description is wholly inadequate. It offers no domain identification, no date-range semantics, no limit/offset behavior, and no indication of what the output contains — an agent cannot call this correctly on the basis of the description.

Complex tools with many parameters or behaviors need more documentation. 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 10% (only 'country' is documented, and that is inside the schema, not the description). With 10 parameters — including non-obvious ones like main_domain_only, traffic_source, web_source, and required date-range bounds — the description supplies zero additional meaning, format hints (e.g. date format for start_date/end_date), or defaults.

Input schemas describe structure but not intent. Descriptions should explain 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 contains no statement of purpose at all — it consists entirely of a pricing block ('Usage-based billing; Default request estimate: $0.375 USD...'). Nothing tells the agent what the tool returns, only that it returns similar sites if you infer that from the tool name. For a 10-parameter analytical tool this is a complete failure to identify verb+resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the many siblings (get_similarweb_ranking, get_similarweb_audience_overlap, get_similarweb_subdomains, etc.). The only 'condition' offered is cost per credit, which does not help the agent decide whether this is the right tool for a task.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=true and destructiveHint=false, so safety semantics are covered. The description does add genuinely useful non-annotation context: usage-based billing with a $0.075 USD per-request estimate and a similarweb_credit unit rate. However it says nothing about rate limits, auth, or what data is returned.

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

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

The text is short, but every word is billing boilerplate that does not help an agent select or invoke the tool. Conciseness without relevance is under-specification, not efficiency.

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

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

For a 9-parameter tool with only 11% schema coverage, an output schema, and a dense sibling set, the description omits purpose, usage, and all parameter semantics. Even granting that the output schema removes the need to explain return values, the definition is unusable 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 11% across 9 parameters (4 required: domain, start_date, end_date, metrics), and the description contributes no parameter meaning at all — no mention of domains, date ranges, metric names, or the enum-constrained country/web_source/granularity values. This is the worst case for a high-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain 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 contains only an auto-generated pricing notice and never states what the tool does. Neither the verb nor the resource is defined beyond what the tool name and title ('Traffic & Engagement') imply, and no sibling is distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no prerequisites, and no mention of alternatives among the ~30 SimilarWeb siblings (e.g., website_traffic_snapshot, traffic_trend, marketing_channel_sources_legacy). An agent gets zero routing information.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add genuinely non-obvious cost context (estimated $2.25 per request, $0.075 per similarweb_credit, account-specific settlement), which an agent weighing whether to call a metered tool would value, but it says nothing about the operation's actual 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 text is short, but every line is pricing boilerplate wrapped in HTML comment markers, so the limited space is spent on something other than tool selection. It is front-loaded with billing rather than 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?

Output schema exists, so return values needn't be explained, but the description never says what "top geographies" means (country-level traffic distribution for a domain/month), leaving the core capability entirely undocumented for an agent scanning a large sibling list.

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

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

Schema coverage is 100% and both parameters are self-documenting: domain is specified as a bare hostname and month as YYYY-MM with a previous-complete-UTC-month default policy. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

The description contains no statement of what the tool does. It is entirely a pricing/billing banner ("Usage-based billing; Default request estimate: $2.25 USD...") with no verb, resource, or scope tied to retrieving top geographies for a website.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the many sibling geographies/audience tools (get_similarweb_traffic_engagement, get_similarweb_demographics, etc.). No prerequisites, no exclusions, no alternative named.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description does add genuinely non-annotation behavior: usage-based billing with a stated unit rate and a default cost estimate, which is useful for cost-aware agents. It still omits any disclosure of response shape, latency, or credit consumption per call beyond the estimate.

Agents need to know what a tool does to the 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 text is short and front-loaded, but every sentence is pricing metadata rather than tool guidance, so the brevity reflects missing content rather than disciplined concision. Nothing is wasted, but nothing about the operation is conveyed either.

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

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

An output schema exists so return values need not be explained, and annotations cover safety, but the description supplies no functional framing at all for a tool that competes with a dozen overlapping similarweb traffic tools. An agent cannot tell what a 'traffic snapshot' includes (visits, pageviews, bounce rate, duration) versus its 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%, and the schema documents domain, month (YYYY-MM, defaulting to previous complete UTC month) and country (worldwide only). The description adds no parameter meaning whatsoever, so the baseline 3 applies.

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

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

The description contains only pricing boilerplate (usage-based billing, $0.3 estimate, $0.075 per credit) and says nothing about what the tool retrieves or returns. Only the tool name and title hint at 'website traffic snapshot', which is not sufficient to distinguish it from siblings like get_similarweb_traffic_engagement or get_similarweb_website_traffic_trend.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. With 30+ similarweb siblings, the absence of any routing guidance leaves the agent unable to choose this tool over the many adjacent traffic metrics 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?

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description does add genuinely useful behavior beyond annotations: usage-based billing, a $0.45 default request estimate, and a $0.075 per similarweb_credit unit rate, which an agent should weigh before calling. However it discloses nothing about latency, time-window semantics, or result shape, so it is only partial.

Agents need to know what a tool does to the 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 text is short and contains no padding, but every sentence is pricing boilerplate wrapped in HTML comment markers rather than task description. It is concise in size yet misdirected in content, and there is no front-loaded statement of purpose to anchor the rest.

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

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

An output schema exists, so return values need not be explained, but the description still omits the trend/time-series semantics, default date behavior, and differentiation from the snapshot and traffic-engagement siblings. For a 5-parameter tool with three closely named siblings, this leaves the agent without the information needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents domain format, the country enum, the four-item metrics list, and the YYYY-MM date semantics; baseline 3 applies. The description adds no parameter meaning whatsoever 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 contains no statement of what the tool does; it is entirely a pricing banner. Only the tool name hints at retrieving a website traffic trend, and the description does nothing to confirm scope, distinguish trend from snapshot, or identify the resource beyond what the name already says.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no exclusions, and no reference to alternatives such as get_similarweb_website_traffic_snapshot or get_similarweb_traffic_engagement, which are the most likely competing tools. An agent has no basis for choosing this tool over those 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 readOnly/idempotent/non-destructive/openWorld, so the safety bar is pre-covered. The description adds useful context the annotations don't: the returned payload ('trend names and volumes under `trends`') and an account-specific pricing/usage note. It omits rate limits or freshness guarantees, but the additions are genuine.

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

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

Purpose is front-loaded and the two core sentences are dense with no waste. The injected pricing block adds length that isn't part of the tool's intrinsic description, slightly diluting the otherwise tight structure.

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

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

With a rich output schema and full annotation coverage, the description supplies what the agent still needs: the location semantics, the returned field group, and the downstream search tool. It leaves only minor gaps like pagination/freshness, which the output schema may cover.

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

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

Schema coverage is 100%, so both params are already documented; the description largely restates WOEID and the default `count` of 30 rather than adding syntax or format meaning. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Get the trending topics for a location') and pins the identifier (Yahoo WOEID), distinguishing it from the sibling tweet/user tools without ambiguity. It also names the natural next step tool, making its role in the workflow 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?

It gives a clear scenario ('real-time read on what a specific market is talking about right now', 'timing content or spotting emerging stories') and routes the follow-up to `get_twitter_tweet_advanced_search`. However, it never states when NOT to use it or how it relates to other trend-adjacent siblings, so it stops short of full explicit 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the lower bar applies. The description still adds real behavior: cursor pagination semantics, the has_next_page/next_cursor return fields, sort modes, and supported query operators. It omits auth requirements and rate limits, which keeps it from a 5.

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

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

Front-loaded with purpose, then operators, pagination, and alternatives in a tight sequence where each sentence carries information. The injected pricing boilerplate is not authored content but does add noise.

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

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

An output schema exists so return values need not be exhaustively explained, and annotations carry the safety profile. The description still covers usage context, alternatives, pagination flow, and query syntax, 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?

Schema coverage is 50%, so the schema does part of the work. The description usefully explains the query-string operator syntax and the Latest/Top sort (mapping to queryType), but count, max_results, and start_time are undocumented in both places. It adds value over the schema without fully compensating for the coverage 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?

States a specific verb (search) and resource (X posts) and immediately differentiates itself by naming the two sibling alternatives for account search and user timelines. An agent can distinguish this from any account-scoped tool without opening a schema.

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

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

Explicitly declares when to use it ('primary entry point for X content research when you do not yet have tweet IDs or handles') and routes to the correct alternatives ('to search accounts use get_twitter_user_search', 'to read one account's posts use get_twitter_user_tweet_timeline'). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral value beyond that: pagination behavior, the ordering limitation of the v1 endpoint, and the shape of returned objects. It stops short of describing rate limits or response envelope details, but is solid given annotation coverage.

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

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

The core definition is three tight, front-loaded sentences that each carry routing or behavioral information. The appended pricing boilerplate is machine-generated and not part of the semantic definition, slightly diluting conciseness but not the author's fault.

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

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

An output schema exists, so return-value structure need not be spelled out, and annotations carry the safety profile. Combined with the sibling routing and pagination notes, an agent has everything needed to invoke this correctly. Complete for a read-only list endpoint.

Complex tools with many parameters or behaviors need more documentation. 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 cursor, tweetId, and the queryType enum with its default. The description reinforces the cursor pagination and default-order behavior but adds no syntax or format detail beyond the schema. Note a mild tension: the schema exposes an ordering enum while the description says this v1 endpoint returns default order only.

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

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

States a specific verb and resource ('Get the direct replies to a tweet') and immediately scopes the shape of the result (cursor-paginated, full tweet objects). It explicitly distinguishes itself from two named siblings, get_twitter_tweet_replies_v2 and get_twitter_tweet_thread_context, so an agent can route correctly 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?

Gives explicit use context ('read the discussion under a post — sentiment, corrections, or follow-up questions') plus two exclusion routes: use v2 for ordering control, use thread_context to walk upward to the root. This is a full when/when-not/alternatives treatment.

Agents often have multiple tools that could apply. Explicit usage 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, openWorld, non-destructive), yet the description adds real behavioral context: 200 results per page by default, has_next_page/next_cursor pagination, and the shape of each entry. It stops short of stating rate limits or cursor lifetime, but the added pagination and page-payload detail is well beyond what the annotations provide.

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

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

Front-loaded with the core action, then pagination, then use cases, then sibling routing — a logical order with no redundant sentences. The injected aisa-pricing boilerplate adds length that does not serve tool selection, which keeps it out of the top band.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema existing, the description goes further by summarizing the per-entry fields, and it covers pagination, the identifier format, use cases, and both alternatives. Given a three-parameter read-only tool with full annotation coverage, an agent has everything needed to call it correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns a step up by clarifying that the user is addressed by @handle rather than the schema's vaguer "screen name," and by restating the 200-per-page default in prose. It does not add cursor format or sizing rules beyond the schema.

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

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

States a specific verb (list), resource (accounts that follow a given X user), the identity key (@handle), and the ordering (newest follower first). It also names the two closest siblings and how they differ, so an agent can pick it apart from get_twitter_user_followings and get_twitter_user_verified_followers without opening a schema.

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

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

Explicitly gives when-to-use scenarios (audience analysis, mapping a competitor's follower base, finding influential followers) and names both alternatives with their selecting conditions — reverse direction for followings, verified subset for verified followers. It even flags that the verified sibling takes a numeric user_id rather than a handle, which is exactly the kind of routing detail that prevents a wrong 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 declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds the meaningful scoping detail that this is a public-profile lookup keyed by handle, plus the returned field set; it does not mention auth or rate limits, which keeps it short of a 5.

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

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

Purpose is front-loaded and each subsequent sentence earns its place by routing to a distinct sibling. The injected pricing block adds length that is not part of the tool's semantic content, keeping it from a 5.

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

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

An output schema exists so return-value explanation is optional, annotations carry the safety profile, and the single parameter is fully documented. An agent has everything needed to select and call this tool correctly, with sibling disambiguation included.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already documents it (baseline 3). The description adds value by specifying the format is the @handle/screen name and by routing numeric-ID callers to a different tool, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain 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) with the exact input form (@handle). It is immediately distinguishable from the profile-adjacent siblings it names, so an agent can route without opening any schema.

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

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

Gives an explicit when-to-use framing (to assess identity, reach, or credibility before trusting content) and then names three concrete alternatives with the condition that selects each: numeric ID → get_twitter_user_batch_info_by_ids, extended metadata → get_twitter_user_about, posts → get_twitter_user_tweet_timeline.

Agents often have multiple tools that could apply. Explicit usage 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, so the bar is lower; the description still adds real behavioral context — cursor pagination and the response shape (data, has_next_page, next_cursor). It does not discuss rate limits or the billing estimate's non-fixed nature beyond the injected pricing note.

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

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

Front-loaded with the core action, then pagination, return shape, and the alternative — each sentence earns its place. The auto-injected pricing block adds length but is boilerplate rather than authored text.

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

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

With an output schema present, return values need not be described, yet the description still summarizes them; annotations carry the safety profile; and parameters, pagination, and alternatives are all addressed. An agent can call this correctly without further inference.

Complex tools with many parameters or behaviors need more documentation. 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%, so the baseline is a 3, and the description adds genuine meaning: that userName is a @handle, that userId and userName are interchangeable entry points (useful before handle resolution), and that replies are optional. Only 'count' remains undocumented in both places.

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

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

Specific verb+resource: retrieves a user's most recent tweets, with the scope (recent, cursor-paginated, optional replies) stated up front. It attempts differentiation by naming an alternative timeline tool, but that tool does not appear in the sibling list, so the contrast lands weakly against the actual siblings (get_twitter_user_mentions, get_twitter_tweet_replies, etc.).

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

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

Gives a clear usage condition: use this when you have not resolved the handle to an ID (accepts either userName or userId). It also names an explicit alternative and the condition selecting it. The referenced alternative is not present among siblings, which slightly undercuts the routing value.

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

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

Annotations already cover readOnly/idempotent/non-destructive/open-world, so the burden is lower. The description still adds real behavioral context: page size (20 per page) and the unique time-window capability. The return-format note (has_next_page/next_cursor) is redundant against the output schema, so it isn't a full 5.

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

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

Front-loads purpose then usage then return shape in a sensible order, with no filler sentences. The trailing auto-injected pricing comment is noise but boilerplate; the return-value sentence is mildly redundant given the output schema.

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

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

For a read-only, paginated list endpoint with a full output schema and safety annotations, the description covers purpose, when-to-use, the time-window mechanics, and pagination size. An agent has everything needed to call it correctly.

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

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

Schema coverage is only 50% — sinceTime and untilTime have no schema description. The description compensates by telling the agent these are Unix timestamps in seconds and that they bound the range, which is exactly the missing semantic detail. cursor and userName are already schema-documented, so it doesn't need to repeat them.

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

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

States a specific verb and resource ('Get tweets that mention a given @handle') and immediately differentiates itself from the sibling for own-posts content. An agent can tell it apart from get_twitter_user_last_tweets without reading either schema.

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

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

Gives explicit use cases (monitoring, brand mentions, inbound replies, reputation tracking, 'last 24 hours') and names the alternative ('For the account's own posts... use get_twitter_user_tweet_timeline'). It also declares a differentiating constraint — the only user-scoped X endpoint with a time window — which routes the agent decisively.

Agents often have multiple tools that could apply. Explicit usage 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, open-world and non-destructive, so the safety profile is covered structurally. The description adds value beyond them by disclosing pagination behavior ('cursor-paginated'), the top-level return key ('full user objects under `users`'), and the scope boundary (accounts, not posts). It omits rate limits or auth requirements, hence not a 5.

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

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

Front-loaded with the core action, then the selection heuristic, then the pagination/return note, then the sibling disambiguation — every sentence earns its place. The trailing pricing block is boilerplate metadata rather than description prose and does not dilute the useful content.

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

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

For a read-only, open-world search with an output schema and full annotation coverage, the description supplies everything needed to call it correctly: what it searches, when to prefer it, how it pages, where results land, and which sibling to use instead for tweet content. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents both 'query' and 'cursor'; the baseline is 3. The description reinforces the keyword-based search and pagination framing but adds no syntax or format detail beyond the schema, and does not address why 'query' is optional despite being the core input.

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

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

States a specific verb+resource ('Search X user accounts by keyword') and the return shape ('matching profiles'). It explicitly distinguishes itself from the nearest functional sibling, get_twitter_tweet_advanced_search, and implicitly from the exact-handle lookup tools, so an agent can pick it without opening another schema.

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

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

Gives a concrete selection condition ('when you know roughly who you are looking for — a company name, a topic, a partial handle — but not the exact @handle') and names the alternative for the adjacent case ('to search tweet content use get_twitter_tweet_advanced_search'). Both the when and the routing alternative are explicit.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description usefully adds pricing ($0.0029 per successful request) and a routing note about the mapped path versus the upstream canonical path, which is real operational context beyond the annotations.

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

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

The core capability and required-parameter guidance are front-loaded, and the optional-parameter detail follows logically. The pricing comment block and path-mapping note add length that is only marginally actionable, slightly diluting an otherwise tight description.

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

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

With an output schema present, rich annotations, and full schema description coverage, the description supplies exactly the missing pieces: required params, filter-token semantics, cost, and endpoint routing. Nothing an agent needs to invoke this correctly is absent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by clarifying that engine and q are both required, that sp carries pagination and advanced filter tokens (upload date, duration, result type), and that gl/hl narrow by country and interface language.

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

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

States a specific verb+resource ('Search YouTube') and enumerates the returned entities (videos, channels, playlists), which an agent can act on immediately. It does not explicitly contrast itself with the sibling 'search' tool, so the distinction is implied rather than stated.

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

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

Gives three concrete use cases (topic discovery, tracking a channel's uploads, gauging coverage) plus the mandatory engine/q pairing. There are no when-not-to-use conditions or named alternatives among the siblings, which keeps it out of 5 territory.

Agents often have multiple tools that could apply. Explicit usage 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 (readOnly, idempotent=false, openWorld), it discloses concrete behavior: 632 KB → ~20 KB, nothing summarised, no post dropped, upstream order preserved, which 9 variants and ~100 flags are dropped, and a pagination limitation the API cannot work around. This is unusually rich.

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

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

Front-loaded with the core purpose and routing, then the survival/removal detail. Slightly long, but nearly every sentence carries decision-relevant information; the byte-savings figures and field list earn their space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-param read tool with an output schema, the description covers projection semantics, dropped fields, ordering, and the pagination constraint. An agent has everything needed to select and 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?

One required parameter with 0% schema description coverage. The description implies the handle identifies a public account whose timeline is fetched, but never explicitly defines the parameter or its format. With a single trivial param and an output schema present, this is adequate but not compensating for the coverage 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 states a specific verb+resource ('one page of a public account's timeline, projected down') and explicitly contrasts with `get_instagram_user_posts`, so an agent can distinguish it from the sibling without opening either schema.

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

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

It gives explicit when-to-use (need compact captions/counts in a context window) and when-not (downloading every resolution, building a player, forensic detail), and routes to the exact alternative tool by name.

Agents often have multiple tools that could apply. Explicit usage 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 establish that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only 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 front-loaded with what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

Complex tools with many parameters or behaviors need more documentation. 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 parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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

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

The description clearly states that this tool gives a catalogue overview: categories, servers per category, tool counts, and a dedicated endpoint. The resource is specific and recognizable, though sibling differentiation is only partial because it references 'tool-router' rather than the listed siblings like search/use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

Agents often have multiple tools that could apply. Explicit usage 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, openWorld, non-destructive), so the bar is lower. The description adds genuine value beyond them: the dual organizations/accounts return shape, the echoed pagination/breadcrumbs, and a cost signal ($0.01975 estimated request). It stops short of noting rate limits or result caps, so it is strong but not exhaustive.

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

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

Three tight sentences, front-loaded with purpose, then output shape, then the routing decision. The appended pricing block is boilerplate but is genuine cost information, and nothing else is wasted.

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

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

For a 24-parameter, zero-required, open-world search with 100% schema coverage and an output schema, the description supplies everything an agent needs: what it searches, what comes back, and when to prefer the cheaper alternative. No critical invocation detail 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 24 parameters, making 3 the baseline. The description names broad filter categories (headcount, funding stage, technologies) that map onto schema properties but adds no syntax or format detail the schema does not already provide.

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

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

States a specific verb+resource ('Find companies matching criteria') and enumerates the filterable dimensions (name, domain, headcount, industry, location, funding stage, technologies). It also distinguishes the result sets (organizations = Apollo global DB, accounts = existing workspace records), so an agent can tell it apart from sibling enrich 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?

Explicit when-to-use ('Use it to build a target list') and an explicit alternative with a selection condition and cost rationale ('When you already know the domain, get_apollo_organizations_enrich answers directly and costs less'). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/open-world, and the description adds substantial non-obvious behavior: no credit consumption, master API key requirement, a 50,000-record display limit (100/page, 500 pages), and guidance to narrow with filters. This is exactly the extra context annotations cannot carry.

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

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

Purpose and key exclusions are front-loaded, but there is mild redundancy from the repeated 'This endpoint...' construction across consecutive sentences. It is appropriately sized for a 23-parameter tool, just slightly repetitive.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 full annotation coverage, the description still supplies everything an agent needs to call it correctly: auth requirement, credit behavior, pagination ceiling, and enrichment alternatives. Nothing material is missing.

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

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

Schema description coverage is 100% across 23 parameters, so the schema already documents each filter in depth. The description adds no per-parameter syntax or pairing guidance beyond the pagination limit note, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('find net new people in the Apollo database') and explicitly contrasts the tool with People Enrichment / Bulk People Enrichment, so an agent can distinguish it from siblings like post_apollo_people_match without opening a schema.

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

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

It states the primary use case (prospecting net new people), the explicit exclusion ('does not return email addresses or phone numbers'), and names the alternative endpoints to use for enrichment. This is an explicit when/when-not/alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower. The description adds real behavioral context beyond them: the exact failure mode (HTTP 422 with 'organization_ids is required') when the required param is omitted, and the response shape (news_articles, pagination). No auth, rate-limit, or cost caveats beyond the injected pricing block.

Agents need to know what a tool does to the 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, front-loaded, and every sentence carries a distinct instruction: required param, how to resolve it, available filters, return fields, and use case. No filler or restatement of the tool name.

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

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

Output schema exists, so return values need not be explained, and the annotations cover the safety profile. Given the description covers the required parameter, its error behavior, the prerequisite chain, filter options, and a use case, 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 coverage is 100%, so the baseline is 3. The description adds meaning on top: it flags organization_ids as required and explains why (and how to obtain values), and gives category examples (funding, hires, launches) plus the date-range and paging parameters as a coherent filtering story. Some overlap with schema text, but the required-param rationale is genuine added value.

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

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

Opens with a specific verb+resource ("News coverage for specific companies") and immediately distinguishes itself from siblings by naming the prerequisite tools (get_apollo_organizations_enrich, post_apollo_mixed_companies_search) rather than describing itself in isolation. An agent can identify the tool's domain without opening the schema.

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

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

Gives an explicit prerequisite (resolve organization_ids first, with two named alternatives) and a concrete motivating use case ("catch a trigger event before reaching out"). It stops short of stating when NOT to use this tool versus other news/social sources in the sibling list, so it is strong but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the 10-company cap and the warning that not every domain may resolve, advising the caller to compare requested vs enriched counts rather than assume success.

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

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

Front-loaded with the core action and cap, then the parameter, then the return caveat, then the sibling pointer. Well ordered and mostly waste-free, though the appended pricing boilerplate inflates length relative to the actionable content.

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

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

Despite an output schema existing, the description helpfully calls out the key response fields and, more importantly, the semantic caveat that counts may not all match. Together with the sibling routing and the 10-domain limit, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the domains array, bare-domain format, and www/@ exclusion. The description reinforces the 'array of bare domains' shape but adds no syntax or format detail the schema lacks, 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 (enrich) and resource (organizations/companies) with scope (up to 10 in one call). Explicitly distinguishes itself from the sibling get_apollo_organizations_enrich by noting that the single-domain case is a plain GET, so an agent can choose between them without opening either schema.

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

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

Provides a clear routing rule: use this for multiple domains (up to 10), use get_apollo_organizations_enrich for one domain. That covers the primary selection decision, though it doesn't state exclusions such as what to do beyond 10 domains or rate-limit behavior.

Agents often have multiple tools that could apply. Explicit usage 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/OpenWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: credit cost is per record enriched rather than per call, and partial matches are possible so the caller should inspect missing_records rather than assume success. It stops short of rate limits or async timing, so a 4 rather than 5.

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

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

Three tight sentences ordered as purpose, body, return/cost, then routing. No wasted prose; the pricing block is an injected boilerplate section rather than authored description text.

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

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

For a paid, nested, non-destructive enrichment call with an output schema, the definition covers input shape, cost model, partial-failure semantics, and sibling routing. Nothing an agent needs in order 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 80%, so a baseline of 3 applies. The description adds value by explaining that body.details is an array of the same identifier objects post_apollo_people_match accepts and is capped at 10, linking the nested schema to the sibling's contract rather than just restating field names.

Input schemas describe structure but not intent. Descriptions should explain 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 (bulk-enrich people), gives the hard cap (up to 10), and explicitly names the sibling it differs from (post_apollo_people_match). An agent can distinguish bulk from single enrichment without opening either schema.

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

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

Gives an explicit routing rule: use this over a loop of single calls for the same credits and one round trip, and fall back to post_apollo_people_match for a single person. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), but the description adds material behavior beyond them: personal emails/phone numbers are withheld by default, revealing them costs extra credits, and a 200 response does not guarantee a match. That last caveat is exactly the kind of non-obvious trait an agent needs. It stops short of noting the async webhook requirement for phone reveals or any rate limiting, so it is not exhaustive.

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

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

It is long, but front-loaded with the core action and then packed with distinct facts (identifiers, placement, return shape, cost, non-match caveat, alternatives) with no filler sentences. The return-field enumeration is arguably redundant given the output schema, which keeps it from a 5.

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

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

Output schema exists so return values need no explanation, yet the description still sketches the person object and note fields for orientation. Combined with identifier options, payload placement, cost implications, and sibling alternatives, an agent has everything needed to invoke this correctly on the first attempt.

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

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

Schema description coverage is 100%, so the baseline is 3, and every body field is already documented with examples. The description still adds semantic value the schema does not: the identifier list is presented as a preference-ordered set ('the more you supply, the likelier the match'), and it flags that reveal_personal_emails lives in the body while reveal_phone_number is a query parameter — a distinction that is easy to get wrong from the schema alone.

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

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

The description opens with a specific verb+resource: 'Enrich one person', and immediately bounds scope ('one person' vs bulk). It explicitly names the sibling tools it is not (post_apollo_people_bulk_match, post_apollo_mixed_people_api_search), so an agent can discriminate among the Apollo people tools without opening any schema.

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

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

It gives explicit routing rules: use bulk match for up to 10 people in one call, and use mixed_people_api_search when no identifier exists and candidates must be found first. It also states the entry condition (supply whatever identifiers you have, more is better) and the payload-placement rule (body, not query string).

Agents often have multiple tools that could apply. Explicit usage 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 (readOnlyHint=false, destructiveHint=true, idempotentHint=false) are counterintuitive for a data-retrieval endpoint, and the description does not reconcile that tension or mention auth or rate limits. It does add genuinely useful behavioral context the annotations lack: the request is billed per call at roughly $0.002 USD, and higher block_depth may incur extra charges.

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

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

The core capability is stated in the first sentence, followed by a docs link and a clearly delimited pricing block. It is compact and front-loaded, with only mild boilerplate in the trailing URL and billing lines.

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

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

An output schema exists, so return values need not be described, and the description covers purpose, location/language dependence, and cost. However, for a paid, multi-field live SERP call it omits which fields are required and when to use it versus the other SERP/social siblings, leaving real gaps.

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

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

The description generically notes that results are specific to the selected location and language settings, mirroring location_code/language_code, but adds no syntax, defaults, or constraints beyond the schema. The nested field descriptions (os, device, block_depth, keyword encoding rules) already carry that load, so the description contributes little parameter meaning.

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

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

The description names a specific verb and resource: it 'provides real-time data on the top 20 blocks of YouTube search engine results', scoped to live SERP with location/language targeting. That is enough to distinguish it from a generic search sibling like get_youtube_search, though it never names an alternative explicitly.

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

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

There is no guidance on when to choose this live endpoint over a batch/standard SERP tool, nor any stated prerequisites even though the nested schema marks keyword, and one of location/language, as required. The reader is only told what the results depend on, not when this tool is the right pick.

Agents often have multiple tools that could apply. Explicit usage 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/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: a `not_found` status with null value is a normal outcome rather than an error, and it is still billed as one valid lookup, plus the per-lookup pricing unit. It does not mention auth requirements or rate limits, so it stops short of a 5.

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

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

Front-loads the core action and payload, then layers response shape, error semantics, and routing in descending order of importance. The embedded pricing comment block is machine-generated noise, but the prose itself is tight with no filler.

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

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

An output schema exists, so return values were already documented, yet the description still surfaces the two things an agent actually needs to reason about: the `not_found` case is normal and billable, and one creator is handled per call. Combined with the sibling routing, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 0% at the top level (the single nested `body.profile_url`), so the description must compensate, and it does: it tells the agent to pass `profile_url` and constrains the accepted values to Instagram, TikTok, or YouTube profile URLs, matching the schema example. It adds no syntax rules (e.g., trailing slash or handle-only input), so it is not fully exhaustive.

Input schemas describe structure but not intent. Descriptions should explain 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 — looks up the contact email for exactly one Instagram/TikTok/YouTube creator from a profile URL — and names the sibling alternatives (Similar Creators, AI Search) it is not. An agent can distinguish this from post_waveinflu_ai_search or post_waveinflu_similar_creators without opening any schema.

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

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

Explicit routing guidance: use the list-producing endpoints first to assemble a creator list, then call this endpoint for the creators whose `email` came back null. The one-creator-per-call constraint is stated outright, which prevents batching misuse.

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