AIsa Sales

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description gives no guidance on when to use this tool versus the sibling 'use' tool. The schema note about 'steps at the same execution_level of a plan go in one batch' is helpful, but it lives in the schema, not the description. The description only implies batching via concurrency but doesn't state when to choose it over the single-operation alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context about workspace scope ('shared AIsa workspace, not Apollo's global database') and return content ('full field set including custom fields and owner'), which goes 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?

Two concise sentences, front-loaded with the core purpose, followed by essential routing guidance. No wasted words; every sentence earns its place.

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

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

For a single-parameter read tool with an output schema, the description covers what it returns, how to get the id, and when to use alternatives. Nothing essential is missing.

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

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

Schema describes the id simply as 'Account ID' (100% coverage). The description adds meaning by specifying it's an Apollo id and explaining how to obtain it via post_apollo_accounts_search, which is helpful for correct parameter usage.

Input schemas describe structure but not intent. Descriptions should explain 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 exactly what the tool does: retrieves one saved account by its Apollo id, with a full field set including custom fields and owner. It clearly distinguishes from siblings by referencing how to find the id and an alternative for unsaved companies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructs when to use this tool (saved accounts) and when not (unsaved companies → get_apollo_organizations_enrich), and tells the agent to use post_apollo_accounts_search to find the id. No ambiguity.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavior context: the result is a workspace-specific list rather than a global enum, and it returns an `account_stages` array with the relevant fields. No contradiction with annotations, though auth or rate-limit details are not added.

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

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

The description is two sentences with no filler. It front-loads the resource and response shape, then supplies the operational caveat and usage timing. Every clause contributes either return-structure information or actionable call 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?

For a zero-parameter, read-only list tool with an output schema and rich annotations, the description is complete: it states the resource, return shape, usage timing, and the workspace-specific caveat. Nothing an agent needs to invoke the tool correctly is missing.

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

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

There are zero parameters, and the schema already documents this with an empty properties object and no required fields. The description confirms 'Takes no parameters,' which matches the schema. With zero parameters, the baseline is 4, and the description adds no extra burden.

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

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

The description names a specific verb and resource: it lists the 'account stages' configured in the workspace and enumerates the exact response fields (`id`, `name`, `display_name`, `display_order`, `category`, `is_meeting_set`). The 'account' qualifier clearly distinguishes this from the sibling stage tools for contacts and opportunities, so an agent can select it without opening the schema.

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

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

The description gives explicit when-to-use guidance: 'Call it before creating or updating accounts' and explains why: stage fields expect a stage id and the set is workspace-specific rather than a fixed enum. It does not explicitly name alternative stage tools, but the account-specific framing makes the intended context 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 the read-only, idempotent, non-destructive profile. The description adds useful behavioral context beyond those annotations: it returns the full field set including custom fields/owner/stage, and it targets the shared workspace rather than the global database. No contradiction.

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

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

Three short sentences, each earning its place: what the tool returns, how to find the input id, and which data scope is read. Front-loaded and free of filler.

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

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

For a single-parameter read tool with rich annotations and an output schema, nothing critical is missing. The agent knows the id source, the workspace scope, and the returned fields. No further behavioral or safety disclosure is needed.

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

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

With 100% schema description coverage, baseline is 3. The description adds practical meaning by clarifying that the parameter is an Apollo contact id and that it should be obtained via post_apollo_contacts_search. This goes beyond the schema's bare 'Contact ID' label.

Input schemas describe structure but not intent. Descriptions should explain 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 the exact operation: retrieve one saved contact by its Apollo id. It adds meaningful specifics—the full field set including custom fields, owner, and stage—and clearly distinguishes itself from search and bulk sibling tools. No tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for correct use: find the id with post_apollo_contacts_search. It also scopes the data source by noting it reads the shared workspace rather than Apollo's global database. It does not enumerate every when-not condition, but the routing context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds workspace-specific scoping and output array details, but beyond that it provides no additional behavioral context such as pagination or rate limits. This is a reasonable score given the strong 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?

Three concise sentences: the first states the result and shape, the second notes zero parameters, and the third gives a concrete usage workflow. Every sentence earns its place, and the important scoping and downstream usage are front-loaded.

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

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

Given zero parameters, rich annotations, and an output schema, the description provides everything needed to invoke the tool correctly. It also explains the workspace-specific nature and the downstream consumer, so no critical information is missing.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is no parameter documentation burden. The description reinforces 'takes no parameters,' which meets the baseline for a parameterless 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 clearly states the tool returns the workspace's contact stages as a `contact_stages` array with named fields. The 'contact' qualifier differentiates it from sibling tools like `get_apollo_account_stages` and `get_apollo_opportunity_stages`, so an agent can select it correctly.

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

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

It gives explicit context for when to call this tool: before setting a contact's stage, because `post_apollo_contacts_update_stages` expects a stage id from this list. It does not mention exclusions or alternatives, but the primary use case is made clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those hints: the notion of per-account state ('sending limits and per-account state') and the operational consequence of unhealthy mailboxes, which is valuable for an agent deciding whether a sequence is ready. 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?

Two sentences with no fluff: the first identifies the resource and return payload, the second confirms no parameters and adds a practical usage tip. Every sentence earns its place and the key information is front-loaded.

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

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

For a no-parameter, read-only, idempotent tool with an output schema, the description covers everything an agent needs: what it returns, that it requires no arguments, and when to invoke it in a sequence workflow. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema provides no explanatory burden. The description explicitly states 'Takes no parameters,' removing any ambiguity about hidden or optional inputs, fully covering parameter semantics for an agent.

Input schemas describe structure but not intent. Descriptions should explain 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 resource ('mailboxes connected to this workspace') and the return shape ('email_accounts array with sending limits and per-account state'), making it clear this is a list/read tool for email accounts. It is distinct from siblings like get_apollo_accounts_id or get_apollo_users_search because it explicitly identifies mailboxes rather than org accounts or users.

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

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

The description gives a concrete trigger: 'Check it before activating a sequence' and explains the consequence (a sequence without a healthy mailbox won't send). It provides clear context for when to use it, though it does not explicitly name alternatives or exclusions, which keeps it one step below the top score.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds meaningful behavioral context beyond them: the specific event types returned and the semantic distinction between delivery state and recipient behaviour. It does not cover pagination or volume limits, but the output schema exists and the added semantics are genuinely useful.

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

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

Three sentences, each earning its place: the first states the core purpose, the second gives the required prerequisite, the third explains the sibling distinction. The most important scoping information is front-loaded and there is zero filler.

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

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

For a single-parameter, read-only tool with an output schema and full schema coverage, nothing an agent needs to call it correctly is missing. The description covers purpose, the dependency on the search tool, and the alternative to avoid; the annotations and output schema cover safety and return shape.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value above that by telling the agent exactly where to source the value for the `id` parameter ('Get the message id from get_apollo_emailer_messages_search'). This cross-tool provenance is more helpful than typical parameter descriptions.

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

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

The description states a specific verb and resource ('Engagement events for one sent email: opens, clicks, replies and bounces, with timestamps') and immediately differentiates it from the message record tool, which 'carries delivery state but not recipient behaviour.' An agent can tell this apart from get_apollo_emailer_messages_search and the campaign tools without opening schemas.

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

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

The description explicitly routes the workflow: 'Get the message id from get_apollo_emailer_messages_search.' It also names the alternative and explains why not to use it ('rather than inferring engagement from the message record itself'), giving a clear when-to-use and when-not-to-use signal with a concrete prerequisite.

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

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

Annotations already signal read-only, idempotent, safe behavior Mendes. The description adds useful behavioral context beyond them: it states the workspace scoperessed, that results include emailer_messages with emailer_steps, and that emailer_steps indicate sequence position. This is meaningful but does not discuss pagination or filtering edge cases.

Agents need to know what a tool does to the 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 focused sentences with no filler. The first states the action, the second clarifies the return shape, and the third redirects to the relevant sibling tool. Every sentence earns its place.

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

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

The description is complete for a search tool with all-optional parameters and an output schema. It highlights the key relationship between emailer_messages and emailer_steps and names the sibling for engagement metrics. Minor details like pagination defaults and accepted filter formats are not described, but the schema and output schema largely cover those.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters. The description itself adds no extra parameter-level meaning, but the existing parameter descriptions are adequate for basic usage. This is the expected baseline given full schema coverage.

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

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

The description names a specific verb ('Search'), a specific resource ('individual outreach emails'), and a clear scope ('already sent or scheduled from this workspace'). It distinguishes this tool from the sibling engagement tool by clarifying what it does and what it is not for.

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

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

The description gives an explicit use case ('Use it to see what actually went out') and names the exact alternative for per-message engagement ('get_apollo_emailer_messages_id_activities'). This is clear when-to-use and when-not-to-use guidance that an agent can act on directly.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond that: the approximate entry count, the shape of the response, and the fact that it takes no parameters. This is meaningful supplementary detail for a simple read tool.

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

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

The description is information-dense with no filler. It front-loads the main purpose, then efficiently covers response contents, alternative tools, and usage relevance in a compact format.

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

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

For a zero-parameter read-only tool with an output schema and rich annotations, the description is complete. It tells the agent what comes back, how much, how it is organized, and how it relates to the rest of the API.

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

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

The input schema contains zero parameters, so the baseline is 4. The description reinforces this with 'Takes no parameters' and adds no unnecessary parameter information, which is appropriate.

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

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

The description clearly states the resource: every Apollo field, standard and custom, returned as `fields` and `field_groups`. It includes specific attributes of the entries and explicitly distinguishes itself from `get_apollo_typed_custom_fields`, making the purpose unambiguous.

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

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

It explicitly frames this tool as the reference for what can be filtered or written elsewhere in the API, which tells an agent when to reach for it. It also names the smaller alternative for custom fields only, providing a clear routing decision.

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

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

The annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, so the bar is lower. The description adds genuinely valuable runtime context: the bare-array-to-wrapped-response behavior, that an empty result is normal, and that the tool's practical purpose is ID resolution. This goes beyond what annotations provide.

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

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

Every sentence earns its place: it names the resource, explains the response wrapping quirk, states there are no parameters, clarifies the empty case, and gives the intended use. It is compact while covering all necessary operational nuance.

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

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

For a zero-parameter, read-only list tool with an output schema, the description is complete. It covers what is returned, how it appears as an MCP result, the empty case, and how the tool should be used. 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?

There are zero parameters and the schema is fully covered, so no parameter documentation is needed. The description correctly states 'Takes no parameters,' which matches the schema and removes any doubt about required 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 identifies the resource ('lists (labels) defined in this workspace') and the tool's role in resolving list names to IDs for filters. It does not explicitly name sibling tools to differentiate itself, but the resource is unambiguous among the many get_apollo_* 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?

It gives a concrete, actionable usage directive: 'Use it to resolve a list name into the id that contact and account filters expect.' It does not state when not to use the tool or mention alternatives, but the context is clear enough for an agent to decide.

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

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

The description discloses the HTTP 400 error behavior and explicitly warns that the schema's 'optional' flags are misleading—valuable context beyond the annotations (readOnlyHint, idempotentHint, etc.). It adds meaningful behavioral information without contradicting the annotations.

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

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

The description is compact—two sentences—with the core purpose first and the critical warning second. It avoids redundancy with the schema and earns its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read tool with a full input schema and an output schema (indicated), the description covers the most important behavioral gotcha (mandatory filter) and is sufficient for an agent to invoke it correctly. It does not mention pagination or return format, but those are handled by the schema and output schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so each parameter already has a descriptive comment. The tool description lists the filter options but adds no new meaning beyond the schema—it merely repeats the filter names. The filter-requirement warning is already embedded in every schema parameter description, so the description provides no incremental parameter insight.

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

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

The description states a clear verb and resource ('Notes attached to workspace records'), which immediately conveys what the tool returns. It lists the specific filter parameters, adding precision. Although it does not explicitly contrast with siblings, none of the many sibling tools appear to overlap with note retrieval, so the purpose is unambiguous.

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

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

The description gives crucial usage guidance: at least one filter is required, otherwise the endpoint returns HTTP 400. It also clarifies that the spec's per-parameter 'optional' markings are misleading. However, it does not mention when to choose this tool over alternatives or any exclusions, so it falls short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds 'full field set' and 'one deal' context, but does not disclose error behavior, rate limits, or other edge-case behavior. It is adequate but not rich beyond 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?

Two clear, front-loaded sentences with no redundancy. The core purpose is stated firstks, and the workflow hint is placed second.

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

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

For a single-parameter read tool with an output schema and comprehensive annotations, the description supplies everything needed: what to pass, how to get it, and what to expect. No significant gaps remain.

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

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

Schema coverage is 100%, so the parameter is fully described structurally. The description adds value by clarifying that the opportunity_id is an Apollo id and by telling the agent how to find that id before invoking the 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 clearly states a specific verb ('deal' fetch) and resource ('one deal by its Apollo id'), and explicitly contrasts it with the search tool that finds ids. This distinguishes it from sibling tools like get_apollo_opportunities_search and patch_apollo_opportunities_opportunity_id.

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

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

The description provides a clear usage workflow: use get_apollo_opportunities_search to find the id, then call this tool. It does not explicitly state when not to use it, but the context is enough for an agent to select it appropriately for id-based fetches.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: the shared workspace warning that results include deals from other AIsa callers, and the explicit list of returned fields. This helps agents understand the open-world nature and result shape.

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

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

The description is compact and front-loaded: it states the action, filters, pagination, return fields, and the critical shared-workspace warning in three sentences. Every sentence earns its place with no redundancy.

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

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

The description covers the essential context: what the tool does, what filters are available, pagination, return fields, and the shared workspace caveat. With an output schema present and annotations covering safety, the description is nearly complete. It could mention sort options or filter parameter names, but these are minor gaps given the schema coverage.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (page, per_page, sort_by_field). The description adds filter semantics (owner, stage, amount, close date) that map to the search behavior, but doesn't detail how these map to the actual parameters. Baseline 3 is appropriate since schema covers parameter basics.

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

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

The description clearly states the tool's purpose: 'Search deals in this workspace' with specific filter dimensions (owner, stage, amount, close date) and pagination. It distinguishes itself from sibling tools like get_apollo_opportunities_opportunity_id (single opportunity lookup) and post_apollo_opportunities (creation) by focusing on search/list behavior.

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

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

The description provides clear context for when to use this tool: when searching deals in the workspace with filters. It doesn't explicitly name alternatives or exclusions, but the filter and pagination guidance implies the search use case. The shared workspace warning also helps agents understand the context of results.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior, and the description adds a non-obvious behavioral detail: `probability` is what turns a stage into a forecast number. Nothing in the description contradicts the annotations.

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

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

The description is two concise sentences: the first front-loads the return shape, and the second provides practical usage context. There is no filler or redundant restating of schema details.

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

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

For a simple parameterless lookup, it includes the main output shape, key field names, when to call it, and an important nuance around probability and forecasting. Combined with the existing output schema and annotations, nothing needed for correct invocation is missing.

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

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

The input schema is empty and the description explicitly states 'Takes no parameters,' which is sufficient for a zero-parameter tool. This matches the baseline for parameterless tools, and no further semantic detail is needed.

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

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

The description clearly states that the tool returns the deal stages configured in the workspace, specified as an `opportunity_stages` array with named fields. This is specific, not a tautology, and the 'deal stages' scope distinguishes it from sibling stage tools for accounts and contacts. The intent is unambiguous.

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

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

It explicitly instructs the agent to call this tool before creating or moving a deal, and explains that stage fields expect an id from this list. This gives a clear when-to-use context, though it does not explicitly name stage-related alternatives or when-not-to-use cases.

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

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

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

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

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

The description is compact and front-loaded: the core action and constraint appear in the first sentence, followed by the return shape and routing guidance. Every sentence earns its place, and the sibling references are concise without being verbose.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior; the description adds useful constraints that the endpoint is id-keyed only and enumerates the deeper field categories returned. It does not discuss errors, rate limits, or authentication, but those are less critical with a single read-only parameter and output schema present.

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

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

Three sentences with no filler: purpose, return contents, and prerequisite/constraint. Important information is front-loaded and every sentence earns its place.

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

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

For a single-parameter, read-only endpoint with full schema coverage and an output schema, the description covers the necessary calling context: what is returned, how to obtain the id, and what input is not accepted. No critical information for correct invocation is missing.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by emphasizing that the param must be an Apollo organization id (not a domain), reinforcing the source endpoints, which is useful beyond the schema's generic string description.

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

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

Description opens with a specific resource (complete Apollo record for one company), identifies the key-by identifier (Apollo organization id, not domain), and contrasts with the enrichment sibling by saying it returns 'everything enrichment returns plus deeper fields.' This clearly distinguishes it from get_apollo_organizations_enrich and other 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?

It explicitly tells the agent to first obtain the id from get_apollo_organizations_enrich or post_apollo_mixed_companies_search, and states the endpoint cannot take a domain. This is a clear when/when-not with named alternatives.

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

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

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

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

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

Four sentences, each carrying distinct value: what the tool returns, why it is useful, how to get the required ID, and a data-source caveat. No redundant words or filler.

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

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

The description covers the prerequisite, the use case, and the key caveat, while the output schema handles return values. For a tool with three simple parameters and rich annotations, nothing critical is missing.

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

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

Schema description coverage is 100% — all three parameters (page, per_page, organization_id) are fully documented with examples. The description adds nothing beyond the schema for these parameters, so the baseline score of 3 is appropriate.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat those. It adds meaningful behavioral context by explaining the data provenance: a call only appears if something logged it into Apollo, and it discloses the shape of the response (pagination, breadcrumbs, faceting, pipeline_total).

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

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

Two sentences with no waste. The main action and scope are front-loaded, and the clarifying caveat about logged versus telephony data earns its place without bloating the 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?

The tool is a read-only search with fully described parameters and an output schema present. The description adds the key non-obvious caveat about data provenance, making it sufficiently complete for an agent to invoke safely and 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?

All 12 parameters have individual schema descriptions and 100% coverage, so the schema already carries the parameter semantics. The description does not add parameter-level guidance beyond that, which is acceptable given the high schema coverage.

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

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

The description opens with a specific verb and resource: 'Search logged calls in this workspace.' It also enumerates the returned fields and explicitly distinguishes these records from telephony data, which helps separate it from raw call-log or other search tools.

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

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

The description implies when to use the tool — when you need logged call records in the workspace — and clarifies a boundary ('not telephony data'). However, it never explicitly names alternatives or states when not to use this tool versus sibling search tools such as get_apollo_emailer_messages_search.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description is not required to restate those. It adds meaningful context by disclosing that the data is workspace-specific and that invalid values are rejected rather than coerced. No contradiction with annotations; the read-only claim aligns with the tool's role as a pre-write lookup.

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

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

The description is compact and every sentence earns its place: return shape, parameterlessness, and usage guidance. The most important information is front-loaded, and there is no filler or repetition of annotation details.

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

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

For a parameterless, read-only list tool, the description is complete: it names the returned data, explains workspace-specific variability, and tells the agent when to use it. The output schema and annotations cover return structure and safety semantics, so nothing needed for correct invocation is missing.

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

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

There are zero parameters and the input schema is empty, so the description's explicit 'Takes no parameters' fully resolves any ambiguity. Per the baseline for zero-parameter tools, no further parameter explanation is needed.

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

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

The description clearly identifies what is returned: custom fields defined in this workspace, with the exact output shape (`typed_custom_fields` array of `id`, `name`, `system_name`, etc.). It also distinguishes this read operation from write operations by framing it as 'Call it before writing a custom field'. Even without naming a sibling, the purpose is unambiguous.

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

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

The description explicitly states when to use this tool: before writing a custom field, because field keys and picklist values are workspace-specific and invalid values are rejected rather than coerced. It does not name alternative tools or explicitly state when not to use it, but the usage 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?

The annotations already mark the call read-only and non-destructive, but the description adds significant behavioral facts: it exposes members' email addresses, notes that the workspace belongs to AIsa rather than the caller, and warns about ~16-second latency. These are meaningful details not inferable from annotations alone.

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

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

Three tightly written sentences: one for output shape, one for the use case, and one for caution/performance. Every sentence earns its place with no filler or redundant schema repetition.

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

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

An output schema exists, so return values need no further explanation. Combined with the use case, sensitivity warning, and performance caveat, the description gives an agent everything needed to select and safely invoke this tool.

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

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

Schema description coverage is 100%, so page and per_page are already fully documented. The description adds no extra parameter semantics, which aligns with the baseline of 3 for high schema coverage.

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

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

The description identifies the resource (user accounts in the Apollo workspace) and the returned structure (users array with id, name, email, credits, pagination), while the title supplies the 'list' verb. No sibling tool covers user accounts, so it is clearly distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 concrete use case: resolving an owner_id from contacts, accounts, or deals into a person. It also cautions about exposing workspace members' emails and workspace ownership, which helps the agent judge appropriateness. It doesn't name alternatives, but no sibling tool lists users, so that's acceptable.

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

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

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

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

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

The description is moderately long but well structured: it opens with the core purpose, then explains the price model in a dedicated paragraph. No redundancy or filler. It front-loads the most critical information (contract fields) and then gives necessary detail about price semantics. Slightly dense but not overly verbose.

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

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

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

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

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

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

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

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

The description states a specific purpose: returning the full contract of one or more operations, including schemas, read_only, side_effects, price, and known_pitfalls. It clearly distinguishes this from executing operations (use, batch_use) and from discovery (search, list_categories). The verb 'get' and the noun 'details' align with the title, and the first sentence is explicit.

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

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

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

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), but the description adds only a note about the response envelope (meta + data). It does not disclose pagination behavior, rate limits, or any operational constraints beyond what the schema already implies. Minimal added value over 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 extremely short, but this is under-specification rather than effective conciseness. It omits essential purpose and usage context. The response-format note is the only substantive content, but it does not earn its place given the critical missing 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?

Despite having an output schema, the description fails to explain what 'Ad Networks' data represents, when to use the tool, or how it differs from similar tools. For a 10-parameter endpoint with many siblings, this is severely incomplete. The only useful hint is the response envelope, which is minor.

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

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

Schema description coverage is 100%, so all 10 parameters are fully documented in the schema. The description adds no parameter-specific meaning, but the baseline of 3 applies because the schema already handles the semantic load.

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

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

The description restates the title ('Ad Networks') without specifying the action (e.g., retrieve, list) or the resource context (domain ad networks). It gives no verb and no differentiation from sibling SimilarWeb tools, making it tautological rather than informative.

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

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

There is no guidance on when to use this tool versus alternatives. With over 40 SimilarWeb sibling tools, no selection criteria or exclusions are provided. The agent must infer usage purely from the name and schema.

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, and non-destructive behavior, so the bar is lower. The description adds the SimilarWeb v5 envelope shape (meta + data), which is useful context, but no other behavior or side-effect information is disclosed.

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

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

The description is extremely short and the envelope sentence is terse and useful, but the opening phrase merely restates the title and 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?

Despite rich schema and annotations, the description omits the fundamental meaning of 'audience interest', what data will be returned conceptually, and why an agent would invoke this sibling over closely related SimilarWeb audience tools.

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

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

Parameter semantics are fully handled by the schema at 100% coverage, and the description adds nothing about parameters. This meets the baseline but contributes nothing beyond the schema.

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

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

The description is essentially a title repetition ('Audience Interest') plus a note on the response envelope. It names no verb or resource, and gives no basis for distinguishing it from sibling tools like get_similarweb_audience_overlap.

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

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

There is no guidance on when to choose this tool over other SimilarWeb tools. The agent must infer intent purely from the tool name, with no exclusions or alternatives provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. On top of that, the description adds genuinely useful behavioral details: the response shape follows the SimilarWeb v5 envelope, data may be grouped as an array of arrays, and billing counts rows across groups. This goes beyond the annotations and helps agents interpret results correctly.

Agents need to know what a tool does to the 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 useful content is compact and front-loaded: the envelope format and the array-of-arrays caveat are stated in two sentences. However, the first sentence 'Audience Overlap.' is redundant with the tool title and does not earn its place. The structure is adequate but not tight.

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

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

Although the schema and output schema are rich, the description still fails to explain what 'audience overlap' means semantically or when an agent should invoke this tool. It provides response-shape details but omits the core conceptual context needed to distinguish it from SimilarWeb siblings. The billing caveat is useful but not sufficient for completeness.

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

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

Schema description coverage is 100%, so the schema already documents every parameter clearly, including domains, dates, country, and granularity. The description does not add any additional parameter-level meaning, but it does not need to because the schema carries the full burden. Baseline 3 is appropriate.

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

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

The description opens with 'Audience Overlap,' which simply repeats the title and does not state what the tool does. There is no verb or explicit resource explanation, so an agent gets no functional definition beyond the tool's name. The name hints at the metric, but the description itself is tautological.

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

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

No guidance is given about when to call this tool versus the many sibling SimilarWeb tools. There are no exclusions, alternatives, or conditions. The surrounding metadata is rich, but the description provides no decision support for tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the response envelope format (meta + data) and the date span constraint, which are useful context beyond the annotations. However, it does not disclose anything about pagination, rate limits, or error behavior, but given the annotation coverage, a 3 is reasonable.

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

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

The description is very short (two sentences) and front-loads the title, with the response envelope and date constraint following. It is efficient and not bloated, but it is under-specified. Conciseness alone is high, though it sacrifices completeness.

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

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

Given the tool has 7 parameters and many sibling SimilarWeb tools, the description is severely incomplete. It does not explain what 'deduplicated audience' means, what data it returns, or how it relates to other audience-related tools. While an output schema exists, the description fails to give an agent enough context to decide when to invoke this tool versus a sibling.

Complex tools with many parameters or behaviors need more documentation. 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% — every parameter has a description in the schema (e.g., domain, country, granularity, etc.). The description adds no parameter-specific meaning beyond what the schema already provides. Baseline 3 applies because the schema fully documents parameters.

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

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

The description is essentially the tool name itself: 'Deduplicated Audience' is a noun phrase that restates the title without a verb or specific resource. It does not state what the tool does (e.g., 'get deduplicated audience metrics for a domain') and does not differentiate it from sibling SimilarWeb tools like get_similarweb_audience_overlap or get_similarweb_traffic_engagement. The added notes about the response envelope and date constraint are peripheral, not the core 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?

No guidance is given on when to use this tool versus the many similar SimilarWeb audience tools. The only usage-related information is a date constraint (span must be 1–120 monthly buckets), which is a validation rule rather than a decision guide. There are no exclusions or alternative tools mentioned.

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

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

The description adds two behavioral details beyond the annotations: the response envelope ('meta + data') and the critical constraint that start_date and end_date must be in the same month. These are useful and non-obvious. However, it does not describe other behavior such as error conditions or rate limits. It does not contradict the readOnlyHint/idempotentHint 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 extremely short (two sentences) but the first sentence 'Demographics.' is useless filler that adds no information. The valuable date constraint is placed second, not front-loaded. It reads as under-specified rather than deliberately 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 tool with 8 parameters, 4 required, and an output schema, the description fails to explain what the tool actually returns or when to use it. The core question—what demographic metrics are provided—is left unanswered. The two behavioral notes (envelope and date constraint) are helpful but far from sufficient for an agent to understand the tool's role among dozens of SimilarWeb siblings.

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

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

The input schema already provides descriptions for all 8 parameters (100% coverage), which sets a baseline of 3. The description adds the month-matching constraint that directly clarifies the date parameters. It does not elaborate on other parameters like main_domain_only or web_source, but the schema covers those adequately.

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

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

The description is merely the word 'Demographics.' with no verb, resource, or scope. It doesn't state what demographic data is returned (e.g., age, gender, income) or how it differs from the many similar SimilarWeb audience tools. It is nearly a tautology of the tool name.

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

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

No guidance is given on when to use this tool versus alternative tools like get_similarweb_audience_interest or get_similarweb_website_top_geographies. It does not mention prerequisites, typical scenarios, or exclusions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There is no guidance on when to use this tool versus alternatives such as get_similarweb_keywords, get_semrush_organic_competitors, or get_similarweb_similar_sites. No context is given about the use case for keyword competitor data, and no exclusions or prerequisites are mentioned.

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

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

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

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

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

The two substantive sentences are dense and valuable, but the opening 'Website Keywords' is a tautological filler that occupies the front-loaded position. It should have been replaced with an actual action statement.

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

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

Given the 100% schema coverage, an output schema, and safety-focused annotations, the description covers the remaining non-obvious contract details: date-range span, response grouping, and billing. Nothing needed to call the tool correctly appears missing, though the absent purpose statement lowers the overall completeness.

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

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

With 100% schema description coverage, the baseline is met. The description goes beyond the schema by constraining the start_date/end_date span to 1–3 monthly buckets, which cannot be inferred from any individual parameter description.

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

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

The opening phrase 'Website Keywords' simply restates the title and implies an action only through the tool name. The rest of the description covers response shape and date constraints, not what the tool actually retrieves. It also does not differentiate it from the sibling get_similarweb_keyword_competitors.

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

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

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

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds one behavioral detail: the response follows the SimilarWeb v5 envelope (meta + data). This is useful context beyond the annotations, but it does not disclose rate limits, auth, or other operational traits. Given the strong annotation coverage, a 3 is appropriate.

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

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

The description is very short (two sentences), so it is concise, but the first sentence 'Landing Pages' is redundant with the title and adds no value. The second sentence about the envelope is the only useful content. It is front-loaded but under-specified; it is not bloated, but it also doesn't earn all its 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?

With 10 parameters, 3 enums, and a clear need to know what data is returned, the description is grossly incomplete. It fails to state the tool's purpose, which is fundamental. Even though an output schema exists, the agent cannot correctly select this tool because it doesn't know what it does. The description is inadequate for a tool of this complexity.

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

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

Schema description coverage is 100%, so every parameter already has a description in the schema. The tool description adds no extra meaning about parameters – it doesn't mention any of them or clarify their semantics beyond what the schema provides. Baseline 3 is correct.

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

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

The description simply repeats the title 'Landing Pages' without stating the function. It does not specify that the tool returns landing page data for a domain, and the only additional detail is about the response envelope, which is about format, not purpose. This is a tautology that gives an agent no clue what the tool actually does.

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

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

There is no guidance on when to use this tool versus alternatives like get_similarweb_popular_pages or other SimilarWeb endpoints. No context is given about use cases, prerequisites, or why an agent would choose this over siblings. The description provides zero directional help.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveness, so the bar for description-added context is lower. The description adds useful behavioral information beyond annotations: the SimilarWeb v5 envelope format and the 1–120 monthly-bucket date constraint. There is no contradiction with the annotations.

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

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

The description is brief and front-loaded: it gives the resource name, response envelope, and key date constraint in two short statements. The initial noun phrase duplicates the title, but the overall size is appropriate and there is no filler.

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

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

Given the rich input schema, strong annotations, and presence of an output schema, the description covers the essential extra context: response envelope and date-window limitation. The 'legacy' suffix is not explained, and the tool's exact semantic output is left to inference, but an agent has enough 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?

The input schema already covers 100% of parameters with descriptions, defaults, and enums, so the baseline is 3. The description adds a cross-parameter constraint — start_date and end_date must span between 1 and 120 monthly buckets — which is not present in the schema and is directly relevant to invocation.

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

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

The opening phrase 'Marketing Channel Sources' simply restates the tool title and lacks a verb such as 'retrieves' or 'returns.' The response-envelope and date-constraint notes imply this is a data-returning endpoint, so it is not a pure tautology, but the actual purpose and payload semantics remain vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 sibling tools like get_similarweb_referrals, get_similarweb_ad_networks, or get_similarweb_traffic_engagement. The only operational note is a date-window validation rule, which is not a usage condition or alternative-selection criterion.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful non-obvious behavior: the SimilarWeb v5 envelope, possible array-of-arrays grouping, and cross-group billing behavior. This exceeds annotation coverage, though it omits auth/rate-limit details and does not describe exact data contents.

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

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

The description is short and the envelope/grouping note is economical, but the first sentence 'Popular Pages.' is a redundant restatement of the title and contributes no information. The useful content is front-loaded after a wasted lead-in.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 many similar siblings, the description is not complete enough for selection or correct invocation: it omits the fundamental purpose and usage context. The output schema and parameter schemas cover mechanics, but the description leaves the core 'what does this tool do' to inference from the name.

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

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

Schema coverage is 100%, so parameters like domain, start_date, end_date, country, web_source, limit, and offset are fully described in the schema. The description adds no parameter-level semantics beyond relating billing to row groups, 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 opens with 'Popular Pages,' which merely restates the title and tool name without stating what the tool does or what 'popular pages' means. It never names the resource, the action (e.g., retrieve/count), or how this differs from siblings like get_similarweb_landing_pages or get_similarweb_keywords.

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

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

There is no guidance about when to call this tool versus the many sibling SimilarWeb getters, no prerequisites, and no exclusions. The only operational note concerns billing and response grouping, which is not use-case guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral details: the response follows the SimilarWeb v5 envelope, and the requested date span is limited to 1–120 monthly buckets. It does not describe pagination, rate limits, or what happens on invalid spans, but it adds meaningful 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 description is short and mostly to the point, with the substantive constraint front-loaded after the opening phrase. However, the initial sentence "PPC Spend." is redundant with both the tool name and title, wasting the first opportunity to say something informative. It is concise but not maximally economical.

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

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

The schema and output schema carry a lot of the burden, and the description adds the date constraint and response envelope. What is missing is a clear statement of what the returned PPC spend metrics represent and how this tool differs from the many other get_similarweb_* metrics. For an agent choosing among more than 30 SimilarWeb siblings, this is a meaningful gap.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already documents every parameter. The description adds value beyond the schema by stating the allowable start_date–end_date span in monthly buckets, a constraint not present in any parameter description. This is a genuinely useful semantic addition for correctly constructing the request.

Input schemas describe structure but not intent. Descriptions should explain 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 "PPC Spend," which restates the tool title and does not use a verb to state what the tool does. The later envelope and date constraint mentions provide context, but they never clarify that this tool retrieves paid-search/PPC spending metrics for a domain. Purpose is therefore left to inference from the tool name.

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

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

No when-to-use or when-not-to-use guidance is provided, and no alternative tools are named despite many SimilarWeb sibling tools that could overlap (e.g., get_similarweb_ad_networks). The only guidance is a date-span constraint, which is parameter-level rather than selection guidance. An agent must infer when this tool 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 the operation as read-only, idempotent, and non-destructive, so the description's extra notes are valuable rather than redundant. It adds a concrete behavioral contract: the response follows the SimilarWeb v5 envelope (meta + data) and the date span must cover 1 to 120 monthly buckets.

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

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

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

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

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

Although the schema, annotations, and output schema are rich, the description itself fails to establish what the tool actually returns or when to prefer it over closely related SimilarWeb ranking tools. An agent gets the constraint details but not enough context to confidently select this tool among many similar siblings.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a useful constraint not present in the schema: start_date and end_date must span between 1 and 120 monthly buckets. This gives the agent actionable validation semantics beyond the individual field descriptions.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a note about the SimilarWeb v5 envelope (meta + data), which is useful for interpreting responses, but it does not disclose any other behavioral aspects like rate limits or authentication needs. The bar is lowered by annotations, so this is 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 extremely brief, but the first sentence is a redundant tautology ('Referrals.') that adds no value. The second sentence about the envelope is useful but does not compensate for the missing purpose. It is not front-loaded with actionable information and feels 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 tool with 10 parameters and an output schema, the description is inadequate. It does not explain what referrals are, how the data can be used, or any specifics about pagination (though offset exists in the schema). The output schema covers return values, but the tool's purpose and typical use cases remain unclear.

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

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

Schema description coverage is 100%, so all 10 parameters are individually documented. The description adds no additional parameter details, but the schema carries the burden effectively. Baseline of 3 is appropriate given high coverage.

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

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

The description 'Referrals' simply restates the tool name and title without specifying what the tool retrieves or how it differs from the many other get_similarweb_* tools. The only substantive statement, about the response envelope, concerns format rather than purpose, leaving the agent to infer the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 any of the sibling SimilarWeb tools, no context about referral traffic, and no mention of limitations or prerequisites. The agent must guess which tool is appropriate for a given 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 the safety profile with readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds one useful behavioral detail: the response follows the SimilarWeb v5 envelope (meta + data). However, it does not disclose other behavioral traits like pagination behavior, rate limits, or what 'aggregated' means relative to the timeseries sibling.

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

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

The description is very short, which is good, but the first sentence merely repeats the title and earns no place. The second sentence about the response envelope is useful and front-loaded, but overall the structure wastes the opening on a tautology.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the rich schema and annotations, the description does not state the core purpose of the tool, how it relates to get_similarweb_serp_players_timeseries, or what 'aggregated' means operationally. The output schema exists and reduces the need to explain return values, but the missing purpose and usage context leave the description incomplete for selection and invocation.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the input schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies. It does not clarify the format or semantics of keyword, dates, or limit beyond what the schema already provides.

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

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

The description is essentially a restatement of the tool's title: 'SERP Players - Aggregated.' It contains no verb and does not explicitly state that the tool retrieves aggregated SERP players for a keyword and date range. It also does not differentiate this tool from its sibling get_similarweb_serp_players_timeseries, relying entirely on the tool name.

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

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

The description provides no guidance on when to use this tool or when to prefer an alternative such as get_similarweb_serp_players_timeseries. There is no mention of use cases, exclusions, or trade-offs, so an agent must infer appropriate usage from the name and schema.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the envelope format ('SimilarWeb v5 envelope (meta + data)'), which is useful behavioral context beyond the annotations. However, it doesn't disclose pagination behavior, rate limits, or billing implications (though the limit parameter description covers billing). The description adds some value but not rich behavioral context.

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

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

Two sentences with no waste. The core resource and metric are front-loaded, and the envelope note is a useful addition. It could arguably include a hint about the time-series nature, but the title already covers that. Efficient and appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 output schema exists, so return values are covered. The annotations cover safety. The description covers the envelope format. However, for a time-series tool with 7 parameters, an agent might benefit from knowing how the data is shaped (e.g., one row per month per player) or how it differs from the aggregated sibling. The description is adequate but not complete for distinguishing from get_similarweb_serp_players_aggregated.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds no parameter-specific meaning beyond what the schema provides. The 'Clicks over time' phrasing implies the time-series nature of the data, which relates to start_date/end_date/granularity, but doesn't add syntax or format details. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description states a specific resource ('SERP Players') and metric ('Clicks over time'), which clearly distinguishes it from sibling tools like get_similarweb_serp_players_aggregated. However, it doesn't explicitly mention that this is a time-series variant, though the name and title convey that. The verb is implied ('get') rather than stated, but the resource and metric are clear.

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

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

The description provides no explicit when-to-use guidance or alternatives. The sibling list includes get_similarweb_serp_players_aggregated, which is the likely alternative, but the description doesn't mention it. The context of 'Clicks over time' implies a time-series use case, but an agent would have to infer when to choose this over the aggregated variant.

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

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

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

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

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

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

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

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

For a 10-parameter tool with a strict rolling date constraint and an output schema, the description thoroughly covers the one truly non-obvious behavior, gives an actionable example, and points to /describe for state that changes monthly. The schema covers parameter defaults/enums and the output schema covers return values, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value for the date parameters—concrete example, exact error codes, and rolling-window semantics—rather than repeating schema text. Other parameters are left to the schema, which is complete.

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

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

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

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

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

The description gives concrete date-usage guidance: request the three most recent completed months, and call the /describe endpoint to discover the exact currently-supported range. It does not discuss when to prefer this tool over sibling SimilarWeb tools, but the context is clear enough to prevent obvious misuse.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile and data volatility. The description adds the note that the response follows the SimilarWeb v5 envelope (meta + data), which is a useful behavioral detail about the response structure but not about side effects or call behavior. It does not mention pagination, rate limits, or any other operational aspects, but annotations carry the main burden. This is a minimal but acceptable contribution.

Agents need to know what a tool does to the 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 extremely short, but it is not well-structured. The first sentence 'Website Subdomains' is redundant with the tool name and title, wasting a sentence. The second sentence about the response envelope is useful but minimal. Overall it is concise in length but not optimally front-loaded; the redundant phrase dilutes the value. A tighter description would start with the envelope note and perhaps add a verb phrase. Score 3 reflects acceptable conciseness with a redundant element.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 10 parameters, 4 required, and a complex domain like SimilarWeb, the description is severely lacking. It provides almost no context beyond the schema: no mention of date format requirements (though schema has it), no explanation of the limit billing behavior, no coverage limitations (though schema mentions country coverage), and no typical use scenarios. The output schema exists, so return values are covered, but the description fails to help an agent understand when and how to use this tool effectively. It is not complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so every parameter (limit, domain, offset, country, end_date, start_date, web_source, granularity, traffic_source, main_domain_only) already has a description in the schema. The tool description adds nothing about parameters beyond the schema. The baseline is 3 because the schema does the heavy lifting, and the description does not compensate for any missing nuance.

Input schemas describe structure but not intent. Descriptions should explain 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 'Website Subdomains' is a noun phrase that merely echoes the tool name and title. It does not state a specific verb or resource, and it does not differentiate this tool from the many similar get_similarweb_* siblings. The only additional detail is about the response envelope, which is about output format, not the core purpose. An agent would have to infer from the name alone that this retrieves subdomains for a 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 guidance on when to use this tool versus alternatives like get_similarweb_similar_sites, get_similarweb_website_traffic_snapshot, or other SimilarWeb endpoints. No context is given about typical use cases, prerequisites (e.g., domain must exist in SimilarWeb), or conditions that would select this tool over siblings. The agent receives no help in choosing among the many get_similarweb_* tools.

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

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

The annotations already declare readOnlyHint, openWorld, idempotent, and non-destructive, and the description adds meaningful behavioral detail beyond them: the single-month date bucket, the latest-available-month requirement, country-dependent availability, and the specific error_code 101. This materially helps an agent anticipate failure and avoid invalid calls.

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

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

The description is compact and mostly dense with the critical date constraint explained efficiently. The opening phrase 'Website Technologies.' is redundant filler, but the remaining sentences earn their place by explaining the envelope and the non-obvious date behavior without unnecessary detail.

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

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

The output schema and annotations carry much of the burden, and the description covers the main hidden trap (date range). However, it never explicitly states what the returned technologies data actually represents, and it leaves tool-selection context entirely absent for an agent choosing among other SimilarWeb tools.

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

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

Schema description coverage is 100%, which provides a baseline of 3. The description goes beyond the schema by clarifying the relationship between start_date and end_date: they must be the same month, must be the latest available month, may differ by country, and invalid combinations return error_code 101. This is important semantic content the schema does not express.

Input schemas describe structure but not intent. Descriptions should explain 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 by repeating the title 'Website Technologies' but never states an action such as retrieves, lists, or returns the technologies used by a domain. It focuses almost entirely on the response envelope and date constraints, so an agent must infer the tool's purpose from its name rather than from the description.

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

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

The description gives no guidance on when to choose this tool over the many similar get_similarweb_* siblings, nor does it name an alternative. The date constraint is invocation-level guidance, not tool-selection guidance, so an agent deciding between this and similar tools gets no help.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small behavioral detail beyond annotations: 'Response follows the SimilarWeb v5 envelope (meta + data)'. This is useful but minimal, and does not address pagination, rate limits, or other behavioral traits.

Agents need to know what a tool does to the 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 extremely short, but 'Top Sites Ranking' is redundant with the title and earns no place. The envelope sentence is a useful detail but the overall structure wastes its limited space on repetition rather than conveying core purpose.

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

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

Despite strong annotations and a complete schema, the description leaves the tool's core purpose ambiguous and fails to differentiate it from similarly named siblings. An agent could not confidently decide when to call this tool over get_similarweb_ranking or similar tools. The output schema exists, but that does not compensate for missing operational context.

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

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

Schema description coverage is 100%, so the input schema fully documents all four parameters, including defaults and allowed values. The description adds no parameter-specific meaning, which matches the baseline of 3 when the schema carries the weight.

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

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

The description is essentially a restatement of the title: 'Top Sites Ranking' repeats the tool's name and title without an active verb or explicit resource. The only additional content is about the response envelope, which does not clarify what the tool does or how it differs from similar siblings like get_similarweb_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 no guidance on when to use this tool versus the many similarweb siblings, such as get_similarweb_ranking or get_similarweb_traffic_engagement. No context, exclusions, or alternative conditions are provided, leaving the agent to infer its place among the tools.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful behavioral context beyond that: the response follows the SimilarWeb v5 envelope and the date span must cover between 1 and 120 monthly buckets. These are concrete operational constraints an agent would need. It does not go into pagination or rate limits, but the output schema reduces the burden.

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

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

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

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

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

For a 9-parameter tool, the description provides one key operational constraint and the response envelope, and the input/output schemas cover parameter details and return structure. However, it does not differentiate this tool from closely related SimilarWeb siblings, leaving an agent to infer when this specific 'traffic & engagement' call is appropriate. It is minimally adequate but with clear contextual gaps.

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

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

Schema documentation covers 100% of parameters, so the baseline is 3, and the description adds meaningful semantic value to start_date and end_date by specifying the allowed 1–120 monthly-bucket span. This is beyond the schema's basic YYYY-MM format info, though no other parameters receive additional description-level clarification.

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

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

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

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

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

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

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

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

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

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

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

The description is two concise sentences with no filler. The core output and constraints are front-loaded, and every clause adds information: time period, row cap, fields, coverage, and parameter restriction.

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

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

For a low-complexity single-parameter tool with a rich output schema and strong annotations, the description is fully sufficient. It covers the relevant behavioral constraints and return-shape details without requiring an agent to open the schema or infer hidden limitations.

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

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

Schema coverage is 100% for the single required `domain` parameter, so the baseline is already covered. The description adds extra semantic value by clarifying that a country parameter is not accepted and that the fixed worldwide scope is part of the endpoint's behavior.

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

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

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

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

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

The description gives clear context for invocation: it returns country-level traffic share for the latest month and explicitly tells agents that a country parameter is not accepted, implying this tool is for worldwide breakdowns rather than country-filtered reports. It does not name a specific alternative tool, but the exclusion is clear enough.

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

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

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

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

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

The description is two sentences with no filler. The first sentence front-loads the core purpose and metrics; the second explains the automatic month selection and meta fields. Every phrase earns its place.

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

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

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

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

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

Schema coverage is 100%: both domain and country have descriptions, including the enum and default for country. The description adds no parameter-specific detail beyond what the schema already provides (e.g., it doesn't explain domain format or country restrictions beyond the schema). Baseline 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb ('get') and resource ('website traffic snapshot') and enumerates the exact metrics returned: visits, average visit duration, bounce rate, pages per visit. It is clearly distinguishable from sibling tools like get_similarweb_website_traffic_trend (trend) or get_similarweb_traffic_engagement (broader engagement) by the 'latest-month' qualifier and the single-object format.

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

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

The description implies usage for retrieving the most recent month's snapshot ('latest-month traffic snapshot') and notes that the month is auto-selected, but it does not explicitly contrast with alternatives or state when not to use it. The guidance is implicit rather than explicit, so a 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

Both parameters (domain and country) have full descriptions in the schema, covering their meaning and allowed values. The description text adds no additional semantic value beyond the schema, so the baseline of 3 for 100% schema coverage is appropriate.

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

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

The description clearly states the tool returns a monthly traffic time series for a domain, which is specific and unambiguous. It differentiates from snapshot-style tools by emphasizing the time-series nature, though it doesn't explicitly name sibling alternatives like get_similarweb_website_traffic_snapshot.

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

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

No guidance is given on when to use this tool versus the many similar Similarweb tools in the sibling list. There are no prerequisites, exclusions, or comparative use cases mentioned, leaving the agent to infer usage from the name alone.

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

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

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

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

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

The description is moderately detailed but every sentence adds useful information: output scope, cost/auth, sibling differentiation, and endpoint usage. It is slightly longer than strictly necessary but remains well-structured and front-loaded with the core purpose.

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

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

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

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

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

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

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

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

The description clearly states what the tool does: it presents the AIsa catalogue at a glance, including categories, servers, tool counts, and a dedicated category endpoint. It also distinguishes itself from search by explaining that the endpoint lists tools directly instead of via search.

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

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

The description provides clear usage context: use list_categories for a catalogue overview, and use the provided endpoint when you only need one category. It explicitly contrasts with search ('instead of via search') and notes tool-router has no equivalent, although it does not exhaustively cover all sibling alternatives.

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

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

The description adds critical behavioral context beyond the annotations: the shared AIsa workspace with no per-caller isolation, and the fact that omitted fields retain their current values. It also reinforces the destructive/mutating nature implied by the annotations. This is valuable, non-obvious context that an agent needs to anticipate side effects.

Agents need to know what a tool does to the 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 concise sentences, front-loaded with the purpose and scope. Every sentence contributes: purpose, partial-update semantics, stage field reference, and shared-workspace warning. No filler or redundancy.

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

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

Given the output schema and annotations, the description covers all essential aspects: what it does, how to use it (partial update), a key parameter dependency, and a side-effect warning about shared workspace. It is complete for an agent to invoke it correctly without additional 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?

Even though schema coverage is 100%, the description adds essential usage semantics: the partial-update behavior (omit fields to keep current value) directly informs which parameters to include. It also clarifies that the account_stage_id must be a valid id from get_apollo_account_stages, which is not in the schema. This goes beyond the bare field descriptions.

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

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

The description clearly states the action ('Update one account by its Apollo id') and distinguishes it from batch operations (post_apollo_accounts_bulk_update) and create (post_apollo_accounts). It is specific about the resource and the granularity (one account), leaving no ambiguity.

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

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

The description explains the partial-update usage (send only fields to change) and explicitly links the account_stage_id parameter to get_apollo_account_stages. It does not explicitly name alternative tools for multi-account updates or exclusions, but the single-account scope is clear. The guidance is adequate but could be more explicit about when to use bulk vs single.

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

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

The description warns that writes affect all callers in the shared 'AIsa workspace' and lack per-caller isolation, which is critical for a destructive write operation. Annotations already indicate destructiveHint=true, but the description adds specifics about visibility and sharing, going beyond 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 three sentences, each adding critical value: the operation scope, the partial-update guidance, and the shared-workspace warning. No filler, and the safety warning is front-loaded after the core purpose.

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

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

For a single-record update tool with many optional fields, the description covers the essential usage rules (partial update, stage id source, shared workspace) and output schema exists. The warnings about shared state are crucial and complete. Nothing critical is missing.

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

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

With 100% schema coverageaint but all parameters are simple strings; the description adds meaningful guidance especially for contact_stage_id, noting it expects an id from get_apollo_contact_stages. This clarifies the parameter's expected source, which the schema does not. Given high coverage, the baseline is 3, but the added stage-id guidance justifies a 5.

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

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

The title 'Update a Contact' and description 'Update one contact by its Apollo id' clearly state the specific verb (update), resource (contact), and target identifier (Apollo id). It distinguishes from siblings like post_apollo_contacts (create) and post_apollo_contacts_bulk_update (bulk).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructs to 'Send only the fields you intend to change' and notes the shared workspace side-effect, which clarifies when to use it. It doesn't explicitly mention alternatives for bulk updates or creation, but the sibling names (post_apollo_contacts, post_apollo_contacts_bulk_update) imply such options.

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