Generect Live API MCP Server

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the bar for adding behavioral context is lower. The description adds valuable cost transparency beyond annotations: 'FREE — this call never spends credits' and 'a realtime count costs $0.02 and is never run implicitly'. This is useful, non-obvious behavior that helps the agent make cost-aware decisions.

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

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

Two sentences with zero filler. The first sentence front-loads the core purpose and cost, the second adds the free guarantee, and the third gives the ordering guidance. Every clause earns its place; no redundant phrasing.

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

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

Given the output schema exists and the input schema is fully documented, the description needs only to cover the non-schema context. It covers the critical decision factors: cost (free vs $0.02), the recommended call order, and the fact that realtime is never implicit. This is complete for an agent to correctly choose and invoke the 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 input schema already documents all 23 parameters with rich detail (including which ones force realtime mode). The description itself adds no parameter-level semantics beyond the schema, so the baseline of 3 is appropriate. No additional parameter meaning is provided.

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

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

The description states a specific verb and resource: 'How many companies match an ICP', clearly distinguishing it from search_companies (which would return records) and count_leads (which counts leads). The first sentence also adds the unique value of 'what pulling them would cost', making the tool's role 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?

Explicitly gives the primary use case: 'Call this before search_companies', which is clear and actionable. It also references count_leads as a sibling for cost behavior, but does not explicitly state when to prefer count_leads over this tool or vice versa. The ordering guidance is strong, and cost implications are mentioned, so this is above average but not a full 5.

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 and idempotentHint, but the description adds substantial behavioral context beyond those: the free cost guarantee, the cost estimate return, the realtime mode's refusal unless explicitly requested, and the known exclude_names bug in database mode (though that is in a parameter description, it signals the description cares about edge behavior). No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and cost statement, then expands into usage guidance. It is a few sentences long but every clause earns its place—no filler. The structure is effective for the tool's complexity, though it could be tightened slightly 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?

Given the tool has an output schema (so return format is already specified) and a rich input schema, the description covers all the essential usage context: when to call, what it returns (count + cost estimate), the free/paid distinction, and the realtime caveat. For a 36-parameter tool, this is more than sufficient; an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The tool description does not add meaning to individual parameters beyond what the schema provides—its focus is on the tool-level cost and mode semantics. Per the rubric, high schema coverage yields a baseline of 3; the description adds no extra param-level insight to warrant higher.

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 clear verb-resource-scope statement ('How many leads match an ICP, and what pulling them would cost') and immediately distinguishes itself from the sibling search_leads by stating it is the only free way to learn audience size. The 'FREE — this call never spends credits' line leaves no ambiguity about what the tool does and how it differs from alternatives.

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

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

Explicitly instructs when to use this tool ('ALWAYS CALL THIS BEFORE search_leads'), explains why (learn audience size without paying per row), and describes the alternative (search_leads). It also clarifies the conditional realtime mode and its non-free cost, giving the agent precise decision criteria.

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 readOnlyHint/openWorldHint annotations, the description discloses billability, approximate per-record cost, refund behavior for not-found records, the existence of different account rates, and the pointer to get_balance for real pricing. It also surfaces the database-vs-realtime mode behavior and cost differences via parameter context, adding substantial behavioral insight.

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 dense, purposeful sentences: the first front-loads the core purpose and inputs, the second packs billing and reliability guidance without filler. Every clause carries decision-relevant information for an agent.

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

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

The rich schema, annotations, and output schema cover parameter details and return structure. The description completes the picture with purpose, billing, and identifier reliability. A minor gap is that it never explicitly states that at least one identifier must be provided, though that is strongly implied by the phrasing.

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

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

The input schema already has 100% parameter description coverage, so the baseline is 3. The description adds extra semantic value by ranking identifier reliability (domain after id), noting that name matching is fuzzy, and explaining cost implications per lookup. This goes beyond simply restating schema fields.

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 'Full profile for ONE known company', naming the exact verb, resource, and accepted identifiers (Generect id, LinkedIn URL, domain, or name). This clearly distinguishes it from sibling list/search tools like search_companies or count_companies by emphasizing a single known company rather than discovery or aggregation.

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

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

The description gives clear context: this tool is for enriching one already-known company, and it offers identifier reliability guidance ('Domain is the most reliable identifier after id; name matching is fuzzy'). It doesn't explicitly name alternative tools or state when not to use this tool, but the single-record enrichment context is strong enough for selection.

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

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

Annotations provide readOnlyHint=true and openWorldHint=true, covering safety and external data scope. The description adds valuable behavioral context: billing details ($0.0067 per found record, not-found refunded), cost guidance (call get_balance, read cost.amount_charged), and the 'prefer id' accuracy note. It does not disclose potential latency for realtime mode (that's in the schema) or failure behavior, but the cost disclosure goes beyond annotations and meaningfully informs the agent.

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 purpose in the first sentence, then cost, then guidance. It is efficient with no filler—every sentence adds functional information. It is slightly longer than necessary due to the billing detail, but that detail is decision-relevant. Structure is logical: purpose → cost → identifier preference → bulk alternative. A 5 would require even tighter phrasing without losing the cost nuance, but this is well above average.

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

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

Given the tool has 6 parameters, an output schema, and rich annotations, the description covers the essential context: single-person scope, identifier options, cost behavior, and the bulk alternative. It does not describe the response format, but the presence of an output schema covers that. It also does not explicitly mention the mode escalation behavior (only in the schema), but that is adequately captured in parameter descriptions. For an agent to call this correctly, the description plus schema provides sufficient guidance, with minor gaps in distinguishing from closely related tools like resolve_profile.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented (id, mode, email, compact, timeout_ms, linkedin_url). The description adds the 'prefer id' recommendation and clarifies email is for reverse lookup, but these are marginal additions over the schema. The baseline of 3 is appropriate because the schema carries the primary semantic weight and the description does not need to compensate for missing parameter info.

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

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

The description states a clear verb ('enrich') and resource ('one known person') with three precise identifier types (Generect id, LinkedIn URL, work email). It explicitly differentiates from bulk operations by naming start_bulk_job as the alternative for many people, and its phrasing 'Full profile for ONE known person' contrasts with search/preview tools. Purpose is unmistakable and distinct from 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?

The description gives explicit when-to-use guidance: for a single known person, and when not to use it ('For many people at once use start_bulk_job'). It also advises preferring the id from search/preview for accuracy. It does not enumerate every sibling alternative (e.g., get_lead_by_url, resolve_profile) but the context of 'known person' and the named bulk fallback provide solid direction. A minor gap: it does not explain when to choose this over resolve_profile or get_lead_by_url, but the identifier focus covers most use cases.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: it is billable with specific cost ($0.4 per phone found), a miss is free, it is roughly 20x an email lookup, and it is not to be used speculatively. It also instructs reading cost.amount_charged in every response, adding operational detail not covered by annotations. No contradiction with annotations.

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

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

The description is efficiently structured and front-loaded: it starts with the core purpose, then the cost and usage warnings, and finally the alternative. Every sentence provides actionable information—cost, comparison, and constraints—with zero fluff. It is appropriately sized for a tool with significant cost and misuse risk.

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

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

Given the tool has an output schema (mentioned in signals) and complete parameter documentation, the description is thorough. It covers purpose, cost, when to use, and when not to use, and directs to get_balance for pricing and to start_bulk_job for approved lists. The only potential gap—return format—is covered by the output schema. Nothing essential is missing for an agent to call it correctly.

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

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

The input schema covers all 7 parameters with full descriptions (100% coverage), so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides; it only mentions high-level usage context. It does not, for example, explain which parameter combinations are preferred, though the schema descriptions already cover that. Thus, the description adds marginal value over the schema.

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

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

The description clearly states the tool's purpose: 'Find a phone number for one person.' It uses a specific verb ('Find') and resource ('phone number'), and distinguishes itself from siblings by explicitly noting it is the 'MOST EXPENSIVE OPERATION HERE' and comparing cost to email lookup. This makes it unambiguous what the tool does and how it differs from alternatives.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Do not call it speculatively or across a list; confirm with the user first, and only for people they have already qualified. Use start_bulk_job for an approved list.' It also directs users to call get_balance for real pricing and to check cost.amount_charged, giving clear decision criteria for selecting this tool versus bulk alternatives.

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

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

With readOnlyHint=true and openWorldHint=true already provided, the description adds significant behavioral context: the billing model ('about $0.02 per VALID email found (a miss is free)'), price variance by account, the presence of cost.amount_charged in responses, and the async routing for >10 candidates. These details go beyond annotations and help an agent anticipate costs and asynchronous behavior. It does not describe error cases or rate limits, but the annotations cover the safety profile.

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 purpose, then covers cost, identification modes, and batch behavior in a logical order. Each sentence serves a distinct purpose; the cost information is detailed but relevant for a billable tool. It is slightly longer than strictly necessary, 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?

The description covers the essential operational aspects: cost, identifier modes, batch behavior, and async fallback. Since an output schema exists, it doesn't need to explain return values, and it does mention cost.amount_charged as a response field. It could add prerequisites or error handling, but for a read-only lookup tool with annotations and an output schema, this is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explicitly listing the allowed identifier modes ('lead_id (best), LinkedIn URL, or first+last+domain') and explaining that candidates entries follow the same rules. It also promotes lead_id as the preferred identifier, which is a semantic nuance not present in the schema. This raises it above baseline.

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

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

The description opens with a specific verb+resource: 'Find and verify a work email.' It then clarifies the identifier options (lead_id, LinkedIn URL, first+last+domain) and the batch mode, making the tool's scope distinct from siblings like find_phone (which finds phones) and validate_email (which only validates an existing email). The title and description align, and the behavior is unambiguous.

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

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

The description offers clear context: it says lead_id is 'best' (cheapest and most accurate), explains the single vs. candidates modes, and routes >10 candidates to an async job via get_bulk_job. It also directs users to call get_balance for real prices and to read cost.amount_charged. However, it does not explicitly state when not to use this tool vs. alternatives (e.g., 'use validate_email if you already have an email'), so it stops short of a full 5.

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 carry readOnlyHint, openWorldHint, and idempotentHint, but the description adds a critical behavioral disclosure those fields do not cover: 'FREE — this call never spends credits.' This cost/credit trait is exactly the kind of context that structured annotations fail to convey, and it materially affects whether an agent should call the tool.

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

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

Four sentences, each carrying a distinct and necessary piece of information: what it returns, that it costs no credits, when to call it (before/after paid batches), and why its price data is authoritative. The content is front-loaded with the result set, and there is no filler — only a minor, acceptable echo of the title's 'free'.

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 description-level explanation. All five parameters are optional and fully documented in the schema, annotations cover the read-only/idempotent safety profile, and the description covers purpose, cost behavior, and usage timing. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description reinforces the tool's domain (balance, usage, real prices) but does not add per-parameter meaning beyond what the input schema already documents; each parameter already has a thorough description in the schema, including the 'Free' note on include_usage.

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

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

The description opens with a precise statement of what the tool returns — account balance, month-to-date usage, and the account's real per-operation prices — using a specific verb-plus-resource pairing that is unambiguous. It clearly distinguishes itself from all 16 sibling tools, which are company/lead data operations, and the 'THIS account's real per-operation prices' phrase adds differentiation from generic list prices.

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 explicit when-to-call guidance: call it before a batch of paid work to tell the user what they can afford, and after to report exactly what was spent. The closing note that returned prices beat any tool-description list prices also routes the agent to prefer this tool's data over static price figures. For a tool with no true sibling alternative, this fully answers the when/why-to-use question.

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 provide readOnlyHint, openWorldHint, and idempotentHint; the description adds valuable non-obvious cost behavior ('FREE — this call never spends credits', 'already billed at submit time') and polling guidance. No contradiction with annotations.

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

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

Four short sentences, each earning its place: purpose, cost behavior, billing rationale, and polling cadence. Front-loaded status/result statement followed by actionable guidance with zero waste.

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 covers return values, annotations cover safety/idempotence, and the description fills the cost and polling-cadence gap. It could explicitly mention in-progress job states, but the polling advice strongly implies them, so only a minor gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, but it does not need to compensate given full coverage.

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

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

Description states 'Status and results of a bulk job' with a specific verb and resource. It distinguishes itself from start_bulk_job in the sibling list through the polling/free framing, making intent unambiguous.

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

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

Gives explicit cadence guidance ('Poll every few seconds, not in a tight loop') and implies post-submit usage ('the work was already billed at submit time'). It does not explicitly name alternatives or exclusions, but the context is clear enough.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses billing behavior, approximate cost, refund policy for not-found records, and where to find actual spend in the response. It also clarifies that the tool is an alias, which transparently signals that behavior mirrors enrich_lead.

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

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

The description is compact and front-loaded: alias and purpose come first, followed by cost, then the routing guidance. It is only a few sentences and every clause earns its place, including the pricing note and the pointer to get_balance.

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

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

For a tool with 8 parameters, an output schema, and rich annotations, this description is complete. It covers what the tool is, what it costs, how failures are billed, and which sibling to prefer. No critical operational guidance 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 every parameter thoroughly. The description adds no per-parameter semantics; it focuses on cost and alias behavior. Per the calibration baseline, this is adequate but not additive.

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

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

The description opens by stating it is an alias of enrich_lead specifically for a LinkedIn profile URL, kept for backwards compatibility. This clearly identifies the resource (a lead), the action (enrich), the input shape (LinkedIn URL), and how it relates to its sibling enrich_lead.

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

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

The description explicitly routes agents to the preferred sibling: 'Prefer enrich_lead — it also accepts a Generect id (cheaper to get right) or an email for reverse lookup.' This gives a concrete when-to-use vs. when-not-to-use rule and names the alternative, leaving little to inference.

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

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

Annotations already mark the tool as readOnly, idempotent, and openWorld, but the description adds valuable behavioral context: it never spends credits, only hits a free account endpoint, reports server version, and makes credential verification optional. This goes beyond the structured hints and helps an agent understand side effects and cost impact.

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

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

The description is compact: three short sentences with the core purpose and cost warning front-loaded. Every sentence adds useful information, and there is no filler or redundant restating 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?

For a simple tool with two optional parameters, a provided output schema, and strong annotations covering safety, this description is complete. It explains cost behavior, credential checking, endpoint usage, and monitor suitability—everything an agent needs to invoke it correctly.

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

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

The input schema already covers both parameters with clear descriptions, including the default for check_credential. The description adds only the paraphrased idea 'unless you disable it,' which does not significantly expand on the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a concrete noun phrase, 'Liveness check,' and specifies exactly what the call does: confirm the server is up, report its version, and optionally verify the credential against a free endpoint. This makes it easy for an agent to distinguish from data-returning sibling tools like search_companies or enrich_lead, even without naming them.

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

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

The description gives a clear use context: it is free, never spends credits, never touches a paid data endpoint, and is safe to call from a monitor. It does not explicitly name sibling alternatives or state when not to use it, but the free/safety framing is strong guidance for tool selection.

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

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

Annotations already indicate destructive and read-write behavior, so the description need not repeat that. It adds valuable extras: the call 'never spends credits' and the event-driven wake-up behavior. This goes beyond the structured fields without contradicting them.

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

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

Two sentences carry the full payload: operations, credit cost, and usage context. No filler, no repetition of schema details, and the most important information is front-loaded.

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

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

Given rich schema descriptions, an output schema, and annotations covering destructiveness, the description is complete. It adds the missing contextual piece—when and why to use webhooks—without leaving an agent guessing about how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all parameters meaningfully. The description adds little parameter-level detail beyond framing the events as 'bulk-job completion' events. Baseline 3 is appropriate because the description does not degrade or confuse parameter understanding.

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

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

The description states a clear verb set ('list, create, update, delete or test') and a specific resource ('webhook endpoints for bulk-job completion'). It fully distinguishes this tool from all siblings, none of which manage webhooks, so an agent can immediately identify its purpose.

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

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

Explicitly tells the agent when to use it: in scheduled/unattended workflows instead of long polling, with the rationale 'register once, then let the completion event wake your job up.' This is concrete usage guidance that names an alternative pattern and the condition favoring 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=true and openWorldHint=true, so the description correctly aligns. Beyond that, it discloses key behaviors: it is billable (~$0.002 per row), rows are masked per API contract, certain parameters force a pricier realtime mode, the preview index may disagree with the cached search index, and there is a known bug with exclude_names in database mode. This is substantial transparency that goes well beyond the annotations.

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

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

The description is two paragraphs and moderately long, but every sentence adds meaningful context (cost, masking, intended flow, known issue). It front-loads the core purpose and cost model. It is not bloated given the tool's complexity (41 params, multiple modes). The only minor deduction is that it could be tightened, but the density of information justifies the length.

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

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

Given the tool's complexity, the description covers the essential context: cost model, data masking, intended workflow, realtime vs database mode, and a known bug. It also clarifies the relationship to count_leads and mentions the free count_only option. The output schema exists, so return details are not required. Nothing an agent needs to call this correctly is missing.

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

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

The schema description coverage is 100%, so the schema already documents all 41 parameters. The tool description does not add parameter-specific semantics; it focuses on the overall flow, cost, and masking. Since the baseline for 100% coverage is 3, and the description does not attempt to compensate or add extra parameter context, a 3 is appropriate.

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

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

The description states a specific verb ('preview') and resource ('leads'), and immediately contrasts it with a count ('the actual people behind a count') and with a full search ('before committing to a full search'). It clearly differentiates from siblings like count_leads and search_leads, and even names the intended follow-up tools (enrich_lead, generate_email). This is unambiguous.

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

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

The description gives strong usage context: use it as a cheap pre-filter before committing to a full search, and specifically to decide which leads to enrich. It also warns about masked rows and suggests treating extra fields as a bonus, which guides expectations. It does not explicitly name alternatives like search_leads or say 'use search_leads when you need full contact details,' but the intended flow is clear. It also mentions count_only as a free second opinion on count_leads, which is a useful distinction.

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

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

Annotations already provide readOnlyHint and openWorldHint, but the description adds substantial behavioral context: billable per resolved profile, free unresolvable references, duplicate billing per row, 403 on numeric member ids, batch row ordering, and output id compatibility. No contradiction with annotations.

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

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

Dense but non-redundant. Front-loads the core purpose, then proceeds through billing, input types, batch mode, and output limitations in a logical order. Longer than typical but 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?

Covers billing behavior, accepted and rejected inputs, batch semantics, and output limitations. With an output schema present, it correctly avoids detailing return fields. The timeout parameter is delegated to the schema, which is acceptable.

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?

Input schema covers 100% of parameters, so baseline is 3. The description adds extra semantics for `profiles` (batch size, billing per row, deduplication) and clarifies accepted input formats plus the rejected numeric member id. This enriches understanding beyond schema descriptions.

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

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

States the specific action (reveal who is behind anonymous LinkedIn profile links) and the resource (anonymous LinkedIn links). It clearly distinguishes from siblings like enrich_lead by explicitly noting it returns identity only, and specifies accepted input types and output.

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

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

Explicitly positions the tool as the cheap first step before enrich_lead, generate_email, and find_phone, and directs users to enrich_lead for location/company/work history. It also warns against using numeric member ids as input and instructs to call get_balance for real pricing.

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

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

The description discloses billing per returned row, zero-cost for zero rows, the cost-reading mechanism, snapshot lag for headcount data, and referential guidance to get_balance. The schema adds escalation behavior for auto mode, realtime-only constraints, and HTTP 400 rejections. This goes far beyond the readOnlyHint/openWorldHint annotations without contradicting them.

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

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

The description is three sentences long, front-loads the core operation, and every sentence carries operational value: what it returns, what it costs, what to run first, and a data-freshness caveat. No filler or repetition of schema content.

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

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

For a 29-parameter, billable, output-schema-bearing tool, the description plus schema covers cost, prerequisites, mode behavior, data freshness, error conditions, pagination, and deprecations. The output schema handles return-value documentation, so nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, including realtime-only behavior and cost implications. The tool-level description adds only a small extra note about headcount snapshot lag, which is useful but not essential given the rich parameter descriptions already present.

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: 'Return companies matching an ICP,' so an agent immediately knows this is a search/list tool for companies. It does not explicitly name a sibling it is not (e.g. count_companies), but 'Return companies' plus the sibling name makes the distinction clear enough.

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

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

The description explicitly directs the agent to 'Run count_companies first,' providing a concrete sibling-workflow rule. The schema further adds strong mode-selection guidance ('Pick database explicitly when freshness is not critical and cost matters more than freshness') and flags filters that force realtime, which is exactly the kind of when-to-use-vs-alternative guidance this dimension rewards.

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 and openWorldHint, so the description carries the behavioral burden and meets it richly: per-row billing with a price, a 0-rows-costs-$0 guarantee, cost.amount_charged in responses, profile-data-only return scope (no email/phone), unstable ordering, and the known exclude_names-in-database-mode defect. All consistent with readOnlyHint, so no contradiction.

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

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

A single dense paragraph with the most decision-critical facts front-loaded: billable, price per row, then the free preflight (count_leads), then return scope, then follow-up tools, then pagination. Every sentence earns its place; nothing is fluff. Appropriate density for a 42-parameter 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?

With an output schema present, return-value description is unnecessary, and the schema fully covers all 42 parameter semantics. The description completes the picture for what the schema cannot convey: cost awareness, free-alternative routing, data scope, and reliable pagination. The database/realtime tradeoff lives in the schema's mode parameter where it belongs.

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

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

Schema coverage is 100%, so the schema documents all 42 parameters and sets a baseline of 3. The description adds genuine connecting value on top: it ties limit_by to 'the price of the call,' explains compact's id-acceptance guarantee, and frames exclude_ids as the reliable pagination mechanism. This is additive beyond the schema rather than redundant.

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 leads (people) matching an ICP' — and is clearly distinct from count_leads (which returns a count, not rows) and the enrichment siblings (generate_email/find_phone, which operate on returned ids). An agent can tell it apart from every sibling 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?

Explicitly instructs 'Run count_leads first — it is free' to size the audience and cost before spending, and routes follow-up work to 'generate_email / find_phone on the ids you actually want.' It also advises pagination by exclude_ids over offset due to unstable ordering. When-to-use and when-to-use-an-alternative are both 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?

The description explicitly states the tool is BILLABLE and reserves cost, indicating a side effect (charging). This directly contradicts the annotation readOnlyHint: true, which implies the tool does not modify state or cause side effects. Per the rubric, a contradiction yields a score of 1 and flags annotation_contradiction.

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

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

The description is three sentences, each purposeful: core function, cost/billing, and usage guidance. It is front-loaded with the primary action and avoids fluff. The all-caps emphasis on BILLABLE and RESERVED is intentional to highlight critical side effects, though slightly noisy, it does not detract.

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

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

The description covers the core function, cost implications, approval requirement, and follow-up actions (polling/webhook). An output schema exists, so return details are not needed. However, the contradiction with readOnlyHint is a notable gap that could confuse an agent about side effects. Despite that, the description itself is fairly complete for a bulk job 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 description coverage is 100%, so all parameters are already documented in the schema. The description adds some context (billing, approval) but does not clarify parameter syntax or usage beyond what the schema provides. The mention of 'up to 50' mirrors the schema's max on items. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly states the action: 'Submit up to 50 records for asynchronous processing and get a job_id back.' It names the resource (records), the operation (submit), and the outcome (job_id), distinguishing it from single-record tools like enrich_lead and from get_bulk_job which polls. The scope ('up to 50') and async nature differentiate it from siblings.

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

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

It provides explicit conditions: 'Only submit a list the user has approved' and describes follow-up actions ('Poll with get_bulk_job, or register a webhook'). It implies this is for batch processing vs single-record tools, but does not explicitly state 'use for multiple records' or 'avoid for single records'. However, the context is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses critical billing behavior: every address is billed regardless of result, with specific cost and how to find actual charges. It also notes that the verdict itself is the deliverable. This adds significant context beyond structured annotations.

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

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

The description is dense but every sentence earns its place: it starts with the purpose, immediately warns about billing, provides pricing specifics and how to read costs, and includes an exclusion. It's well-structured and front-loaded with the most critical 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 billable operation, the description covers the action, cost implications, billing exceptions, and how to retrieve real charges. With an output schema also present, the agent has everything needed to call and interpret results correctly without missing details.

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 schema already describes both parameters with 100% coverage ('Email addresses to validate. Each one is billed.' and 'Request timeout in milliseconds.'). The description adds pricing context but does not elaborate on the meaning of individual parameters beyond what the schema provides, so it meets the baseline.

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

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

The description clearly states the action ('Check deliverability of emails you already have') and the resource ('emails you already have'), distinguishing it from generate_email which creates emails. It's specific and unambiguous, with no tautology.

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

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

Explicitly instructs when NOT to use the tool: 'Never validate an address that generate_email just returned as valid; it is already verified.' It also references get_balance for pricing, guiding the agent on alternative actions. This is clear usage differentiation.

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