Generect Live API MCP Server

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), but the description adds non-obvious billing semantics: the call is free, a realtime count costs $0.02, and it is 'never run implicitly' — real behavioral context an agent could not infer from annotations alone. It stops short of noting latency for realtime counts or how cost is reported.

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

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

Three short sentences, front-loaded with what the tool returns and what it costs, with no filler. Every clause 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?

With an output schema present, return values need no explanation, and the description correctly focuses on the cost/credit model that the schema cannot express. Coverage is nearly complete; only the difference from sibling preview/count tools is left implicit.

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

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

Schema description coverage is 100% and the 23 parameters are richly documented (mode enums, per-field 'realtime only' cost warnings, deprecated fields), so the description's minimal parameter commentary is acceptable. The only added hint is cost-related, which is already implied by the mode field.

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 ('count companies matching an ICP') plus an adjacent deliverable ('what pulling them would cost'), which clearly separates it from search_companies (retrieval) and count_leads (a different 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?

Gives a strong explicit ordering directive ('Call this before search_companies') and implies the pre-flight-estimate use case, but never states when this tool is NOT the right choice or how it differs from preview_leads.

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

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

Annotations only declare readOnly/idempotent/openWorld; the description adds the decisive behavioral facts an agent cannot get elsewhere — this call never spends credits, the realtime count is a $0.02 flat charge, and the tool actively refuses to run one unless explicitly requested. That is exactly the kind of cost and gating context annotations do not 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?

Three sentences, front-loaded with the core question and the free/cost distinction, with zero filler. There is mild redundancy between 'FREE — this call never spends credits' and 'without paying per row', but the emphasis is justified for a cost-sensitive 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 36-parameter tool with full schema coverage and an output schema, the description supplies the missing decision layer: cost, free-ness, ordering relative to search_leads, and the realtime escalation cost. Filter semantics are correctly left to the schema, though the interaction with the sibling preview_leads is not addressed.

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

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

Schema description coverage is 100% and the mode parameter is already fully documented in the schema, including the auto/database/realtime tradeoffs. The description only reiterates the realtime gate ('unless you pass mode:"realtime" on purpose'), adding no syntax or format detail beyond structured fields, 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?

The first sentence names the exact question answered — how many leads match an ICP and what pulling them costs — which is a specific verb+resource and immediately distinguishes it from search_leads. An agent can tell what it produces 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?

Explicit sequencing directive: 'ALWAYS CALL THIS BEFORE search_leads', with the rationale (only way to size an audience without paying per row). It also states the exclusion condition — realtime is refused unless mode:"realtime" is passed on purpose — so both when-to-use and when-not-to-use 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 only declare readOnlyHint=false / destructiveHint=false / openWorldHint=true; the description goes well beyond them with pricing (~$0.0067 per record found, not-found refunded), the instruction to read cost.amount_charged, the realtime billing behavior, the 5–60s realtime latency, and the per-call spend ceiling refusal. That is exactly the extra behavioral 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?

Front-loads what the tool returns and what it accepts before the cost details; every sentence carries information. The long nested parentheses around pricing tiers make it denser than it needs to be, but nothing 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?

With an output schema present, return-shape explanation is unnecessary, and the description covers identity inputs, cost, and async/latency tradeoffs. The one gap is that 0 parameters are required but the description never says how many of them must be supplied or what happens if several conflicting identifiers are passed.

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 selection semantics the schema does not: relative identifier reliability (id > domain > fuzzy name) and the point that the compact summary carries the Generect id every later step accepts. The mode tradeoffs are largely already spelled out in the schema's mode description, so the added value is partial.

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

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

States a specific verb and resource with explicit scope: 'Full profile for ONE known company', which implicitly separates it from cohort search tools like search_companies. It also enumerates the accepted identifiers (Generect id, LinkedIn URL, domain, name). It stops short of naming the sibling an agent should use for discovery instead, so it is clear but not fully sibling-differentiated.

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 operational guidance: 'Domain is the most reliable identifier after id; name matching is fuzzy', and routes cost questions to get_balance. It does not state when to prefer a different tool (e.g. search_companies for discovering unknown companies, or enrich_lead for people), so the when-not-to-use half is absent.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond that with billing mechanics (BILLABLE, ~$0.0067 per found record, not-found refunded, Tier 0 list price caveat, cost.amount_charged in every response), the per-call spend ceiling that can refuse an escalation, escalation reporting, and realtime latency of 5-60s.

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 what the tool returns and its cost, then routing guidance. Dense parenthetical stacking (price caveat plus get_balance plus amount_charged all in one clause) costs some readability, but essentially every sentence carries actionable 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 format need not be explained, yet the description still tells the agent where to read actual spend. Combined with identifier choice, mode selection, billing, and bulk-tool routing, nothing needed to invoke this correctly or decide whether to invoke it is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds selection guidance the schema does not: it frames id/LinkedIn/email as interchangeable identifiers and states that `id` is the most accurate one, which is a cross-parameter preference rather than a restatement of the schema text.

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: 'Full profile for ONE known person, by Generect id, LinkedIn URL, or work email (reverse lookup).' The 'ONE' emphasis and the explicit 'For many people at once use start_bulk_job' cleanly separate it from the bulk sibling, and 'known person' separates it from search/preview 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?

Gives explicit routing rules: prefer the `id` from a search/preview result as the most accurate identifier, and use start_bulk_job for many people. It also explains when to pick each `mode` value, including the concrete case for choosing 'database' explicitly ('when a record from the last 12 months is good enough and cost matters more than freshness').

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: billable at ~$0.4 per hit, misses free, ~20x an email lookup, tiered pricing that may differ, and the cost.amount_charged field and get_balance route for real spend. This is exactly the cost/auth-style disclosure 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?

Front-loads the action and the cost warning, and every sentence carries useful information. The nested parentheticals about tiered pricing and cost.amount_charged make one sentence dense, but nothing is truly wasteful.

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 the safety profile and an output schema covering returns, the description still supplies the pricing, confirmation-before-calling, and alternative-tool context an agent needs. Nothing material is missing.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema (domain, lead_id, first/last name, linkedin_url, etc.). The description adds no parameter-level meaning, which is acceptable at full coverage but not value-adding.

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 ('Find a phone number for one person') and explicitly scopes it to a single individual, which separates it from bulk and email siblings. An agent can identify the operation immediately without reading 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 explicit when-to-use ('only for people they have already qualified'), when-not ('Do not call it speculatively or across a list'), and names the alternative for approved lists (start_bulk_job). Routing guidance is unambiguous.

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 beyond annotations by disclosing cost semantics (~$0.02 per VALID email, misses free), that pricing is tier/list-dependent with a pointer to get_balance, and that cost.amount_charged in each response is the ground truth. Also discloses the async-routing threshold behavior, which no annotation conveys.

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 purpose then billing then identifier modes, and every clause carries information. The stacked parentheticals around pricing ('(a miss is free) (Tier 0 list price; ...)') are dense and slightly hard to parse, costing a point on 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?

Output schema exists so return values need no explanation, and the description nonetheless covers pricing, every identifier mode, batch behavior, and async escalation. For an 8-parameter, 0-required tool this 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%, so baseline is 3, but the description adds real value by ranking identifiers ('lead_id (best)'), naming the three valid modes, and explaining the candidates batch threshold. It still doesn't reconcile the 0-required-parameter situation (exactly one mode must be chosen) at the top level beyond the identifier list.

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 and verify a work email') immediately, and the identifier/batch details make it clearly distinguishable from siblings like validate_email (which verifies an existing address) and find_phone. An agent can route here vs. elsewhere 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 explicit identifier preference ('lead_id (best), LinkedIn URL, or first+last+domain') and an explicit alternative path for batches over 10 ('routed to an async bulk job ... job_id for get_bulk_job'). It stops short of stating when NOT to use it (e.g., 'if you already have the address, use validate_email'), so it's strong but not fully 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, idempotentHint and openWorldHint, but the description adds non-obvious behavior: the call is free and never spends credits, grants are spent before balance but only on covered operations (a perk never pays for phone numbers), and balance_usd and grants_usd must not be summed. It also establishes authority — the returned prices override list prices in other tool descriptions.

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 purpose and the free-call guarantee are front-loaded, and each subsequent sentence carries non-obvious guidance (grant spending order, do not sum, when to call). It runs several sentences long for a getter and could be tightened, but no sentence is filler.

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

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

An output schema exists, so raw return values need not be enumerated, yet the description still explains the two headline figures and how to interpret them together — exactly the ambiguity an agent would hit. Combined with the free-call and pricing-authority notes, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents timeout_ms, include_usage, include_prices, include_transactions and include_token_analytics including defaults and free/paid status. The description adds no input-parameter detail beyond that, so the baseline 3 applies even though the output-field semantics it explains are valuable.

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 specific resources — account balance, month-to-date usage, and this account's real per-operation prices — with a clear verb framing. None of the siblings (search/enrich/count/bulk/webhook tools) overlap this function, so the agent can tell immediately what it retrieves and that it is a read-only account-status call.

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?

Timing is stated explicitly: call it before a batch of paid work to tell the user what they can afford, and after to report what was spent. This is a concrete when-to-use pattern with a stated purpose for each occasion, leaving nothing to inference for the agent's workflow.

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 beyond the readOnly/idempotent annotations with a materially important billing fact: the call is free, credits were already charged at submit time. That is exactly the kind of context an agent budgeting calls needs. It stops short of describing behavior when the job is still running or how failures surface.

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

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

Three short sentences, front-loaded with what the tool returns, then the cost reassurance, then the cadence rule. Nothing is redundant and 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?

An output schema exists, so return values need not be explained, and both required params are fully documented in the schema. The free/billing and polling-cadence context is the key missing piece from annotations, and it is present. Only the non-terminal job state behavior 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 coverage is 100% with descriptions on all three parameters, so the schema already carries the load. The description adds no parameter-level detail (e.g., timeout_ms tuning or job_type echoing rules), 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+resource (retrieves status and results of a bulk job) and pairs naturally with the start_bulk_job sibling referenced in the schema. It does not explicitly name the sibling it complements, but the polling/status framing 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?

Provides cadence guidance ("Poll every few seconds, not in a tight loop"), which is genuinely useful, but never states the trigger condition explicitly (call after start_bulk_job until a terminal state). Usage is implied rather than spelled out, and no alternatives 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing billability at ~$0.0067 per record, that not-found results are refunded, the Tier 0 list-price caveat, and that the agent should call get_balance and read cost.amount_charged for real spend. It also notes escalation is refused above a spend ceiling, giving the agent concrete cost and side-effect awareness.

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 two most decision-relevant facts (alias status, prefer enrich_lead) and packs billing details into a single dense parenthetical. It is efficient, though the nested pricing caveat is heavy enough that it slightly slows scanning.

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 an aliased enrichment tool with an output schema already present and 100% schema coverage, the description covers the remaining agent-critical gaps: identity as an alias, cost, refund behavior, and where to verify real pricing. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents url, mode, compact, and the deprecated no-op parameters in detail. The description adds little parameter-level meaning beyond pointing to enrich_lead and mentioning the mode escalation ceiling, so the baseline of 3 applies.

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

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

States a specific verb and resource (enrich a lead from a LinkedIn profile URL) and explicitly frames itself as an alias of enrich_lead kept for backwards compatibility. This makes its identity and its relationship to the sibling tool unambiguous without opening either schema.

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

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

Gives an explicit routing rule: 'Prefer enrich_lead — it also accepts a Generect id (cheaper to get right) or an email for reverse lookup.' It also names the alternative and the conditions under which the alternative wins, so the agent knows when NOT to call this tool.

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 safety is covered; the description adds genuinely new context: zero credit cost, no paid endpoint contact, and the default credential-verification side effect against /accounts/me. It stops short of stating behavior when the credential check fails, which is the main remaining 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 sentences, all front-loaded with the highest-value fact first (liveness, then free/cost, then what it checks). No filler or repetition 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?

With an output schema present, return format needn't be explained, and annotations cover the safety profile. The description supplies the cost profile, default behavior, and monitoring suitability that an agent needs to call it correctly.

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

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

Schema coverage is 100%, so both timeout_ms and check_credential are already documented in the schema. The description only echoes the opt-out nature of the credential check ('unless you disable it'), adding little beyond the structured fields — 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?

Opens with a specific verb+resource ('Liveness check') and enumerates exactly what it confirms: server up, version, credential validation. That scope is unmistakably distinct from every sibling, which are all data-fetching tools (enrich_*, search_*, get_balance).

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?

States a clear use context ('safe to call from a monitor') and a cost condition ('never spends credits'), which tells the agent when this is preferable to paid siblings. It does not explicitly name an alternative or state exclusions, but the separation from data tools is obvious from the 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), it discloses a genuinely useful behavioral fact — 'FREE — this call never spends credits' — and explains the register-once/event-wake workflow model. It does not discuss HMAC secret handling, auth/permission needs, or rate limits, but the destructiveHint already covers the delete risk.

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

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

Two tight sentences: the action/resource inventory is front-loaded, then the cost and workflow guidance. The 'FREE' callout is placed prominently and nothing is repeated or padded.

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 schema coverage is complete, so return values and per-action field requirements need not be restated. The description supplies the missing framing (cost model, intended workflow, purpose) needed to call this multi-action tool correctly.

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

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

Schema description coverage is 100%, so every parameter (id, url, action, events, secret, timeout_ms) is already documented in the schema. The description adds no syntax, format, or conditional-requirement detail beyond restating the action list, so the baseline of 3 applies.

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

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

The description names a precise set of actions (list, create, update, delete, test) on a specific resource (webhook endpoints) scoped to bulk-job completion events. No sibling tool touches webhooks, so an agent can immediately distinguish this from get_bulk_job or the bulk-job starters.

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 selection condition and names the alternative technique: 'Use this instead of long polling in scheduled/unattended workflows.' That routes the agent well, but it offers no 'when not to use' (e.g., interactive single-shot flows) and does not tie the five actions to any scenario 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?

Discloses cost behavior far beyond the annotations: billable at ~$0.002/row, per-row billing semantics, where the true price is found (get_balance and cost.amount_charged), and the masking contract (no LinkedIn URL, domain, email or phone). The readOnlyHint=false annotation is consistent with the billable framing, and the description adds substantial value on top of 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?

Front-loads the value proposition ('Cheap look at the actual people behind a count'), then the cost warning, then the workflow. Dense and mostly economical, though the nested parenthetical about get_balance and cost.amount_charged makes the second sentence long.

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-format details are not needed, and the description covers the essential extras: billing, masking, and the intended pipeline. It omits any mention of the spend cap / confirm_spend_usd approval flow, which is a meaningful behavioral gap for a tool that charges money.

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 41 parameters are already fully documented and the baseline is 3. The description adds little parameter-specific meaning beyond noting that preview rows carry an id (relevant to exclude_ids) and that cost is per returned row.

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 ('preview leads') and pinpoints the role it plays: a cheap look at the people behind a count before committing to a full search. This cleanly separates it from count_leads (no rows) and search_leads (full cost).

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 workflow: 'preview many → pick the few that fit → enrich_lead / generate_email only on those', naming the follow-on siblings. It also directs the agent to get_balance for real prices, which is actionable routing guidance rather than vague context.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is already partly carried. The description still goes well beyond them: per-row billing (~$0.0005, unresolved free), duplicate rows billed per row, cost.amount_charged in every response, and the hard 403 on numeric member ids. That is genuinely additive 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 core purpose is front-loaded in the first sentence and every sentence carries load. It is dense with parentheticals and repeats the billing/credits point, which costs a little readability, but nothing is 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?

Even though an output schema exists, the description usefully explains the return shape (resolved profile vs {input,error}, the interop `id`, `linkedin_id`, compact vs ~80-field raw). Combined with the billing and input-constraint coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents id/url/compact/profiles/timeout_ms. The description does add meaning (batch up to 50 in one call, one row per input, duplicates billed per row, and the critical negative constraint that the numeric member id is rejected), which is more than restating the schema, but it largely mirrors what the properties already say.

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

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

Specific verb+resource: 'Reveal who is behind an anonymous LinkedIn profile link.' It explicitly scopes what is returned (identity only, no location/company/work history) and names the sibling that covers the rest (enrich_lead), so an agent can separate it from enrich_lead, get_lead_by_url and find_phone 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?

Explicit routing: 'this is the cheap first step before spending on a full record' and 'use enrich_lead for those'. It also states operational prerequisites — deduplicate before batching, call get_balance for real prices — and names the downstream consumers (enrich_lead, generate_email, find_phone).

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?

Discloses far more than the annotations (readOnlyHint=false, destructiveHint=false): daily free row quota resetting at 00:00 UTC, ~$0.0067/row full pricing, list-price disclaimer, cost.amount_charged, the $5 spend ceiling with confirm_spend_usd, 429 behavior on spent quota, and the headcount_range snapshot-lag caveat. It stops short of describing pagination/response shape, but the billing and escalation semantics are unusually thorough.

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 the free-by-default economics, and every clause carries cost or routing information. It is dense with stacked parentheticals (Tier 0 list price, quota, escalation) that could be tightened, but nothing is wasted for a 30-parameter billed search.

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 it need not explain return values, and with 30 params and a dual billing model it still covers the essentials: free vs billable paths, escalation, spend ceiling, filter caveats, and deprecated no-op params. An agent has enough to call this correctly and safely.

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 baseline is 3, but the description adds cross-parameter meaning the schema doesn't: detail's free/thin vs billable/full escalation path and thin_unavailable marker, and that realtime-only filters force the pricier mode. The limit_by cost equation ('this number IS the price') is also supplied by the schema, so the added value is moderate rather than decisive.

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 ('Return companies matching an ICP') and immediately scopes itself against siblings ('Run count_companies first', 'use enrich_company on the ones you keep'). An agent can distinguish it from count_companies, enrich_company and search_leads without opening any schema.

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

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

Explicit routing to alternatives and conditions: run count_companies first, enrich_company/generate_email on rows you keep, pick 'database' when freshness matters less than cost, 'auto' escalates only on rejected filters. Both when-to-use and how-to-avoid-cost are stated.

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

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

Goes well beyond the annotations: free thin-row quota with a 00:00 UTC reset, per-row billing (~$0.0067 / Tier 0 list), automatic escalation to realtime, the spend ceiling, 429 on a spent quota, and the fact that rows never contain email or phone. Annotations only declare readOnlyHint=false/openWorldHint=true, so this prose is doing the real behavioral work.

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 cost model before any convenience guidance, and every sentence is operational rather than filler. It is a dense paragraph rather than a tight list, and the price/cost-verification advice is slightly repetitive, but nothing 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 43-parameter, billed search with nested company_filters and an output schema, the description covers the things an agent cannot infer: quota behavior, mode escalation billing, spend approval, pagination strategy, and which sibling tools to chain. Return-value details are left to the output schema, which is appropriate.

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 earns an extra point by explaining cross-parameter economics — 'limit_by is the price of the call' in practice, detail 'thin' guaranteeing $0, and exclude_ids as the reliable pagination handle. It does not attempt to restate the 40+ filter fields, which 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 opens with a specific verb+resource+scope: 'Return leads (people) matching an ICP.' It also implicitly distinguishes itself from siblings by telling the agent to run count_leads to size the audience and enrich_*/generate_email to expand rows, so an agent can tell which tool does the actual lead retrieval.

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

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

Explicit routing: 'Run count_leads first — it is free and sizes the audience', 'call generate_email ... or find_phone only on the ids you keep', and 'pass detail "thin" to guarantee $0'. It also gives the pagination alternative (exclude_ids over offset) and states when full detail is worth the cost.

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 (which only cover read/write and open-world character), it discloses billing behavior, that cost is RESERVED at submit time, and that the job keeps charging even if polling stops — critical non-obvious behavior for a paid async tool. It also explains the confirm_spend_usd approval gate, which the annotations do not cover.

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

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

Three tight sentences with no waste; the cost/commitment warning is front-loaded immediately after the core action, which is exactly where a costly side effect should appear.

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 narration, and the description still names the job_id and the follow-up tools. Billing, approval, and polling semantics are all covered for a 5-parameter asynchronous submission tool.

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

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

Schema coverage is 100%, so mode, items, job_type, timeout_ms and confirm_spend_usd are already documented in-schema. The description adds cost context around the spend approval but does not add format or semantics beyond the schema for any individual parameter, 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 and resource ('Submit up to 50 records for asynchronous processing') and its primary output ('get a job_id back'). It also contrasts itself with the single-record tool by referencing the shared per-record rate, so an agent can separate it from enrich_lead/find_phone siblings.

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

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

Gives a clear precondition ('Only submit a list the user has approved') and explicit next-step routing to 'get_bulk_job' or a webhook. It does not explicitly say when to prefer the single-record tool over batching, so it stops short of full when/when-not coverage.

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 and openWorldHint=true, but the description adds crucial behavioral context: the operation is billable at ~$0.005 per email, every submitted address is billed regardless of verdict, and cost.amount_charged in responses shows actual spend. This exceeds annotation coverage and informs the agent of cost implications.

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, followed by critical billing details and a usage warning. While the billing parenthetical is dense, every part provides actionable information; the structure is logical and efficient.

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 hints and an output schema present, the description needn't explain return values. It covers billing, usage exclusions, and cost-checking, leaving no significant gaps for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, fully documenting both parameters ('emails' and 'timeout_ms'). The description does not add any parameter-specific syntax or format details beyond the schema's own 'Each one is billed' note, so the baseline of 3 applies.

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

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

The description states a specific verb ('Check deliverability') and resource ('emails you already have'), clearly distinguishing this tool from siblings like generate_email by warning against validating addresses already verified by that tool. An agent can identify the tool's function 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?

It provides explicit when-to-use ('emails you already have') and when-not-to-use ('Never validate an address that generate_email just returned as valid'), plus a pointer to get_balance for pricing. This is comprehensive guidance for selection and invocation.

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