AIsa Apollo

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

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

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

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

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped without losing information.

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

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

For a zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret it correctly is missing.

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

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

The tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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

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

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

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below a 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Explicitly sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already cover mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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

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

The description is dense and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better structured.

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

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

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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

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

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

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

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

The description gives explicit when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little ambiguity.

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

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the bar is lower; the description still adds two genuinely useful facts not in annotations: the master API key requirement and the per-request price. It stops short of 5 because it says nothing about rate limits or failure modes for a privileged read.

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 operative text is two front-loaded sentences with zero waste. The embedded pricing HTML block is boilerplate rather than explanatory content, which slightly dilutes an otherwise tight definition.

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

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

An output schema exists so return values need not be described, and the description covers auth and cost. What is missing is routing context against the many sibling account tools, which is the main gap for an agent deciding whether to call this one.

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

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

Schema description coverage is 100% with a single documented 'Account ID' parameter, so the schema already carries the semantics. The description only restates 'by ID' and adds no format, source, or lookup guidance beyond it.

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

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

States a specific verb and resource ('View an account by ID'), which clearly separates it from the write siblings like patch_apollo_accounts_account_id and post_apollo_accounts_search. It does not explicitly name an alternative, so it stops short of a 5.

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

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

The only guidance is the prerequisite 'Requires a master API key'. There is no indication of when to use this versus post_apollo_accounts_search or the other account-related siblings, and no exclusions or conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds the non-obvious 'Requires a master API key' constraint, which is genuinely useful behavioral context beyond the annotations, though it omits any rate-limit or pagination notes.

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

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

The functional content is front-loaded in one short sentence. The mandated pricing block inflates the text but is boilerplate inject rather than author prose, so it does not materially hurt structure.

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

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

With an output schema carrying return-value detail and no input parameters, the description only needs to cover purpose, auth, and scope. Purpose and auth are present; the one real gap is sibling differentiation, which is minor for such a simple read tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless schema is 4.

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

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

States a specific verb+resource ('List account stages'), so the operation is unambiguous. However, it does not distinguish itself from close siblings like get_apollo_contact_stages and get_apollo_opportunity_stages, leaving the agent to infer scope from the name alone.

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 explicit when-to-use guidance and no mention of alternatives, even though three near-identical stage-listing siblings exist. The agent must infer selection criteria from tool names.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new operational context the annotations do not: the master API key authorization requirement and the per-request cost of $0.012 for successful calls, both of which affect whether an agent should call it.

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 operative content is front-loaded in two short sentences with zero waste. The embedded pricing comment block is boilerplate policy noise rather than tool guidance, but it is clearly delimited and does not obscure the primary instruction.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile; the description supplies the missing auth and cost context. For a one-parameter lookup tool this is close to complete, with only the sibling-routing guidance absent.

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

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

There is a single required parameter (contact_id) documented at 100% schema coverage, so the schema carries the semantics. "by ID" merely restates the parameter in prose and adds no format, sourcing, or validation detail beyond the schema's "Contact ID" 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?

"View a contact by ID" states a specific verb and resource, and the identifier-based lookup is unambiguous. However, the title ("Update or View Contact") contradicts the read-only framing and the description never distinguishes this tool from the sibling patch_apollo_contacts_contact_id, which is the write path for the same resource.

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

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

The description implies the natural usage (direct lookup by a known ID) and states the master API key prerequisite, which is a real gate. But it gives no when-to-use/when-not guidance versus siblings such as post_apollo_contacts_search (find by criteria) or patch_apollo_contacts_contact_id (modify), so routing relies on inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one useful non-annotation fact (master API key requirement) and a pricing note, but nothing about rate limits, pagination, or scope of the returned stages.

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

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

The functional sentence is short and front-loaded, with the auth requirement immediately following. The injected pricing block adds bulk but is required boilerplate rather than author bloat.

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

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

An output schema exists, so return values need not be explained, and there are no parameters to document. The auth requirement is stated; the only real omission is disambiguation from the sibling stage-listing 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds nothing parameter-related, but none is needed since the schema is empty.

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+resource (list contact stages), so an agent knows what it retrieves. However, it does nothing to distinguish itself from the near-identical siblings get_apollo_account_stages and get_apollo_opportunity_stages, which is exactly the ambiguity that matters for selection here.

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?

"Requires a master API key" is a genuine precondition, which is more than many definitions offer. But there is no guidance on when to choose this over the account/opportunity stage siblings, nor any exclusion or context for use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds one piece of non-annotation context, the master API key requirement, but says nothing about pagination, filtering, or result scope. Modest added value beyond the structured hints.

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

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

The operative description is a single efficient sentence with the purpose front-loaded. The appended pricing comment block is injected boilerplate that adds length without aiding tool selection, which slightly dilutes the otherwise tight structure.

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

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

With an output schema present, return values need not be explained, and rich annotations cover the behavioral profile. For a zero-parameter read tool, stating purpose plus the auth requirement is sufficient, though a hint about result scope (e.g., all accounts vs. paged) would round it out.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter syntax or defaults are 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?

States a specific verb and resource: 'Get a list of email accounts.' An agent can immediately tell this is a read that lists email accounts. However, there are no sibling tools with overlapping naming (no other 'email_accounts' tool), so no explicit differentiation is offered or needed.

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 supplies a prerequisite ('Requires a master API key') but gives no when-to-use/when-not guidance and names no alternatives. Usage is only implied by the tool's name and the plural 'list' framing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description still adds two pieces of non-annotation context an agent needs: it requires a master API key, and it costs $0.012 per successful request, which affects invocation decisions.

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

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

The functional sentence is short and front-loaded, with the auth requirement following immediately. The embedded pricing comment block is boilerplate that consumes roughly half the text but is at least clearly demarcated.

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

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

An output schema exists, so return values need not be explained, and the single-parameter read operation is otherwise straightforward. Still, the description never characterizes the scope of 'stats' or positions the tool against its emailer siblings, leaving a gap for an agent choosing among many get_/post_ apollo 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% with a single, fully-documented 'id' parameter, so the baseline is 3. The phrase 'specific outreach email' adds only light framing and no format, source, or ID-resolution guidance beyond the schema.

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

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

States a specific verb+resource ('Check email stats for a specific outreach email'), which is clear enough to act on. It does not, however, differentiate itself from the sibling get_apollo_emailer_messages_search or explain what 'stats' actually covers, and the tool name's 'activities' is not reflected in 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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite several emailer-related siblings. The only conditional information is the auth prerequisite ('Requires a master API key').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description contributes the master-API-key auth requirement and a per-request price disclosure, which are real additions, but says nothing about pagination behavior, result caps, or ordering despite eight list/filter parameters.

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 short sentences, front-loaded, with the auth constraint stated immediately. The injected pricing comment block is boilerplate rather than substance, but it is clearly delimited and does not obscure 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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. Still, for an eight-filter search over a domain-specific resource, the description omits what the results represent, default paging behavior, and how to choose this tool over sibling campaign/message endpoints.

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 eight optional parameters (page, per_page, user_ids, emailer_campaign_ids, emailer_message_stats, not_emailer_campaign_ids, email_account_id_and_aliases, emailer_message_reply_classes) are already documented in the schema. The description adds no syntax, format, or combined-filter semantics beyond that, which is the expected baseline.

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

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

The description states a verb+resource ("Search for outreach emails"), but it largely restates the title and never clarifies what an "outreach email" is (emailer messages within a sequence) or how this differs from sibling search tools such as post_apollo_emailer_campaigns_search or get_apollo_emailer_messages_id_activities. Purpose is discernible but vague at the message-vs-campaign level.

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

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

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives among the many sibling search tools. The only contextual note is an authentication prerequisite ("Requires a master API key"), which is useful but is not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the master API key requirement, which is useful context, but it does not describe field scope, listing behavior, or how it differs from the sibling create/typed-field tools.

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 front-loaded in two short sentences, and the pricing block is boilerplate rather than explanation. It is appropriately sized overall, though the HTML pricing comment is noise for tool selection.

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

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

The tool is simple, has an output schema, and is covered by annotations, so the description is close to sufficient. However, it omits sibling routing and leaves the title's 'Create a Custom Field' claim unresolved, which could confuse an agent choosing between get_apollo_fields and post_apollo_fields.

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, so the schema already fully defines the call shape and no parameter semantics are needed. The baseline for a zero-parameter tool is 4; the description adds no parameter detail but does not need to compensate for any schema gap.

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

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

The description states a clear verb and resource: 'Get a list of fields.' It does not, however, distinguish this tool from siblings such as post_apollo_fields or get_apollo_typed_custom_fields. The title's '+ Create a Custom Field' also introduces ambiguity that the description itself does not resolve.

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 only guidance is the prerequisite 'Requires a master API key.' There is no explanation of when to use this tool versus siblings like post_apollo_fields for creation or get_apollo_typed_custom_fields for typed custom fields.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds a genuinely useful operational constraint not present in structured data: a master API key is required. It stops short of noting rate limits or result-size behavior, but for a read-only lookup this is solid 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 functional content is a single front-loaded sentence with the auth caveat immediately after, which is efficient. The injected pricing block adds length that does not help tool selection, though it is an appended artifact rather than authored prose.

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

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

With an output schema present, return values need not be described, and with zero parameters the schema burden is nil. Purpose plus the master-key requirement covers what an agent needs to invoke this correctly; only when-to-use routing to siblings is absent.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify beyond confirming the call is unfiltered. No syntax or format 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 names a concrete verb and resource ("Get a list of all lists (labels)") and the parenthetical disambiguates that 'labels' and 'lists' are the same object. It is clear enough to act on, though the phrasing is slightly circular and it never contrasts itself with any sibling tool.

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 call this versus alternatives; the only conditional statement is an auth prerequisite ("Requires a master API key"). The agent must infer the use case (discovering label/list IDs) entirely on its own.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds one genuinely useful non-annotation fact — a master API key is required — plus pricing context, but omits the behavioral trap that unfiltered calls fail with HTTP 400.

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 short, front-loaded sentences with no wasted prose; the auth requirement is stated immediately. The injected pricing comment block adds bulk but is boilerplate rather than authored content.

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

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

An output schema exists, so return values need no explanation, and the schema carries the filter requirement. Still, for a 10-parameter retrieval endpoint with several near-identical siblings, the description is thin — it never mentions filtering, pagination, or how it differs from neighboring search 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% across all 10 parameters, so the schema already documents each filter and the at-least-one-filter rule. The description contributes no parameter meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get a list of notes'), which is clear on its own. It does not, however, distinguish this tool from the many other Apollo list/retrieval siblings (e.g. get_apollo_emailer_messages_search, get_apollo_users_search), so an agent cannot tell from the text alone why it would pick this one.

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

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

There is no when-to-use guidance, no mention of alternatives, and no hint about the most important usage constraint: that at least one filter argument is required. The only guidance an agent gets is buried in the schema, not the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the master-API-key requirement, which is useful operational context beyond the annotations, but says nothing about rate limits, error behavior, or the fact that the title ('View or Update Deal') misleadingly suggests write capability.

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

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

The core purpose and auth requirement are front-loaded in a single tight sentence, which is good. The pricing boilerplate that follows does not help an agent select or invoke the tool and is mildly noisy, but it is delimited and clearly ancillary.

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 one-parameter read-by-ID tool with an output schema and full annotation coverage, the description supplies what the agent needs: what it fetches and the auth prerequisite. Return value details are correctly left to the output schema; only the routing vs. sibling tools is unaddressed.

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

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

Schema description coverage is 100% with a single opportunity_id parameter, so the baseline of 3 applies. The phrase 'by ID' in the description adds no format, encoding, or sourcing detail beyond what the schema already documents.

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: 'View a deal (opportunity) by ID,' which maps cleanly to the get_apollo_opportunities_opportunity_id name. It does not explicitly distinguish itself from get_apollo_opportunities_search or get_apollo_opportunities_opportunity_id's update sibling, but 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 provides the prerequisite 'Requires a master API key,' which tells the agent an auth condition must be met before calling. However, it gives no guidance on when to use this single-record fetch vs. get_apollo_opportunities_search or when to use the patch sibling for updating.

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 structurally. The description adds one genuinely useful behavioral fact — 'Requires a master API key' — which is an auth requirement not present in the annotations, but it discloses nothing about pagination behavior, result caps, or why the tool is named 'search' when it claims to return all deals.

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

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

The core sentence is short and front-loaded, but the injected aisa-pricing boilerplate roughly doubles the length with content irrelevant to tool selection. The description is not bloated by the author's own prose, but the effective payload carries dead weight.

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 rich annotations and an output schema present, the description does not need to explain return values, and it covers the auth requirement. However, for a 'search'-named list endpoint over deals, it omits any hint of scope (all deals in the workspace?), paging expectations, or filtering limits, leaving gaps an agent must discover by trial.

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 page, per_page, and sort_by_field are already documented in the schema. The description adds no paging or sort semantics of its own, 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?

States a specific verb and resource ('List all deals (opportunities)'), which distinguishes it from the single-deal sibling get_apollo_opportunities_opportunity_id and from the write sibling post_apollo_opportunities. It does not call out the 'search' nature implied by its name or name any alternative explicitly, so it stops short of a 5.

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

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

The description gives no when-to-use context, no prerequisites beyond the API key, and no routing to alternatives such as the opportunity-id getter or the account/contact search siblings. The agent must 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful piece of context — the master API key requirement — but says nothing about scope of the returned stage list or account/workspace dependency.

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

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

The functional sentence is front-loaded and wastes no words, but the embedded aisa-pricing block is boilerplate noise that adds length without helping tool selection.

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

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

With an output schema present, return values need not be described, annotations cover the safety semantics, and there are no parameters. Purpose plus the auth prerequisite is close to sufficient for a simple read-only list 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?

The tool takes zero parameters, so there is nothing for the description to document; the baseline for a parameterless tool applies.

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

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

States a specific verb and resource ('List deal stages') and disambiguates the term with the parenthetical '(opportunity stages)', which helps separate it from the nearby account/contact stage tools. It does not, however, explicitly distinguish itself from get_apollo_account_stages or get_apollo_contact_stages.

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 only guidance is the auth prerequisite ('Requires a master API key'). There is no statement of when to call this versus the sibling stage-listing tools or the opportunity search/get tools, so selection is left to inference.

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

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

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

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

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

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

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

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

Covers what it does, when to use it, its two alternatives, and the id hand-off to the detail sibling. With an output schema present, return values need not be documented, and nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the single-parameter contract and adds a caveat beyond the schema ('must be the bare domain (apple.com), not a full URL'), which sharpens the format requirement rather than merely restating it.

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

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

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

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

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

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

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds useful substance by contrasting the payload with enrichment ('everything enrichment returns plus the deeper fields') and by disclosing usage-based billing. It stops short of rate limits or quota behavior, but that is a minor gap against the annotation coverage.

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

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

The substantive content is two tight sentences with the id-first constraint front-loaded before the supporting detail. Only the auto-injected pricing block bulks it out, so the prose itself 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 return shape need not be re-explained, and annotations carry the safety profile. What remains — how to get the id, what extra fields to expect, and that domains are unsupported — is all supplied, so nothing needed for a correct call is missing.

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

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

Schema coverage is 100% and the single parameter is documented with an example, so the baseline is 3. The description goes further by clarifying the identifier's origin and warning that a domain will not work, which materially reduces the chance of a wrong-value call.

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

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

States a specific verb and resource — the complete Apollo record for one company — and immediately scopes it to being looked up by Apollo organization id rather than domain. That scoping distinguishes it cleanly from the enrichment and search siblings, so an agent can route without opening a schema.

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

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

Explicitly tells the agent how to obtain the required id (via get_apollo_organizations_enrich or post_apollo_mixed_companies_search) and states the exclusion plainly: 'this endpoint cannot take a domain.' Both the positive path and the anti-pattern are covered.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so page, per_page and organization_id are already documented in the schema; baseline is 3. The description adds a hint about where to source organization_id, though it points at get_apollo_organizations_enrich while the schema's own organization_id description says to use the Organization Search endpoint, a minor inconsistency rather than added clarity.

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

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

States a specific verb and resource ('Live job postings for one company, by Apollo organization id') and enumerates what each posting carries (title, location, posted date, source URL). An agent can distinguish this from sibling organization tools like get_apollo_organizations_id and get_apollo_organizations_enrich without opening a schema.

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

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

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

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: the master API key requirement and per-request pricing, which an agent would not learn from annotations or schema 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?

The authored content is two short, front-loaded sentences with no waste. The pricing block is boilerplate disclosure rather than tool prose, but it does consume roughly half the visible text.

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

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

An output schema exists, so return values need no explanation, and the schema fully documents all 12 optional filters. The gaps are the absence of any usage routing among the many search siblings and no note on pagination semantics, which matters for a 12-param search endpoint.

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

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

All 12 parameters have schema descriptions (100% coverage), including value formats like YYYY-MM-DD and seconds for durations, so the schema does the heavy lifting. The description adds nothing about parameter meaning, which is acceptable at this coverage level but offers no extra value.

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

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

"Search calls" gives a specific verb (search) and resource (phone calls), which distinguishes it from write siblings like post_apollo_phone_calls and put_apollo_phone_calls_id. However, it does not differentiate from other search siblings (e.g., get_apollo_emailer_messages_search, post_apollo_tasks_search) or clarify the scope of what is searchable.

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 only guidance is the prerequisite "Requires a master API key." There is no statement of when to use this tool versus alternatives, no exclusions, and no description of the searchable context (e.g., logged calls in the Apollo account).

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 safe-read profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description adds a genuinely useful constraint beyond annotations: the operation requires a master API key, which affects whether an agent can call it at all.

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 operative content is two short sentences with the purpose front-loaded and the auth prerequisite immediately after. The injected pricing comment block is boilerplate noise that pads the text but is not under the tool author's control.

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

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

For a zero-parameter read tool with an output schema (so return values need no explanation) and full annotation coverage, the description covers purpose and the key auth gate. It falls short only on clarifying what 'typed' means versus the sibling fields endpoint.

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

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

The tool takes zero parameters, which sets the baseline at 4 per the rubric, and the empty schema means there is no parameter semantics to compensate for. The description rightly spends no words on arguments.

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

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

States a specific verb and resource ('Get a list of all custom fields'), so the operation is unambiguous. However, it never distinguishes itself from close siblings such as get_apollo_fields or get_apollo_labels, and the 'typed' qualifier in the tool name is left unexplained.

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 get_apollo_fields or the other field/label endpoints. The only clause present ('Requires a master API key') is a prerequisite, not a usage condition or alternative comparison.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description does add one genuinely useful behavioral fact — the master API key authorization requirement — but says nothing about pagination defaults, rate limits, or result size, and an output schema exists so return shape is already covered.

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

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

The tool-authored sentence is one line and front-loads the verb and the auth requirement. That said, the majority of the visible description text is an injected pricing block rather than content that helps an agent select or call the tool.

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

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

For a simple 2-optional-parameter, read-only listing tool with an output schema and full annotation coverage, a short description is defensible. Still missing are any statement of what objects are returned, whether filters are supported, and how pagination terminates — gaps that matter given the crowded sibling namespace.

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

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

Schema description coverage is 100%: both 'page' and 'per_page' are documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies — the schema carries the full 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 verb+resource ('Get a list of users') is stated, but it is generic and gives no sense of what a 'user' is in this API or how this differs from the ~30 sibling search endpoints (contacts, accounts, opportunities). Despite the name ending in '_search', the description never mentions searching, filtering, or querying, so an agent cannot tell how it is distinguished from the other list-style 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?

'Requires a master API key' is a prerequisite, not usage guidance. There is no statement of when to call this versus the many sibling search tools, no exclusion conditions, and no mention of pagination strategy or result scope.

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

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

Annotations already establish that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only annotations.

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

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

The description is front-loaded with what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content context.

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

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

With zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

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

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

The tool has zero parameters, so parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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

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

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

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

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

It gives a clear alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description contributes the master-API-key auth requirement and pricing note, but omits important behavior for a PATCH: that unspecified fields are left untouched, and any error/partial-failure semantics.

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, front-loaded with the core action and then the auth requirement, with no redundancy. The injected pricing block adds length but is boilerplate rather than authorial padding.

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 and annotations cover destructiveness, so those need not be restated. Still, for a mutation endpoint with a nested custom-fields object, the description never explains PATCH partial-update behavior or that typed_custom_fields requires pre-fetched field IDs, leaving meaningful operational 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?

Top-level schema coverage is 50% (account_id and body), and the description adds no parameter context. However, the nested body properties are documented exhaustively in the schema itself (name, phone, domain, owner_id, raw_address, account_stage_id, typed_custom_fields), so the schema carries the load and a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Update fields on an existing account') with clear scope (PATCH semantics implied by 'fields'). However, it does not differentiate from near-siblings such as post_apollo_accounts_bulk_update, post_apollo_accounts_update_owners, or patch_apollo_contacts_contact_id, leaving the agent to infer the distinction from names alone.

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?

Adds one concrete prerequisite, 'Requires a master API key,' which is genuine selection context. But it gives no when-to-use vs when-not guidance and no pointer to the bulk-update or update-owners siblings, so routing relies on inference from the tool name.

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

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

The description says 'View a contact by ID', implying a read, while annotations declare readOnlyHint=false and destructiveHint=true. This directly contradicts the structured safety signal. The one useful addition is the master API key requirement, but the contradiction dominates.

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

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

The functional description is a single terse sentence that mischaracterizes the tool, and it is padded with a multi-line pricing boilerplate block that is irrelevant to selecting or invoking the tool. The valuable content (auth requirement) is buried after the core claim.

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 destructive PATCH tool with a nested update payload and a required body, the description never explains that it mutates a contact, what fields are updatable, or that `label_names` overwrites existing lists. An output schema exists so return values need not be explained, but the mutation semantics are absent.

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

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

Schema description coverage is 50% and the tool has a nested `body` object with a required but undocumented top-level shape. The description contributes nothing about `contact_id` or the update payload, so it fails to compensate for the coverage gap.

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

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

The description says only 'View a contact by ID', but the tool is a PATCH endpoint whose required `body` object contains update fields (email, title, name, labels, etc.) and whose title is 'Update or View Contact'. The description captures the read half and omits the mutation half, which is the primary operation, making it misleading rather than merely 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?

No guidance on when to use this tool versus the obvious read sibling `get_apollo_contacts_contact_id`, or versus the bulk update tools like `post_apollo_contacts_bulk_update`. The only condition stated is 'Requires a master API key', which is an auth note, not usage guidance.

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

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

The annotations declare readOnlyHint=false and destructiveHint=true, but the description says 'View a deal', implying a read-only operation. This contradicts the mutation/destructive nature of the tool and omits what fields are updated, whether changes are reversible, or what gets destroyed.

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-loads a functional statement, but that statement is the wrong operation for the tool and is followed by pricing boilerplate rather than necessary update guidance.

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

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

For a destructive PATCH tool with annotations, nested body parameters, and a required body object, the description is critically incomplete. It omits update semantics entirely and instead describes a read operation, leaving an agent unable to safely invoke the tool from the description alone.

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

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

Schema coverage is 50%, and the description adds almost no parameter meaning beyond 'by ID'. It does not explain the required body object or any of the update fields, leaving the schema to carry most of 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 names a resource and ID lookup ('View a deal (opportunity) by ID'), but the tool is a PATCH update tool. It gives the wrong core verb and fails to distinguish itself from the GET sibling get_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?

It only states an authentication prerequisite ('Requires a master API key') and provides no guidance on when to use this PATCH tool versus the GET tool or other update endpoints. The only usage signal it gives is misleading because it frames the operation as viewing rather than updating.

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 safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description still adds genuinely non-annotation context: the master-API-key requirement and the duplicate-domain rejection rule. It omits failure behavior and does not restate anything the annotations already cover, but adds no more.

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 front-loaded sentences: action, constraint, prerequisite. The pricing block is boilerplate but separate and ignorable. No wasted text in the substantive portion.

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

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

Output schema exists, so return values need no explanation, and the nested schema fully documents inputs. What remains for the description—auth requirement and domain constraint—is covered, leaving only failure modes unstated for a destructive create.

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 top-level `body` param carries no description (reported coverage 0%), but the nested body schema documents each field extensively (name, domain, owner_id, account_stage_id, typed_custom_fields), so the schema itself carries parameter semantics. The description contributes only the domain-uniqueness constraint, adding marginal value beyond the schema; baseline 3 fits.

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

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

States a specific verb+resource ('Create a new account') in the first sentence, and the singular 'an account' distinguishes it from post_apollo_accounts_bulk_create and from patch_apollo_accounts_account_id. An agent can place it correctly without opening any schema.

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

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

The description supplies prerequisites ('Requires a master API key') and a hard constraint ('Duplicate domains are not allowed'), which implies the create use case, but it never names an alternative such as bulk create or the patch endpoint, nor states when not to call it. Usage is implied rather than guided.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the write/safety profile is covered. The description adds two genuinely useful non-schema facts — the master API key requirement and per-request pricing — but says nothing about partial-failure behavior, duplicate handling, or the all-or-nothing nature of a batch mutation.

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 front-loaded sentences carry the core action and the auth prerequisite with no wasted prose. The embedded pricing marker block is boilerplate noise but is clearly delineated and does not bury the substance.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still missing for a destructive batch mutation: the 100-item limit, whether validation failures abort the whole batch, and what a duplicate match returns — all of which the agent needs before invoking.

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

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

The description mentions no parameters at all; its only structured reference is the word "bulk". Reported schema description coverage is 0% at the top level, and the highest-leverage parameter semantics (run_dedupe behavior, the 100-account cap, append_label_names applying to ALL accounts) live only in the nested schema, leaving the description to compensate and it does not.

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 gives a specific verb+resource ("Bulk create accounts"), and "bulk" implicitly distinguishes it from the singular post_apollo_accounts and from post_apollo_accounts_bulk_update. It never names those siblings explicitly, so differentiation is inferable rather than stated.

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

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

The only usage-relevant statement is the prerequisite "Requires a master API key". There is no guidance on when to prefer this over post_apollo_accounts (single create), bulk_update, or how to decide on dedupe behavior, and no exclusions or failure conditions 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description does add one genuinely useful non-annotation fact — the master API key requirement — but says nothing about what is overwritten, whether partial updates are possible, or the semantics of async processing beyond what the schema states.

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 authored content is two short, front-loaded sentences with no filler. The injected aisa-pricing block adds length but is machine-appended boilerplate rather than authorial verbosity, so it is only a minor deduction.

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

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

An output schema exists, so return values need not be described, and annotations cover the destructive/idempotency profile. What is missing for a nested-object mutation is the two-mode usage model and any guidance on selecting between uniform and per-account updates, which an agent cannot infer from the wrapper schema alone.

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

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

Schema description coverage is reported at 0% for the single top-level 'body' parameter, so the description carries the burden and does not meet it. It never explains the critical account_ids vs account_attributes duality, the async constraint, or the per-account versus uniform-update distinction that determines how the call must be shaped.

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

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

States a specific verb+resource (bulk update accounts) and the 'bulk' qualifier correctly scopes it against the single-record sibling patch_apollo_accounts_account_id. It does not, however, explicitly name or distinguish itself from post_apollo_accounts_bulk_create, post_apollo_accounts_update_owners, or post_apollo_contacts_bulk_update, which share the same bulk-mutation pattern.

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 only guidance is 'Requires a master API key.' There is no statement of when to use this versus the single-record PATCH, the bulk_create, or the update_owners/update_stages variants, and no mention that two mutually exclusive update modes exist inside the body.

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, destructiveHint=false, and openWorldHint, so safety is covered. The description adds two genuinely non-annotated traits: the master API key auth requirement and a per-request cost ($0.012 per successful request), which an agent weighing cost/credentials needs. It stops short of 5 because it says nothing about result volume or pagination behavior.

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

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

Two short sentences, purpose front-loaded, no filler. The embedded pricing comment block is boilerplate but is at least clearly delimited and does not obscure the purpose line.

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

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

An output schema exists so return values need not be explained, and the nested schema covers all filters and pagination. Against that real complexity (seven filter/sort parameters on a nested body), the description is thin: it never summarizes that this is a filtered/paginated list search or how it relates to the parallel contact and mixed-company search endpoints.

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

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

The description contributes zero parameter meaning, and the top-level 'body' parameter has no description (0% coverage by the stated metric), so per the rubric the description should compensate but does not. In practice the nested body properties are documented thoroughly with examples and enum semantics, which keeps this at the baseline 3 rather than lower.

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 gives a clear verb+resource ('Search for accounts'), which an agent can distinguish from the sibling create/patch account tools and from get_apollo_accounts_id. However, it offers no differentiation against the other search endpoints (post_apollo_contacts_search, post_apollo_mixed_companies_search), so it stops short of a 5.

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

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

The only guidance is a prerequisite ('Requires a master API key'), which is auth information rather than a when-to-use statement. Nothing tells the agent when to prefer this over get_apollo_accounts_id, post_apollo_mixed_companies_search, or the create/patch siblings, and there are no 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond the structured fields: it requires a master API key, an auth escalation the agent would not otherwise know about. It stops short of saying whether existing owners are replaced or how partial failures are handled.

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

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

The functional content is two tightly written sentences, front-loaded with the action and followed by the prerequisite. The injected pricing block consumes more words than the actual description, though it is machine-generated boilerplate rather than authorial bloat.

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

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

An output schema exists, so return values need no explanation, and the master API key requirement is a useful addition. However, for a destructive, non-idempotent bulk mutation, the description gives no indication of overwrite semantics or partial-success behavior, leaving 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% with only two self-documenting parameters (owner_id, account_ids), so the schema carries the load. The description adds no syntax, format, or cardinality guidance beyond what the schema already states, making 3 the correct baseline.

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

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

The description states a specific verb and resource (update account owner) and adds the scope qualifier 'for multiple accounts', which distinguishes it from the single-record sibling patch_apollo_accounts_account_id. It does not, however, contrast itself against the other near-identical bulk siblings such as post_apollo_accounts_bulk_update or post_apollo_contacts_update_owners.

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 explicit when-to-use guidance, no named alternatives, and no exclusions. The 'multiple accounts' phrasing only weakly implies this is the batch variant; an agent must infer from the name which of several bulk-account tools applies.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the master API key authentication requirement, which is genuine value beyond the annotations. It does not, however, warn that creating without dedupe can produce duplicates -- that risk is only disclosed inside the run_dedupe property description in the schema, not here.

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 prose is a single front-loaded sentence followed by the auth prerequisite -- no wasted words. The trailing pricing HTML comment block is boilerplate noise that adds length without helping an agent invoke the tool, which keeps this from a 5.

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

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

An output schema exists, so return-value explanation is not owed. Still, for a destructive, non-idempotent write tool the description omits the duplicate-creation caveat and any pointer to the bulk or update alternatives, leaving behavioral context thinner than the tool's complexity warrants.

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

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

The description contributes no parameter information at all; the wrapper 'body' parameter is undocumented in the description. The reported 0% coverage is largely an artifact of only counting top-level parameters, since the 17 nested properties carry rich descriptions and examples (notably run_dedupe). Net effect: the schema does all the work and the description adds nothing, so a middle score is appropriate.

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

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

The description states a specific verb and resource: 'Create a new contact.' An agent immediately knows this creates one contact record. However, it does nothing to distinguish itself from close siblings such as post_apollo_contacts_bulk_create (creating many) or patch_apollo_contacts_contact_id (updating an existing one), so the agent must infer the distinction from the names alone.

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 only guidance is the prerequisite 'Requires a master API key,' which is useful but not a usage condition. There is no statement of when to use this tool versus bulk_create, the search endpoints, or patch for updates. No alternatives or exclusions are named.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a genuinely useful non-annotation fact - the master API key requirement - but is silent on the 100-contact cap, dedupe/merge semantics, and partial-failure behavior for a destructive bulk write.

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 functional sentences, front-loaded with the purpose, with no wasted prose. The injected pricing comment block consumes structure without helping tool selection, which is the only blemish on an otherwise tight definition.

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

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

An output schema exists, so return values need no explanation, and annotations cover the destructive/idempotency profile. Still missing for a destructive batch mutation are the max batch size, what happens on duplicate matches, and whether validation failures are partial or atomic.

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

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

Schema description coverage is 0% at the parameter level, so the description would normally need to compensate, and it says nothing about the body. The nested schema is nevertheless exhaustive - every contact field, owner_id, run_dedupe, and append_label_names carry their own descriptions - so effective semantics are already available. Baseline 3 reflects a description that adds nothing over the schema.

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

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

The description states a specific verb and resource ('Bulk create contacts'), and the 'bulk' qualifier cleanly separates it from the single-record sibling post_apollo_contacts. It never names that alternative, so the agent must still infer the boundary, which keeps this from a 5.

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

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

No guidance on when to use bulk create versus post_apollo_contacts, post_apollo_contacts_bulk_update, or the dedupe-aware path. The one prerequisite given ('Requires a master API key') is an auth condition rather than selection guidance, so the agent gets no routing help beyond the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds a genuinely useful auth requirement ('Requires a master API key') that annotations omit, but it says nothing about overwrite semantics, whether omitted fields are preserved, or the >100-contact async threshold.

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

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

The functional sentence is short and front-loaded with the verb and resource. The injected pricing block adds length but is a mandated boilerplate element rather than authorial bloat, so the core text earns its place.

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

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

For a destructive bulk mutation with a deeply nested, two-mode request body, the description is bare. The output schema removes the need to document return values and the annotations carry the safety profile, but routing between the bulk and single-contact siblings and clarifying the two mutually exclusive update modes are still 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?

Top-level schema coverage is 0% (the single 'body' wrapper is undocumented), but its nested properties are exhaustively described with examples, so the schema does most of the heavy lifting. The description contributes nothing about the anyOf union — that contact_ids applies identical values to many contacts while contact_attributes applies individual updates — which is the key semantic an agent needs.

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?

'Bulk update contacts' names a specific verb and resource, and the word 'bulk' implicitly separates it from the single-record sibling patch_apollo_contacts_contact_id. It does not, however, explicitly name an alternative or contrast itself with post_apollo_contacts_bulk_create, so an agent must infer the distinction.

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 only conditional statement is 'Requires a master API key', which is a prerequisite rather than usage guidance. Nothing says when to prefer this over patch_apollo_contacts_contact_id, post_apollo_contacts_bulk_create, or post_apollo_contacts_update_owners, nor when to choose uniform updates vs per-contact updates.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds two genuinely useful non-schema facts, the master API key requirement and the per-request price, but says nothing about result volume, rate limits, or account scoping. Given annotations carry most of the burden, 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 core content is two tight sentences with the purpose front-loaded. The pricing block is injected boilerplate rather than authored prose, but it is fenced and does not bury the actual intent.

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

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

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. What is still missing is routing against the numerous sibling search tools and any hint about the nested body structure, which for a nested-object, open-world search endpoint leaves meaningful gaps.

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

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

Schema description coverage is reported at 0% for the top-level required parameter 'body', and the description says nothing at all about how to shape the body. Although the nested properties carry their own descriptions in the schema, the description contributes zero additional meaning about pagination, keyword search, sorting, or label/stage filters, so it fails to compensate for the coverage gap.

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

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

The description names a clear verb and resource ('Search for contacts'), so the basic purpose is legible. However, it gives no differentiation from the many sibling contact/search tools (e.g. get_apollo_contacts_contact_id, post_apollo_mixed_people_api_search), leaving the agent to guess which is appropriate. This lands at the minimum-viable level rather than a specific, distinguishing statement.

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?

Only 'Requires a master API key' is offered, which is a prerequisite rather than guidance on when to use this tool versus alternatives. Nothing tells the agent when this search is preferred over the mixed-people or bulk-match siblings, and there are no exclusions or context cues.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds a real behavioral fact in the master API key requirement, but it never explains the destructive effect itself — that existing owner assignments are overwritten — which is the key unknown for an agent calling a destructive bulk mutation.

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

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

The functional sentence and the auth requirement are front-loaded in two short sentences with no redundancy. The injected pricing block is mandated boilerplate rather than authorial waste, but it does dilute the signal slightly.

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 safety and an output schema covering the response, the definition is broadly serviceable. It is still thin for a destructive bulk mutation: no guidance on partial failure, batch limits, or what happens to the previous owner.

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

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

Schema coverage is 100% and both parameters carry descriptions, so the schema fully documents owner_id and contact_ids. The description contributes no additional parameter meaning (no ID format, no batch size ceiling, no behavior for invalid IDs), 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?

States a specific verb+resource+scope: reassigning a contact owner across multiple contacts, which implicitly separates it from the single-record patch_apollo_contacts_contact_id and from post_apollo_contacts_update_stages. It does not explicitly name those siblings, so differentiation is inferred from the 'multiple contacts' scope rather than stated.

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

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

The prerequisite 'Requires a master API key' is a genuine usage constraint that helps an agent decide whether the call is even possible. However, there is no indication of when to prefer this bulk tool over the single-contact patch, nor any exclusion or limit guidance for the contact_ids set.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is covered structurally. The description adds one genuinely useful behavior beyond them — the master API key requirement — but says nothing about reversibility, what happens to existing stage assignments, or partial-failure behavior on a batch.

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

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

The core sentence is front-loaded and wastes no words. The appended pricing block is templated boilerplate that does not aid tool selection, but it is clearly delimited and does not obscure the 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?

With an output schema present, return values need no explanation, and the annotations carry the safety profile, so the description is close to sufficient. It still omits the one thing an agent would want for a destructive batch mutation: whether the change is reversible and how many contacts can be submitted per call.

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

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

Schema description coverage is 100% and both parameters are required, so contact_ids and contact_stage_id are already documented in the schema. The description adds no format, cardinality, or batching-limit detail beyond what the schema states, making the baseline 3 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 states a specific verb and resource plainly: 'Update contact stage for multiple contacts', which is unambiguous and clearly a bulk stage mutation. It does not, however, distinguish itself from adjacent siblings such as post_apollo_contacts_bulk_update or patch_apollo_contacts_contact_id, so the agent must infer the difference from the name alone.

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?

Other than the requirement of a master API key, there is no when-to-use guidance, no exclusions, and no routing to alternatives like the single-contact patch or the generic bulk update. 'For multiple contacts' implies the batch case but stops short of telling the agent when this tool is the right pick.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation/safety profile is covered structurally. The description adds the auth requirement (master API key) and pricing, which is real context, but it never explains the consequence of the destructive hint (e.g., contacts entering an outbound sequence) that the annotations imply.

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

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

The functional sentence is front-loaded and waste-free, and the auth requirement follows immediately. The embedded pricing comment block is boilerplate noise but is clearly demarcated and does not obscure the core instruction.

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

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

With a full output schema and 100% parameter coverage, return values and inputs are covered, so the remaining burden is behavioral. For a destructive 11-parameter mutation the description is minimally adequate: it names the auth requirement but omits consequences, conflict conditions with the remove/stop sibling, and how the several 'allow contacts with...' flags interact.

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 11 parameters including contact_ids/label_names alternation are documented in the schema itself. The description adds nothing about parameter semantics, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Add contacts to a sequence'), which an agent can map directly to the operation. It does not, however, differentiate itself from the closely named sibling post_apollo_emailer_campaigns_remove_or_stop_contact_ids or explain the contact/label ambiguity that the schema raises.

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

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

There is no when-to-use guidance, no conditions distinguishing adding from removing/stopping contacts, and no note on prerequisites beyond 'Requires a master API key.' The agent is left to infer when this tool is the correct choice vs. siblings like the remove/stop variant or sequence approve/abort.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the genuinely useful auth constraint (master API key), but is silent on the behavioral consequences of each mode — removing vs stopping vs marking finished — for a bulk destructive operation, which is exactly the context an agent needs.

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 operative text is two short sentences and the auth constraint comes early. The injected pricing block is platform boilerplate rather than the author's prose, so it only marginally dilutes an otherwise tight definition.

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

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

An output schema exists so return values need no explanation, but for a destructive bulk mutation with three semantically distinct modes the description leaves the mode effects, scope of impact, and failure behavior entirely unexplained. The definition is too thin for the operation's risk level.

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

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

Schema description coverage is 100%, so all three parameters (mode, contact_ids, emailer_campaign_ids) are documented in the schema. The description adds no semantics beyond that, 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?

"Update contact status in a sequence" is essentially a restatement of the title with a different arrangement of the same words. It does not clarify that the tool removes/stops/marks contacts in one or more sequences, nor does it distinguish it from the sibling post_apollo_emailer_campaigns_add_contact_ids. Only the tool name carries the real distinguishing information.

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 only guidance is a prerequisite ("Requires a master API key"); there is no statement of when to prefer this tool over add_contact_ids, nor which of the three modes to choose for a given outcome. The agent must infer the entire decision from the schema's mode list.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description adds a genuinely useful non-annotation detail, the master-API-key authentication requirement. It still does not describe pagination behaviour or result limits, which the annotations do not cover either.

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 front-loaded sentences with zero filler; purpose comes first, then the auth prerequisite. The injected pricing block is boilerplate noise relative to tool selection but does not bury the operative information.

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

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

With an output schema, full parameter coverage in the schema, and annotations carrying the safety profile, the description needs only purpose and prerequisites, both of which it supplies. A note on paging across the page/per_page pair is the only obvious missing piece.

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

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

Schema description coverage is 100% for all three parameters (page, q_name, per_page), so the schema already carries the semantics. The description adds no syntax, defaults, or guidance about paging or keyword matching, so baseline 3 applies.

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

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

States a specific verb (Search) and resource (sequences / emailer campaigns), and resolves the naming ambiguity created by the 'post_' prefix by making clear this is a read-style lookup. It does not name a sibling to differentiate from, though the parenthetical alias quietly separates it from get_apollo_emailer_messages_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?

"In your Apollo account" plus "Requires a master API key" gives the prerequisite and a general context, but there is no explicit when-to-use guidance or named alternative for searching messages rather than sequences. The agent must infer the boundary from the resource 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds the master-API-key authentication requirement, which is real value beyond the annotations, but says nothing about what deactivation actually does to in-flight sequences, enrolled contacts, or how abort differs from archive.

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 substantive content is two short front-loaded sentences with no padding around the action. The injected pricing block is boilerplate that consumes space without aiding tool selection, keeping it below a 5.

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

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

With an output schema present and annotations carrying the safety profile, the description only owes the agent the action and its prerequisites, both of which are present. It falls short of complete because the distinction between deactivating, archiving, and stopping (remove_or_stop_contact_ids) is left for the agent to guess.

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

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

Schema description coverage is 100% for the single sequence_id parameter, so the baseline is 3. The description adds no format, sourcing, or semantics for the ID beyond what the schema already states.

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

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

States a specific verb ("Deactivate") and resource ("a sequence"), so the action itself is unambiguous. It does not, however, distinguish itself from the close siblings post_apollo_emailer_campaigns_sequence_id_archive or ..._approve, which an agent reads as adjacent lifecycle operations on the same sequence.

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 when-to-use guidance, no when-not-to-use, and no routing to alternatives such as archive vs abort vs approve. The only actionable instruction is the credential prerequisite ("Requires a master API key"), which is a gate rather than usage guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered externally. The description's one real addition is 'Requires a master API key' — a genuine auth prerequisite not in the annotations. It says nothing about reversibility or what activation does to in-flight contacts.

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

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

The functional content is two tight sentences with the auth caveat front-loaded alongside the action. The pricing boilerplate is non-behavioral but is clearly delimited as a comment block.

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

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

An output schema exists, so return values need not be explained, and annotations carry the destructive/idempotency profile. What is missing is guidance on irreversible activation, which matters for a destructive, non-idempotent mutation.

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

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

Schema description coverage is 100% with a single parameter, so the baseline is 3. The description adds no format or sourcing detail for sequence_id beyond the schema's 'Sequence ID.'

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

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

States a specific verb+resource ('Activate a sequence'), which is much clearer than the name's opaque 'approve' segment. However, it does not differentiate from close siblings like _abort and _archive, so an agent must infer the distinction.

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 no when-to-use guidance and names no alternatives, despite siblings _abort and _archive being obvious confusable options for an emailer campaign sequence. The agent gets no routing 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 destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: what archiving does to the sequence and its contacts, the master-key auth requirement, and per-request cost. It does not cover reversibility or timing, but given the annotation coverage this is a strong disclosure.

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

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

The operative content is two tight sentences, front-loaded with the action and its effect. The pricing block is boilerplate but is short, clearly delimited, and carries genuine cost information.

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

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

For a destructive single-parameter call with an output schema, the description covers the effect, auth requirement, and cost, so an agent has enough to invoke it correctly. It stops short of stating whether the change is reversible or how in-flight sends are handled.

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?

Only one parameter (sequence_id) and schema description coverage is 100%, so the schema already carries the parameter meaning. The description adds nothing about the identifier beyond what is structured, which is the expected baseline here.

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

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

Specific verb ('Archive') and resource ('a sequence'), plus a clarifying gloss of what archiving does ('marks it inactive and finishes contacts'). That effect does implicitly distinguish it from the abort sibling, but no sibling is named, so it falls short of full differentiation.

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

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

Gives an important prerequisite ('Requires a master API key') and describes the outcome, which implies when this is appropriate. However, it never states when to choose archive over the closely related abort or approve endpoints, leaving the agent to infer the distinction.

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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, but the description says only "Get a list of fields," implying a read. This contradicts the annotations and hides the destructive write nature. The only useful extra is the master API key requirement.

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 real sentences are terse, but a large auto-generated pricing block occupies much of the text and conveys nothing about tool selection or behavior. The minimal information present is also front-loaded around the wrong (read) action.

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

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

Although an output schema exists (so return values need not be described), the definition is incomplete for a destructive write tool: it never states it creates a custom field, never covers the required body parameters, and its stated action conflicts with the annotations.

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

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

Schema description coverage is 0% at the top level and the description mentions no parameters at all. It adds nothing about the nested body fields (type, label, modality, meta) that drive field creation.

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 only says "Get a list of fields," but the tool name (post_), the title ("Get a List of Fields + Create a Custom Field"), and the body schema with type/label/modality all indicate the primary action is creating a custom field. The description omits the create function entirely and is therefore partial/misleading about what the tool does.

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

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

No when-to-use, when-not, or alternative guidance is given. Siblings get_apollo_fields and get_apollo_typed_custom_fields appear to be the pure read routes, yet the description does not distinguish this mutating tool from them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuine value beyond them: the dual organizations/accounts return shape, the echoed pagination/breadcrumbs, and a cost signal ($0.01975 estimated request). It stops short of noting rate limits or result caps, so it is strong but not exhaustive.

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

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

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

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

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

For a 24-parameter, zero-required, open-world search with 100% schema coverage and an output schema, the description supplies everything an agent needs: what it searches, what comes back, and when to prefer the cheaper alternative. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all 24 parameters, making 3 the baseline. The description names broad filter categories (headcount, funding stage, technologies) that map onto schema properties but adds no syntax or format detail the schema does not already provide.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With an output schema present and full annotation coverage, the description still supplies everything an agent needs to call it correctly: auth requirement, credit behavior, pagination ceiling, and enrichment alternatives. Nothing material is missing.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Dense, front-loaded, and every sentence carries a distinct instruction: required param, how to resolve it, available filters, return fields, and use case. No filler or restatement of the tool name.

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

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

Output schema exists, so return values need not be explained, and the annotations cover the safety profile. Given the description covers the required parameter, its error behavior, the prerequisite chain, filter options, and a use case, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top: it flags organization_ids as required and explains why (and how to obtain values), and gives category examples (funding, hires, launches) plus the date-range and paging parameters as a coherent filtering story. Some overlap with schema text, but the required-param rationale is genuine added value.

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the mutation profile is covered. The description adds the auth requirement (master API key), which annotations do not convey, but says nothing about creation side effects, duplicate handling, or required related entities.

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 short sentences, front-loaded with the action and followed by the key precondition, with no wasted prose. The injected pricing comment block is boilerplate noise rather than description content.

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

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

A mutation tool with a required nested body object and no annotation-level detail about creation semantics; an output schema exists so return values need not be explained. The description covers only the action and auth, leaving the agent to infer prerequisite IDs and creation behavior entirely from the nested schema.

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

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

Top-level schema description coverage is 0% (the single 'body' parameter is undescribed), and the description contributes no parameter meaning at all. The nested body properties are in fact richly documented in the schema, which limits the damage, but the description itself does nothing to compensate for the coverage gap.

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

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

The description states a specific verb and resource ('Create a deal (opportunity)') and usefully disambiguates the API's 'opportunity' terminology as a 'deal'. It does not differentiate itself from siblings like patch_apollo_opportunities or get_apollo_opportunities_search, but the create action is unmistakable.

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

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

The only guidance is an authentication prerequisite ('Requires a master API key'), which is a precondition rather than a when-to-use rule. There is no mention of when to create a deal versus updating one, or of what pre-existing entities (stage, account, owner) must be resolved first.

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

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

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

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

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

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

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