Aidenix

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

Goes well beyond the annotations: it explains the repeat-call behavior (a second call reports the contact already existed, consistent with idempotentHint=true), the downstream enforcement effect (contact analysis refuses excluded contacts, people lists omit them), the quota exemption, and a hard rate limit of 10 new records per account per day. These are operational facts an agent cannot infer from readOnlyHint/openWorldHint.

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

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

Front-loads the core action and condition, then layers safety, enforcement, cost, and limit information in short independent clauses. Every sentence carries distinct decision-relevant information; nothing is repeated from the schema or title.

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, no-output-schema tool, the description covers everything an agent needs: input flexibility, idempotency, enforcement consequences, cost model, rate cap, and the removal path. Nothing material is left to inference.

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

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

Schema coverage is 100% and the single parameter already documents that email, phone, or LinkedIn values are accepted and auto-detected. The description restates that same acceptance/detection behavior rather than adding format examples, normalization rules, or error cases, so it neither compensates nor detracts.

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 ('Record a person in this account's opt-out list') plus the triggering condition ('when they ask not to be contacted'). It also names the counterpart tool remove_opt_out, so an agent can distinguish it from the closest sibling 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 when-to-use ('when they ask not to be contacted'), explicit when-not-to-use ('not for bulk-marking a list'), the correct batching posture ('one at a time'), and the alternative for the inverse operation ('Use remove_opt_out to lift a record').

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 second sentence adds genuine value beyond the annotations by telling the agent how to render the result (hide technical metadata, use human-readable headings, preserve all user-facing fields). However, with readOnlyHint=false and openWorldHint=true, the description never discloses that the call may perform external research or incur latency/cost, nor whether results are persisted or regenerated on repeat calls (idempotentHint=false).

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, purpose front-loaded, no filler. The second sentence is an output-presentation rule rather than tool semantics, but it is short and actionable, so it 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?

An output schema exists, so return values needn't be spelled out, but for a non-read-only, open-world analysis tool with two undocumented parameters the definition is thin: no parameter formats, no ICP-profile prerequisite, no mention of cost or side effects, and no explicit routing to analyze_contacts. The presentation instruction partially compensates but leaves the invocation contract unclear.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. The critical ambiguity — whether 'contact' is an email, a person ID, a LinkedIn URL, or a name — is left entirely unexplained, and icp_profile_id is not mentioned at all, so an agent gets no guidance on when to supply 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 output ('Return a complete ... single-contact business-fit analysis and outreach drafts') and scopes it to one contact, which implicitly separates it from the plural analyze_contacts sibling. The phrase 'business-fit analysis' is somewhat abstract, but the deliverables (analysis plus outreach drafts) make the tool's job recognizable.

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

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

Usage is only implied by the singular 'single-contact' framing; there is no explicit statement such as 'use this for one contact, use analyze_contacts for batches', and no mention of prerequisites, cost, or whether an ICP profile is needed first. An agent can infer the routing from the sibling name but not from the description itself.

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 a non-read-only, open-world, non-idempotent, non-destructive operation, so the description's main contribution is the 500-contact cap and the notion of a 'named batch'. It omits important behavior for a non-idempotent submit: whether resubmitting duplicates work, whether analysis is async, and how the resulting batch is identified for later retrieval.

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 single sentence is front-loaded and free of filler, but it is under-specified rather than genuinely concise for a batch-submission tool with three parameters. Brevity here costs the agent information rather than saving it effort.

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?

There is no output schema and no annotation clarifying return shape, yet the description never indicates what the agent gets back (a batch id or handle) or how to follow up. For a non-idempotent, open-world submission tool with a fully undocumented parameter set, this leaves the agent without enough to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It covers 'contacts' (with a 500-item cap) and loosely implies 'name' via 'named batch', but says nothing about icp_profile_id — including what happens when it is left null, which is a defaulted optional parameter whose behavior is entirely undefined.

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 ('Submit') and resource ('contacts') and qualifies the operation as 'batch business-fit analysis', which implicitly separates it from the singular sibling analyze_contact. It stops short of naming the sibling or clarifying how the batch relates to get_batch/list_batches.

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: nothing says to prefer this over analyze_contact for single contacts, nor what to do after submitting (poll get_batch/get_analysis). The word 'batch' plus the 500 cap only weakly implies the usage context.

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

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

Beyond the annotations it discloses the key side effect: the new profile becomes the active one and therefore reweights every later score and generated email, which is exactly the consequence an agent needs before calling. It also discloses a dedup guard ('A recent profile for the same site is not rebuilt — the upstream reports it already exists'), which the idempotentHint=false annotation alone would not reveal.

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?

Information-dense with the purpose and the activation side effect front-loaded; every clause carries an instruction an agent could get wrong. It is a single long block, though, and the 'confirm with the user' rule is buried mid-paragraph rather than surfaced, which slightly hurts scanability.

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 tool with annotations and no output schema, the description covers purpose, prerequisites, alternatives, scoping, side effects and repeat-call behaviour. Nothing material an agent needs in order to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description nevertheless adds real disambiguation by stressing twice that the URL is the seller's own site rather than the prospect's, and by stating the downstream consequence of the site's copy. It does not add URL format or validation specifics, which is a minor residual 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 opens with a specific verb and resource ('Build the seller's ICP profile by reading their own website') and immediately enumerates what the profile captures (offer, value prop, roles, industries, pain points, proof points, tone). It is clearly distinguished from the read-only sibling by naming list_icp_profiles as the inspection alternative.

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 ('onboard a new account or after a repositioning'), explicit alternative ('use list_icp_profiles to see what is already there'), an explicit precondition ('confirm with the user before running it on a website they have not named'), and an explicit negative scoping rule ('The URL is the seller's own site, never the prospect's').

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, but the description adds substantive behavior: no phone numbers returned, opted-out people excluded entirely, addresses never synthesized from a name@domain template, no SMTP probing because domains are mostly catch-all, and per-address worth labels (company inbox, shared short address, former job, private mailbox). That is exactly the operational context an agent needs before trusting results.

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

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

The most decision-critical constraint (admin-only, do not offer for customer accounts) is front-loaded, and every paragraph carries payload. There is mild redundancy in the sibling routing, which is stated once early and restated later as "This is the roster layer," so it is dense and useful rather than perfectly tight.

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

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

There is no output schema, yet the description fully specifies what comes back — named team rows with role/grade/seniority/country/LinkedIn plus addresses annotated with their worth — and states the important negatives (no phones, opted-out excluded). For a read-only enrichment tool of this complexity, nothing consequential 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that top limits named rows while metrics still describe the whole team, and supplies a concrete roles usage pattern (founder,ceo to keep only cold-email responders). It does not add much beyond the schema for the contacts toggle, keeping it short of a 5.

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

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

The description opens with a specific verb+resource: "Get the people of a company and the addresses to reach them," then names the exact inputs (domain, LinkedIn slug, or name) and the exact output fields (name, role, grade, seniority, country, LinkedIn, labelled addresses). It also explicitly segments itself from siblings: company_signals profiles the ACCOUNT, person_signals explains ONE human, analyze_contact scores the deal. An agent can route correctly without opening any other schema.

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

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

It gives both when-to-use ("Use after company_signals, when the account is worth working") and when-not-to-use ("the upstream refuses this tool for customer accounts, so do not offer it as an option") with named alternatives in each case. It even routes to email_intel for the specific case where a single address must be trusted, and specifies roles=founder,ceo for cold-email targeting.

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, yet the description still adds real operational context: quota consumption per returned row, pagination via next_cursor, and the exclusion of the tool's own maker from team_uses counts. That is genuine value beyond the structured fields, though the exact consequences of exhausting quota are not spelled out.

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

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

Purpose is front-loaded and the workflow tail is well placed, but the description re-enumerates the filter list and repeats the per-company quota cost that the limit parameter already states. Two sentences duplicate structured data that the agent will read anyway.

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 no output schema, the description supplies the return shape (one row per company with the named fields), the cost model, the paging contract, and the downstream workflow. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns above that by explaining the semantics behind team_uses (internal tools derived from current employees' skills, minimum two users, maker excluded) and researching (buyer intent from recent reading), which the schema only names in passing. It does not add format or range guidance beyond what the filters property 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?

Opens with a specific verb and resource ("Find companies") and enumerates the qualifying dimensions, then explicitly scopes it as "without people," which cleanly separates it from person_search. An agent can distinguish this from every sibling 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 a concrete workflow: start with a small limit, page with next_cursor, then follow with person_search using the same filters or domains, or company_signals for a single account. Both the when-to-use and the named alternatives are stated outright.

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

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

Annotations already cover read-only/idempotent/non-destructive, yet the description adds genuinely new operational facts: one quota request per call, priced per account rather than per person, no per-contact repetition, ~20s latency for enrich, and that employee names are never exposed. It stops short of describing result size/pagination or failure modes, so it is strong but not exhaustive beyond the annotations.

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

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

Front-loaded with purpose and payoff, and the workflow guidance comes last where it belongs. It is dense and runs long with some repetition of what the schema already states and a couple of sprawling run-on sentences, but nearly every clause carries decision-relevant 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?

There is no output schema, so the description must carry the return-value burden, and it does: it enumerates the returned blocks, explains what relationships and enrich add, and states the privacy boundary on employee names. An agent has enough to call it correctly and know what comes back.

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 per-parameter descriptions restate nearly the same content as the main description (relationships expansion, enrich ~20s, company domain/name). The description adds the account-level pricing constraint around the call, but little parameter meaning that the schema does not already supply, 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 ('Profile a company') and then enumerates the concrete outputs: firmographics + revenue, team makeup, hiring velocity, activity signals, geo footprint, and a growth/reorg/stealth/stable verdict. It explicitly positions itself as account-level work before individual-level work, separating it from analyze_contact.

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 when-to-use routing: 'Call once per account for research and timing; then analyze_contact for the individuals.' It also scopes the optional flags with exclusions ('ask for it when you need warm entry paths, not for plain account research' and 'hot accounts only' for enrich).

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

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

Beyond the read-only and idempotent annotations, the description discloses quota cost, the two independent checks performed, and the fact that it catches stale-address failures that standard verifiers miss. It does not fully explain the returned fields, but the guidance about presenting recommended action and reason adds useful behavioral context.

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

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

The description is front-loaded with the core decision, then moves logically through what it answers, why it matters, cost, usage relative to a sibling, and output guidance. Every sentence earns its place and there is no filler.

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

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

For a three-parameter, read-only tool with no output schema, the description covers purpose, workflow placement, cost, and high-level return guidance. It could be slightly stronger on what the returned recommendation includes, but it is complete enough 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%, and the schema already documents the email, enrich, and deliverability parameters in detail. The description reinforces the two-layer model but does not add syntax, format, or flag-specific meaning beyond what the schema provides.

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

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

The description states a specific decision-oriented purpose: deciding whether an email address is worth contacting before drafting anything. It distinguishes itself from a named sibling, analyze_contact, and explains the distinct value of catching stale addresses that verifiers miss.

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

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

It gives explicit when-to-use guidance: run before analyze_contact when the address might be dead, and skip it on trusted contacts where it adds a redundant request. It also states the cost relative to an analysis, making the tradeoff concrete.

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 a safe, idempotent read, and the description goes well beyond them: it discloses the quota cost model ('one request of the user's quota per address'), the batching caps and their cause ('those layers are slow'), and the partial-result failure mode ('the rest is reported as skipped, not assessed'). The instruction not to present a truncated list as complete is exactly the kind of caveat 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?

The description is front-loaded with purpose, then caps, then cost, then reporting guidance — a sensible order with no filler sentences. It is somewhat dense and run-on in the quota/partial-result sentence, which could be split for scanability.

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 no output schema available, the description still tells the agent what comes back ('returned as a split by recommended action') and how to report it ('Present the counts and name the addresses not to send to'). Combined with the cap, quota and skip semantics, it covers everything needed to invoke and interpret this tool.

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

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

Schema description coverage is 100%, so the meanings of emails, enrich and deliverability are already documented, including the cap of 10 when either flag is on. The description reinforces the cap rationale ('those layers are slow') but adds no new per-parameter semantics such as address format, deduplication, or whether invalid entries are reported. 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 ('Assess a whole list of addresses in one call') and immediately distinguishes itself from the sibling email_intel by scoping to bulk ('Same two questions as email_intel ... answered per address'). An agent can route between the single and bulk variants without opening either schema.

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

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

Gives explicit when-to-use ('worth it on a cold list, not on a handful of contacts you already trust') and when-not, plus a hard operational boundary ('Up to 50 addresses per call, or 10 when deliverability or enrich is on ... split a longer list yourself'). It also names email_intel as the alternative for the single-address case.

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, idempotentHint=false, and openWorldHint=true, so the mutating, non-idempotent, external-facing nature is covered. The description contributes a genuinely useful behavioral fact — the link is "short-lived" — but never quantifies the expiry or says whether repeated calls mint new links.

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?

A single front-loaded sentence with no filler or repetition. It is efficient, though the terse phrasing leaves room for one more clarifying clause at little cost.

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 only two required parameters and no output schema, most structural burden is already carried by the schema, so the description needn't explain return values. However, for an open-world, non-idempotent tool it omits link lifetime and whether the returned URL is single-use, leaving a real 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 0%, so the description carries the full burden, and it only partially compensates: it explains file_format's two values (already enumerable from the schema) and hints that job_id must reference a completed batch. It adds no detail on job_id format or where to obtain 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?

The description names a specific verb ("Create") and resource ("export link") with format scope (CSV or JSON) and a precondition (completed batch). No sibling tool covers export, so differentiation is implicit, but an agent can still tell this apart from get_batch and list_batches from the wording 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?

"For a completed batch" implies the state prerequisite — the batch must be finished before exporting — but this is left implicit rather than stated as a rule. No alternatives or when-not-to-use conditions are named, and it doesn't tell the agent to call get_batch first to confirm completion.

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

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

The annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is fully covered. The description adds useful return-content detail (plan, quota, selected ICP, website label) but says nothing about authentication prerequisites, quota semantics, or what happens if no ICP has been selected.

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?

A single front-loaded sentence that names the returned fields immediately, with no filler. The trailing participial clause about the website label is slightly awkward and could have been phrased more directly.

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?

Placeholder.

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 baseline this scores 4. The clause about the profile website as a human-readable label describes output labeling rather than parameter meaning, and the empty schema leaves nothing further to disambiguate.

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?

Uses a specific verb ("Return") with a well-defined resource list: account plan, quota, and selected ICP. It is clearly a zero-argument account-scoped read, but it never distinguishes itself from siblings like list_icp_profiles, which an agent could plausibly reach for instead.

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

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

Usage is only implied: words like "authenticated" and "selected ICP" suggest this is the tool for reading the current account's own state rather than enumerating profiles. There is no explicit when-to-use statement and no named alternative such as list_icp_profiles or build_icp_profile.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds genuine value by disclosing output shaping (technical metadata hidden, human-readable headings, all user-facing fields preserved), but it omits the critical behavior for a polling tool: what is returned or raised when the job is not yet finished.

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?

One front-loaded sentence with the action first and the output-shaping behavior second; no filler. The semicolon-joined clauses are dense but each carries 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?

An output schema exists, so return structure need not be restated. Still, for a polling tool the description leaves two operationally important gaps: the state of an unfinished job and the provenance of job_id. Adequate but not complete.

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

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

The single parameter job_id has zero schema description coverage, so the description must carry its meaning and does not. It never explains whether job_id is the identifier returned by analyze_contact/analyze_contacts or how to obtain one, leaving the only input underspecified.

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: poll one business-fit analysis job and return its user-facing result. The subject matter ('business-fit analysis job') distinguishes it reasonably well from generic siblings like get_batch, though the relationship to get_batch/list_batches is never made explicit.

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

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

The word 'Poll' and the clause 'when finished' imply a repeated-call-until-complete pattern, which is useful implied guidance. However, there is no explicit statement of when to use this versus get_batch, no guidance on retry intervals, and no mention of where the required job_id comes from.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only that results are returned one page at a time and are optional, which is modest added context without explaining pagination termination, cursor behavior, or cost of large result pages.

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?

A single front-loaded sentence with no filler, appropriately sized for a simple getter. It is efficient, though the terseness is part of why the parameters go unexplained.

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 four parameters at 0% schema coverage and no output schema, the description should explain the pagination model and the progress-vs-results distinction. It only gestures at 'one page of results', leaving an agent unsure how to iterate pages or when results 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 0%, so the description must carry parameter meaning, but it only hints at paging ('one page of results'). It says nothing about cursor semantics, the result_limit default of 50, or what include_results actually toggles, leaving three of four parameters undocumented anywhere.

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 ... batch progress') plus the optional result page, which is clearly distinct from export_batch. However, it never contrasts itself with the sibling list_batches, so an agent must infer that this tool is for a single known job_id rather than enumeration.

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 or when-not-to-use guidance, and no routing to list_batches or export_batch. The only implied usage comes from the required job_id in the schema, which the description never mentions.

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 only that results include 'readable status and progress', which hints at return content but says nothing about pagination behavior implied by limit/cursor, result ordering, or what happens at end of pages.

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

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

It is a single short sentence with no wasted clauses, so it is concise. However, the brevity comes at the cost of specification, leaving the misleading 'by name' as the most prominent 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 paginated listing tool with an opaque cursor and a status filter, none of which the schema documents, the description is not complete enough to call it correctly. There is no output schema to fill the gap either, so return shape and paging semantics are entirely undocumented.

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

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

Schema description coverage is 0% for all three parameters, so the description carries the full burden and provides nothing about limit, cursor, or status. Worse, 'by name' points at a filter that does not exist while the real filter (status) and paging (limit/cursor) go unmentioned.

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 'List' and resource 'batch analyses' identify the operation, but the qualifier 'by name' has no corresponding parameter in the schema and misleads about what filtering is possible. No distinction is drawn from siblings such as get_batch or export_batch, so an agent cannot confidently separate listing from fetching a single 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?

There is no guidance on when to use this versus get_batch, export_batch, or get_analysis, all of which appear in the sibling list and touch the same resource. The reader must infer that this is the enumeration entry point from the verb 'List' 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?

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one useful piece of content context — results include which website is selected — but does not describe ordering, volume, or pagination for an open-world listing.

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?

A single front-loaded sentence with the core action first and the return detail second; nothing is padded. The only weakness is that the "by website and product description" clause is vague rather than value-adding.

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 no output schema and no parameters, the description carries the burden of explaining what comes back, and it only partially does so (profiles plus the selected website). It is adequate to call the tool but leaves the result shape underspecified for an agent planning downstream steps.

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 no parameter semantics burden and the baseline is 4. The description does not falsely imply required inputs, though its "by website and product description" wording slightly muddies the no-argument nature.

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 and resource ("List ICP profiles") that clearly separates it from the creation sibling build_icp_profile. However, the phrase "by website and product description" is ambiguous — it reads like a filtering dimension even though the tool takes no arguments, which could mislead an agent about scope.

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 mention of when not to use it, and no reference to alternatives such as build_icp_profile. Usage is only inferable from the verb "List" and the read-only annotations.

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, non-destructive, open-world, but the description adds genuinely non-obvious behavior: each returned person costs one request against the user's quota, an empty page is free, opted-out people are excluded, and emails are not SMTP-checked. These quota and data-quality disclosures go well beyond what structured fields provide.

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

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

The scope and return fields are front-loaded and nearly every sentence carries actionable information. It is dense — a long run-on paragraph enumerating return fields and filters — but not padded, as the enumeration maps directly to absent output schema.

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

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

For a complex tool with nested filters, 100% schema coverage, no output schema, and 17 siblings, the description closes every needed gap: what comes back per row, how cost/quota works, pagination mechanics, exclusion of opted-out people, and the email verification caveat. An agent has everything required to call and interpret it.

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

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

Schema coverage is 100%, so field-level docs already exist; the description still adds meaning by explaining AND-across-filters/OR-within-list semantics, the timing/intent filter concept, and that profiles accepts up to 100 URLs/emails and returns each row tagged with its `input`, skipping unknowns at no cost. This is real added value, though the per-field detail largely mirrors the schema.

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

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

The description opens with a specific verb+resource ("Find people") and immediately scopes it by role, company, timing, and contacts. It explicitly distinguishes itself from siblings (company_people for one company's team, person_signals for one human, email_intel for an address), so an agent can select it without opening other schemas.

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

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

It names alternatives with the exact condition that selects them ("This is the way IN from an account or a segment"), gives pagination strategy (start small to see the total, then page with next_cursor), and adds a downstream sequencing rule (run emails through email_intel_bulk before a send). When-to-use and when-not are both explicit.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description layers on non-obvious behavior well beyond them: quota consumption, that it resolves dead addresses to the current employer, the deliberate asymmetry where an email query returns no name or slug while a URL/slug query does, and the match_confidence / linked_profiles ambiguity path. That is exactly the operational context annotations cannot express.

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 identity thesis, then cost, then sibling routing, then output caveats — a sensible order. It is dense rather than padded, but a few clauses restate the same rule (the email-vs-URL privacy point is made twice) and could be tightened 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 single-parameter tool with no output schema, the description carries the full burden and does so: it enumerates the returned facets, discloses cost, explains identity resolution on dead addresses, and tells the agent how to report low-confidence matches. Nothing needed to call it or interpret results 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% for the single parameter, so the baseline would be 3, but the description adds meaning the schema does not: the input type changes the answer (email queries strip identity, URL/slug queries return the name because the caller already holds it). It also states the dead-address fallback behavior, which is genuine semantic value for the one parameter.

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

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

"Who a person is and what is going on with them" is followed by an explicit inventory of what comes back (role, grade, company, trajectory, published subjects, reading habits, self-reported status, verdict). It then positions itself against siblings by name — email_intel answers whether the ADDRESS is usable, analyze_contact scores the DEAL, this one says who the human is — so an agent can discriminate 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 both the trigger and an explicit exclusion: "reach for it when you need the human behind the address, not as a warm-up before analyze_contact." It names the two adjacent tools and states the division of labour, plus the cost condition (one quota request per contact) that governs whether to call it at all.

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?

Adds substantial context beyond the annotations: the opt-out list is shared across accounts, so removal is restricted by ownership, and the call reports one of three outcomes (lifted, never there, belongs to another account). This fills in the failure semantics that destructiveHint alone does not convey. It does not discuss irreversible side effects beyond removal itself, but that is a minor gap.

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 well-formed sentences, front-loaded with the action before the precondition and the outcome reporting. Slightly overlaps with the schema's parameter description but no sentence 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 single-parameter mutation with no output schema, the description covers purpose, precondition, and return outcomes — exactly the information an agent cannot get from structured 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?

Schema coverage is 100% and the schema already documents the single contact parameter, including accepted formats and the ownership restriction. The description adds only marginal scope framing, 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 ('Take a contact off this account's opt-out list') with explicit scope — this account's list, not the shared list. An agent can distinguish it from add_opt_out without opening either schema.

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

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

Gives concrete triggering conditions: a record added by mistake, or a person who asked to be contacted again, plus the hard precondition that only records this account created can be lifted. It does not explicitly name add_opt_out as the inverse operation, but the context is unambiguous.

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