Unified GTM API for AI agents: find leads, enrich to verified emails, verify, detect intent, social listening, provision warmed sending, launch human-approved campaigns and handle replies. One key, prepaid credits.
Scored across 22 tools
The tools cover distinct phases like prospecting, enrichment, campaign sending, replies, and operations. A few research/discovery tools (check_companies, find_intent, research_company, prospect_picture) could overlap, but descriptions cross-reference alternatives and clarify boundaries. Mostly distinct with minor potential confusion.
Names are predominantly snake_case verb_noun (find_leads, create_campaign, get_operation). Minor deviations exist: bare enrich, prospect_picture, setup_sending, and singular/plural get_reply/get_replies. Overall readable and consistent.
22 tools is on the heavy side for one MCP server and falls in the borderline 16–25 range. The domain is broad and most tools map to distinct actions, but the surface feels over-scoped rather than tightly curated.
Core workflows are covered: lead/company discovery, enrichment, campaign creation/launch, replies, research, and billing. However campaign lifecycle lacks update/delete/list/get-campaign operations, and list management is explicitly unavailable via MCP. These are notable gaps, though main workflows remain workable.
Add recipients to a draft or incomplete campaign through the suppression-safe bulk importer. Returns removed counts for recipients not added and their reasons. Adding to an active campaign pauses it and requires signed-in human confirmation before recipients enter the sequence. The campaign-wide maximum is 5,000 unique recipients. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan. Pass each person’s location from find_leads or enrich in leads[].location (at most 200 characters). Active area rules leave new people with no location out; removed.no_location is included in removed.do_not_contact, not added again to total.
| Name | Required | Description | Default |
|---|---|---|---|
| leads | No | ||
| dry_run | No | ||
| campaign_id | Yes | ||
| idempotency_key | Yes | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| confirmation_token | No | ||
| finalize_incomplete | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: returns removed counts with reasons, pauses active campaigns pending signed-in human confirmation, enforces a 5,000 unique-recipient campaign maximum, and details dry_run's non-reserving semantics. The do_not_contact/removed.no_location accounting behavior is disclosed, which an agent could not infer from destructiveHint=true alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and keeps every sentence informational — limits, confirmation, dry_run, and location rules each add distinct value. Some sentences are densely packed and require a second read, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, open-world mutation with no output schema, the description covers the return shape (removed counts and reasons), the confirmation gate, and capacity limits. The remaining shortfall is the unexplained confirmation_token/finalize_incomplete parameters, which an agent invoking the approval flow would need.
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 only 17%, and the description compensates for two parameters well: dry_run (advisory estimate as of evaluated_at, reserves nothing, may diverge from a later plan) and leads[].location (sourced from find_leads/enrich, 200-char cap). However confirmation_token, finalize_incomplete, and campaign_id carry no meaning in the description, so the gap is only partly closed.
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 ('Add recipients to a draft or incomplete campaign') and distinguishes itself from the campaign-creation sibling by scoping to existing draft/incomplete campaigns. The suppression-safe bulk importer framing tells the agent exactly what mechanism is used.
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 clear conditional guidance: use dry_run for an advisory estimate, expect a pause plus human confirmation when targeting an active campaign, and source location values from find_leads or enrich. It stops short of an explicit 'use X instead when Y' routing against siblings such as find_leads or launch_campaign.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer one yes/no question about each of up to 10 companies from its own website, e.g. "Do they let their users book appointments inside their product?" or "Do they publish a public API?". For angles, what's changed, how to approach, or why now on one company or person, use research_company (a company) or prospect_picture (a person, their company, or both) instead. Ask about what the company offers or does, as a seller would. Each answer is yes (with the passage from the company's own site that states it, quoted word for word, and its page URL), not_found (every passage of the pages listed in pages_read was checked and none touches it; that is not proof it's absent) or unclear (the pages hint at it but no single passage states it). A yes always comes with a passage that states it on its own. 3.5 credits per company answered yes or not_found; unclear answers and unreadable sites are free. A call answers within about a minute; a company it could not reach in that time comes back unclear (free), so send it again. Use it after a broad company search to keep only companies with the need, before paying for people or emails. budget_credits is a spend ceiling, never permission to use a dearer source: above it, the call is refused before anything is reserved, and no company you sent is dropped to fit. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"question":"Do they let their users book appointments inside their product?","company_domains":["acme.com","example.io"]}
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| question | Yes | One yes/no question about each company's own offering, as a seller would ask it (10–300 characters), e.g. "Do they let their users book appointments inside their product?". Answered only from the company's own website. | |
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged. No company you sent is dropped to fit. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| company_domains | Yes | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Far exceeds what the annotations convey (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false). It discloses credit pricing (3.5 per company answered yes/not_found, unclear and unreadable sites free), response latency (~1 minute), that unreachable companies return unclear and should be re-sent, and that budget_credits is a hard ceiling that refuses the call rather than dropping companies. This is materially richer than the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, examples, and alternatives before the pricing and parameter detail. It is long, and budget_credits/dry_run semantics are restated nearly verbatim from their schema descriptions, which is slight redundancy, but nearly every sentence carries operational information an agent needs.
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?
No output schema exists, and the description compensates fully by defining the three return states (yes with a verbatim quoted passage and page URL, not_found with the scope caveat that it is not proof of absence, unclear), plus pricing and latency. For a 5-parameter tool with a genuinely complex contract, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so most parameters are already documented. The description nevertheless adds meaning beyond the schema: budget_credits is framed as a spend ceiling and never permission for a dearer source, and dry_run is explained as returning the plan (max cost, how many sources could answer, limits tripped) with nothing looked up or charged. idempotency_key, however, is only covered by the schema, not the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('answer one yes/no question about each of up to 10 companies from its own website') and immediately grounds it with two concrete example questions. It explicitly distinguishes itself from the sibling tools research_company and prospect_picture, so an agent can route without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('after a broad company search to keep only companies with the need, before paying for people or emails') and names the alternatives for adjacent tasks (research_company for angles/what changed/why now on a company, prospect_picture for a person). It also tells the agent the question style to use ('ask about what the company offers or does, as a seller would').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a draft email campaign with sequence steps, {{first_name}}-style variables, leads, and an optional sending window. Common sending_window.timezone values: Europe/London, Europe/Dublin, Europe/Paris, Europe/Berlin, America/New_York, America/Denver, America/Phoenix, America/Toronto, Australia/Sydney, Asia/Singapore, America/Chicago, Asia/Kolkata, Asia/Dubai. Returns removed counts for opted-out, do-not-contact, invalid, platform-blocked, or capped recipients. Active person, company and area entries are enforced even when new list creation is disabled. List management requires a signed-in person in the console or client window; there is no list-management MCP tool. Drafts never send; launch is a separate confirmed action. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan. Pass each person’s location from find_leads or enrich in leads[].location (at most 200 characters). Active area rules leave new people with no location out; removed.no_location is included in removed.do_not_contact, not added again to total.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| leads | Yes | ||
| steps | Yes | ||
| dry_run | No | ||
| stop_on_reply | No | ||
| sending_window | No | ||
| idempotency_key | Yes | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover safety flags, but the description adds genuinely non-derivable behavior: what `removed` counts mean (opted-out, do-not-contact, invalid, platform-blocked, capped), that active person/company/area entries are enforced even when new list creation is disabled, that drafts never send, and that dry_run reserves nothing and may differ from a later plan. This is rich disclosure beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and the create-vs-launch distinction, and every sentence carries operational content. It is dense and interleaves several concerns (billing, list management, area-rule edge cases), with some granularity that borders on padding ('removed.no_location is included in removed.do_not_contact'), but nothing is clearly 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 7-param, nested, non-read-only tool with no output schema and low schema coverage, the description supplies the return-side essentials (`removed` accounting), the dry-run contract, and enforcement rules. The main gap is that it doesn't document most nested lead/step fields, which the schema carries only via types and constraints.
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 only 14%, so the description has to compensate — and it does for the highest-risk params: sending_window.timezone (names common values), dry_run (advisory/reserves-nothing semantics), and leads[].location (source from find_leads/enrich, 200-char cap). It does not add meaning for name, the other lead fields, or step body/subject/wait_days, so it falls short of full compensation.
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 gives a specific verb+resource (create a draft email campaign) plus the shape of the payload (sequence steps, variables, leads, optional sending window). It also explicitly distinguishes itself from the sibling launch_campaign: 'Drafts never send; launch is a separate confirmed action.' An agent can route between create and launch 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 clear context for use and non-use: drafts never send, launch is a separate confirmed action, and there is no list-management MCP tool (so list management must happen elsewhere). It also explains when to reach for dry_run. It stops short of a full when-to-use/when-not matrix against all siblings, but the boundaries are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find a person's verified work email and profile (title, company, linkedin, location). Accepts email, linkedin_url, or name plus company_domain. Fresh results are cached per workspace; repeats are served from cache. Costs credits on hit only. want: ["mobile_phone"] also looks for a mobile number: 17 credits when a separate mobile search finds it, 5 when it comes with the email, nothing when none is found. budget_credits is a spend ceiling, never permission to use a dearer source: the same ceiling as max_credits (send one); above it, the call is refused before anything is reserved. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. route picks how sources are chosen: balanced (the default), cheapest, broadest or fastest. The price is the same whichever you pick, and the answer's layrcake.route says which route was used and whether it came from the request, this key's default or the default.
| Name | Required | Description | Default |
|---|---|---|---|
| want | No | What to look up. work_email and profile run the email lookup (5 credits on a hit), which returns a mobile number too when its source has one. mobile_phone also runs a separate mobile search when the email lookup found none: 17 credits when that search finds one, 5 when the mobile came with the email, nothing when no mobile is found; a mobile_phone-only request that finds only an email is free and returns nothing. Where this isn't applied for your key yet, every call runs the same email lookup whatever this lists. | |
| route | No | Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted. | |
| person | Yes | ||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| max_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged. | |
| budget_credits | No | Spend ceiling for this call, in credits. The same ceiling as max_credits, as a number: send one or the other. If the most the call can cost is above it, the call is refused before anything is reserved or charged. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond annotations: caching per workspace, credit costs (5 on hit, 17/5/0 for mobile), budget_credits as a ceiling that never grants a dearer source, refusal before reservation, dry_run semantics, and route effects. This is more than the annotations' coarse destructiveHint/openWorldHint. However, the description's 'Costs credits on hit only' is slightly at odds with the mobile-fee cases, and it doesn't clarify the destructiveHint=true behavior (what could be 'destroyed'), so it stops short of full disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A dense run-on paragraph mixing caching, three credit scenarios, two spend-ceiling params, dry_run, and route in one block, with a typo ('layrcake.route'). Not front-loaded or partitioned; the agent must parse a wall of text to extract key rules.
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 cost, caching, route, and dry_run well for a 7-param enrichment tool with no output schema, but omits return shape, error handling for refused calls, and why the tool is marked destructive. Adequate but with clear gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 86%, so the schema already carries most param details; the description adds value on want (mobile pricing) and route (that price is unchanged) beyond the schema, but for budget_credits/max_credits it mostly restates the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (a person's verified work email and profile), and lists the outputs (title, company, linkedin, location). It doesn't explicitly name a sibling to distinguish from, but the 'verified work email' phrasing sets it apart from 'find_leads'/'prospect_picture' well 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?
Implies when to use it by describing accepted inputs (email, linkedin_url, or name plus company_domain), but offers no explicit when-to-use vs when-not, and doesn't route the agent to alternatives like find_leads or verify_email. Usage is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enrich one company domain with independently statused profile, technologies, funding, or relationships datasets; or request an exclusive fast/deep sourced brief. Structured hits cost 13 credits each; briefs cost 10 fast or 40 deep. Empty and unavailable datasets are free.
| Name | Required | Description | Default |
|---|---|---|---|
| want | No | ||
| depth | No | ||
| company_domain | Yes | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered; the description adds genuinely new behavioral facts beyond that — per-dataset credit costs (13), fast/deep brief pricing (10/40), and that empty or unavailable datasets are free. It still omits what the response looks like and the credit-exhaustion failure mode, but the cost model is meaningful added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed sentences with no filler: the capability list comes first, the cost model second. The pricing clause is dense but each element (per-hit, brief, free cases) carries distinct decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should ideally hint at the shape of the returned datasets or the brief, and it does not. For a cost-incurring, non-idempotent call the pricing coverage is good, but the sibling ambiguity and absent return-value framing leave gaps an agent must guess at.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (company_domain and idempotency_key are documented in-schema; want and depth are bare enums). The description compensates by explaining that 'want' selects among independently statused datasets and that 'depth' (fast/deep) applies specifically to briefs and changes the price, which is semantics the enum alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Enrich one company domain') and enumerates the concrete datasets it can return (profile, technologies, funding, relationships) plus the brief alternative, which is far more than a restatement of the title. However, it never distinguishes itself from close siblings like research_company or enrich, so an agent still has to infer which enrichment tool to pick.
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 single-domain scope ('one company domain') is implied as a usage boundary versus batch tools, and the pricing sentence implicitly warns the agent about cost. But there is no explicit when-to-use, when-not-to-use, or named alternative, so selection against research_company/enrich remains unguided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover companies by hiring activity, technologies in use, similarity to one company domain, or a plain-language query (up to 400 characters, translated server-side into those filters and echoed back in result.interpreted). Industry phrases in a plain-language query are not applied; they appear in result.interpreted.dropped.industries so the result can be disclosed and narrowed with supported filters. Hiring, technology and query requests accept provider-taxonomy industries, ISO alpha-2 country_codes and company_headcount. Sent with a query, they win over what the query says; company_headcount merges bound by bound, so a bound you leave out keeps the query's value unless that would invert the range, in which case your range is used alone. result.interpreted.caller_filters lists them with every reading of the query they replaced or dropped. limit defaults to 25, maximum 100. Returns unique companies with evidence and company_domains, plus jobs_last_30_days and last funding round facts when the source reports them. Technology matches carry match_confidence; only high-confidence companies are returned and billed unless include_low_confidence is true, which adds a separate unbilled low_confidence_companies list. Technologies take a tool's usual name (for example Customer.io or Pendo); an unknown name is refused with close suggestions. A similar_to request also accepts country_codes and company_headcount: each lookalike then comes back with headcount, industry and country, companies that don't fit are dropped and free (counted in result.filtered_out), and each company kept costs 33 credits. Hiring results cost 11 credits each, unfiltered lookalikes 13 and technology results 16; zero results are free. mode: "firmographic" finds companies by industries (LinkedIn's names, as on find_leads) and ISO alpha-2 country_codes, optionally narrowed by locations (cities or regions, matched against each company's headquarters) and company_headcount; 2 credits a company. mode: "local" finds local businesses by categories (for example "dentist") in locations, each a city with its country (for example "Leeds, United Kingdom"); 3 credits a business, with a website. budget_credits is a spend ceiling, never permission to use a dearer source: when the call could cost more, limit is lowered to the largest that fits and result.budget_applied says so. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"hiring":{"titles":["GTM Engineer","Sales Development Representative"],"posted_within_days":30},"country_codes":["US","GB"],"company_headcount":{"min":50,"max":500},"limit":10} route picks how sources are chosen: balanced (the default), cheapest, broadest or fastest. The price is the same whichever you pick, and the answer's layrcake.route says which route was used and whether it came from the request, this key's default or the default.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | firmographic: companies by industries (LinkedIn's names, as on find_leads), country_codes, and optionally locations and company_headcount. local: local businesses by categories (for example "dentist") in locations. Leave it out for hiring, technologies, similar_to or query. Where a mode isn't available to this key yet, a request that sets it is refused with the reason. | |
| limit | No | ||
| query | No | ||
| route | No | Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted. | |
| hiring | No | ||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| audience | No | ||
| keywords | No | Only with mode firmographic: 1 to 10 phrases, for example "carbon accounting" or "dental practice management". A company matches when its own description, products or specialties mention any of them; with keywords, industries may be left out. Each company then comes back with its description. Where keywords aren't available to this key yet, a request that sets them is refused with the reason. | |
| locations | No | Places, only with mode. firmographic: optional cities or regions inside country_codes, matched against each company's headquarters. local: required, each a city with its country, for example "Leeds, United Kingdom" or "Austin, TX". | |
| categories | No | Only with mode local: the kinds of business, for example "dentist" or "commercial cleaning service". | |
| industries | No | ||
| similar_to | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| technologies | No | ||
| country_codes | No | ||
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one company fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| exclude_keywords | No | Only with mode firmographic: up to 10 phrases, for example "recruitment agency" or "consultancy". Companies whose own description mentions any of them are left out. Each company then comes back with its description. Where exclude_keywords aren't available to this key yet, a request that sets them is refused with the reason. | |
| company_headcount | No | Employee-count range. With no min or max, companies with fewer than 10 employees are left out. Any bound replaces that default: a max without a min searches from 1 employee. | |
| include_low_confidence | No |
Screen up to 25 company domains for dated buying signals: hiring (live job posts with evidence URLs), funding, news, job_change. For angles, what's changed, how to approach, or why now on one company or person, use research_company (a company) or prospect_picture (a person, their company, or both) instead. Leave signals out unless a family must be checked on every company: by default only hiring is checked, a company that is not hiring costs nothing, and a hiring company's latest funding round comes with it (the others list funding under skipped_signals). A company with a current hiring signal costs 11 credits. Each paid check you ask for explicitly (funding on a company that is not hiring, news, job_change, technology) costs 13 credits whatever it finds; hiring checks that find nothing, and failed checks, are free; result.domain_status[].charge shows what each company cost. Recency: signals observed inside since / within_days (default 180 days) are current; older ones return under result.historical as context. Each news signal carries news_type, the kind of news it is: funding | product | partnership | customers | expansion | leadership | layoffs | acquisition | challenges | recognition | other. roles filters hiring by job title (literal match). technology is DEPRECATED (a present-day vendor detection with no adoption date, not a buying signal; use find_companies technologies). audience is an optional goal: what you sell and to whom. It never changes charges. With a goal, ranking.by says goal when signals were judged for it, otherwise recency (today’s order); why_now requires a date within 60 days, and why_now_basis says judged or date. Unavailable or unsure judgments use the date rule. budget_credits is a spend ceiling, never permission to use a dearer source: above it, the call is refused before anything is reserved, and no company you sent is dropped to fit. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"company_domains":["acme.com","example.io"]}
| Name | Required | Description | Default |
|---|---|---|---|
| roles | No | Hiring role filter, up to 25 job titles or phrases: a hiring post counts only when it is one of these roles. Put a role in double quotes to match it word for word. Applies to hiring only; job_change events carry no structured role field. | |
| since | No | ||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| signals | No | Signal families to check. hiring = live job posts with evidence URLs; funding, news, job_change = dated events. Omit it to check hiring first: only hiring is checked, and a hiring company's latest funding round comes with it; list funding explicitly to check every company (a paid check). DEPRECATED: technology — a present-day vendor detection with no adoption date, not a buying signal; use find_companies.technologies instead. Still accepted in v1. | |
| audience | No | Optional goal: what you sell and to whom. Always accepted. Until goal ordering is available, signals keep today’s order with ranking.by recency and date-based why_now flags; no change to charges. | |
| within_days | No | ||
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged. No company you sent is dropped to fit. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| company_domains | Yes | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already flagging destructiveHint=true, the description goes far beyond them: it prices each path (11 credits for a hiring company, 13 per explicit paid check), states which checks are free (hiring misses, failed checks), explains budget_credits refusal-before-reservation semantics, dry_run's no-charge plan, and recency/historical split. This is the kind of cost-and-side-effect disclosure the destructiveHint annotation only hints at.
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 and every sentence is substantive, but it is delivered as one unbroken ~350-word block interleaving pricing, deprecation, recency, ranking, and refusal rules. There is no structural separation (no lines for cost, defaults, or return fields), so scanning for a specific rule is hard despite low redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return burden and does: result.domain_status[].charge, result.historical, skipped_signals, news_type values, ranking.by, and why_now_basis are all explained. For a 9-parameter, credit-spending, open-world tool, an agent has everything needed to call it 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 67%, and the description fills many gaps: signals defaults and the DEPRECATED technology note, roles as literal job-title match, audience as a charge-neutral goal, and how ranking.by / why_now_basis behave with a goal. It does not mention idempotency_key at all, and its 'up to 25 company domains' conflicts with the schema's maxItems of 50, a count an agent could rely on incorrectly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a concrete verb and resource — 'Screen up to 25 company domains for dated buying signals' — and enumerates the signal families (hiring, funding, news, job_change). It also names the two siblings it is not (research_company for a company angle, prospect_picture for a person), so an agent can route 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 when-to-use and when-not-to-use: 'For angles, what's changed, how to approach, or why now... use research_company... or prospect_picture instead.' It also gives a default-behavior rule ('Leave signals out unless a family must be checked on every company') that tells the agent which invocation is the cheap/correct one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search 200M+ B2B contacts by structured filters (titles, locations, industries, company_headcount, company_domains). At least one of titles, industries, locations, or company_domains is required. company_domains accepts up to 100 domains or URLs and restricts results to people at those companies. Industry values follow LinkedIn's taxonomy (for example, 'Hospitals and Health Care'). Returned leads have work_email null. If title_filter.withheld is above 0, the sources found people whose titles did not match; widen titles to see them. Costs 0.25 credits per lead returned, with a 3-credit minimum when any lead is returned; zero results are free. budget_credits is a spend ceiling, never permission to use a dearer source: when the call could cost more, limit is lowered to the largest that fits and result.budget_applied says so. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged. Example: {"audience":"Heads of Sales and VPs of Sales at US software companies with 50 to 500 employees","titles":["Head of Sales","VP Sales"],"industries":["Software Development"],"locations":["United States"],"company_headcount":{"min":50,"max":500},"limit":25} route picks how sources are chosen: balanced (the default), cheapest, broadest or fastest. The price is the same whichever you pick, and the answer's layrcake.route says which route was used and whether it came from the request, this key's default or the default.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| route | No | Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted. | |
| titles | No | ||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| premium | No | Consent, for this call only, to a dearer source when the standard sources come back short, as long as the whole call, the premium step included, stays within budget_credits (which it requires). The premium step is charged separately and reported in result.premium_step. Without it, budget_credits is only a ceiling. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason. | |
| audience | Yes | ||
| locations | No | ||
| industries | No | ||
| offer_token | No | Accept a previous answer's offer: send the same call again, unchanged, with its offer.offer_token. Only the premium step runs, as its own charge at the offer's price, up to its max_credits; the token works once, until expires_at, and only when max_credits is within this key's premium allowance. Where premium offers aren't available to this key yet, a request that sets it is refused with the reason. | |
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, limit is lowered to the largest that fits and result.budget_applied says so; the call is refused, before anything is reserved or charged, only when not even one lead fits. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| company_domains | No | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| company_headcount | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false / destructiveHint=true / openWorldHint=true; the description adds far more: 0.25 credits per lead, a 3-credit minimum, free zero-result calls, budget_credits acting as a ceiling that lowers limit rather than enabling pricier sources, and dry_run performing no lookup, reservation or charge. It also warns that returned leads carry work_email=null and explains title_filter.withheld, 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?
Front-loads purpose well, but the final sentences duplicate the route enum and its default straight from the schema ('balanced (the default), cheapest, broadest or fastest'), and the sentence is convoluted and contains a typo ('layrcake.route'). Several sentences are overloaded where bullets would serve better.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return burden and does so reasonably: work_email is null, title_filter.withheld is surfaced, result.budget_applied and the route echo are named. It is only incomplete on the required 'audience' parameter, whose semantics are never stated.
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?
Adds real meaning beyond the 46%-covered schema: LinkedIn industry taxonomy, the semantics of company_domains as a company-level restriction, and headcount ranges. Gaps remain — the single required parameter 'audience' is never explained in prose (only shown inside the example), and the stated 'up to 100 domains' conflicts with the schema's maxItems of 200.
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 and scale ('Search 200M+ B2B contacts by structured filters') and immediately enumerates the filter axes, so an agent knows exactly what class of tool this is. It is clearly distinguishable from siblings like find_companies or enrich.
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 hard precondition ('at least one of titles, industries, locations, or company_domains is required') and explains the situations for dry_run, premium and offer_token. However, it never names an alternative tool (e.g. find_companies) or says when not to use this one, so routing among siblings is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find public social posts by keyword (people discussing a topic), by a known author's profile URL or handle, or by LinkedIn company domain. For angles, what's changed, how to approach, or why now on one company or person, use research_company (a company) or prospect_picture (a person, their company, or both) instead. intent: pain | question keeps only posts one audience-specific model pass classified as buyer pain or a buying question (each returned post carries its label and reason; unclassifiable candidates are withheld, never returned unlabelled) and adds a separate classification component at llm token pricing, shown in result.cost_breakdown. Supports LinkedIn, X, Reddit and Facebook, and YouTube and TikTok by keyword, when enabled. include: ["author_details"] adds each author's type (person or company page) and whether the post is a repost. Returns per-platform status and only bills posts passing deterministic literal-v1 relevance. Keyword search costs 0.5 credit per returned post and a miss is free; author/company scope adds a 1-credit base even when no post is returned. On Reddit and Facebook a returned post costs 2 credits. For a person known only by name, call enrich with person { full_name, company_domain } first, then pass the linkedin_url it returns as author { type: "profile_url", profile_url }; a name-only author is refused before any charge, with that call in error.details.next. intent also takes hiring_for_it (the author's own company hiring for the work your product does) and competitor_complaint (a user complaining about a tool like yours; it finds most, not all, complaint posts, so an empty answer doesn't mean nobody is complaining). audience is an optional goal: what you sell and to whom. It never changes charges. With a goal, posts are ordered by how worth a reply they are (ranking.by goal; recency when nothing was judged) and each carries why_now with why_now_basis judged or date. leads takes contacts as find_leads or enrich return them and gives each one's best recent reason to reach out (their own post, a comment, a reaction or their company's post) with the evidence, and the person ready for enrich: 3 credits per lead with a signal, a lead with none is free, budget_credits caps it. Up to 10 leads answer inline; up to 1,000 run as an operation: send idempotency_key, then poll get_operation, which returns the leads 25 at a time with next_cursor. engagers_of takes up to 5 post URLs and returns the people who reacted, commented, replied or reposted, each with what they did and ready for enrich: 0.5 credit per person (2 on Reddit), a post with nobody is free, per_post up to 50. author_filter (headline or bio keywords) keeps only matching people, adds 0.4 credit per person read, and skips Reddit and Facebook, whose people show no headline. Choose posts your buyers engage with. A company's own announcements can draw mostly its own staff, so check who engaged, or pass author_filter with title words (for example head of sales, VP sales) to keep only the roles you want. Each post reports read (people read) and, on LinkedIn, engaged_total; more_available true means the sample missed people. To read everyone, send the same posts with read_all: true, budget_credits and idempotency_key: it runs in the background (about 2 minutes per 500 people) at the same price per person kept, plus 0.4 credit per person read with author_filter, and never charges above budget_credits. When the counts are known the sample's full_read quotes that budget and the time: tell the user before running it. Then poll get_operation, which returns the people 25 at a time with next_cursor. If the budget runs short, each post says how many people were not read (not_read) or withheld (withheld) and limited_by budget: raise budget_credits to get them. With author_filter, a title check also keeps people whose headline clearly means one of your terms in other words (a CCO for chief revenue officer): each is marked matched_by judged, and filter_basis says judged when it added anyone. It only adds people, and a full read checks at most 2,500 of them.
| Name | Required | Description | Default |
|---|---|---|---|
| leads | No | Leads mode: people from find_leads or enrich. Returns each one's best recent reason to reach out (own post, comment, reaction or company post). LinkedIn only: send no query, platforms or intent. | |
| limit | No | ||
| query | No | ||
| author | No | ||
| intent | No | ||
| include | No | ||
| audience | No | ||
| per_post | No | Engagers mode: up to this many people from each source (reactions, comments, replies) of each post. | |
| read_all | No | Engagers mode: read everyone who engaged, not a sample, in the background (about 2 minutes per 500 people). Needs budget_credits and idempotency_key. Returns an operation: poll get_operation, which returns the people 25 at a time with next_cursor. | |
| platforms | No | ||
| engagers_of | No | Engagers mode: up to 5 post URLs (LinkedIn, X, Reddit, Facebook). Returns the people who reacted, commented, replied or reposted. Send no query, platforms, intent or audience. | |
| within_days | No | ||
| author_filter | No | Engagers mode: keep only people whose headline contains one of these words, e.g. ["head of sales", "VP sales"]. Each person read costs a small scan fee; Reddit and Facebook are skipped (no headlines). | |
| budget_credits | No | Leads mode, or engagers_of with read_all: a spend ceiling in credits. Leads beyond it come back not_processed; read_all reads people up to it. | |
| company_domain | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false; the description goes far beyond them, disclosing per-post credit pricing, free misses, platform-specific surcharges, base fees, refusal/rescue behavior for name-only authors, budget ceilings, and background-operation polling. No contradiction with the declared destructive/charging profile — it explains why spending occurs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, and most sentences carry required operational detail, but it is a single ~700-word run-on block with no paragraphs, bullets, or headings, making mode separation hard to parse. The complexity justifies length, but the structure does not earn a higher score.
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 16-param, multi-mode, no-output-schema tool, the description covers modes, input prerequisites, error/refusal paths, billing rules, and even key return fields (read, engaged_total, more_available, next_cursor, cost_breakdown). Nothing an agent needs to invoke it correctly appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 16 params at 50% schema coverage, the description adds real meaning for the non-obvious ones: intent values (pain, question, hiring_for_it, competitor_complaint), include: [author_details], audience ordering, leads/engagers_of/author_filter/read_all/budget_credits semantics. It leaves simple params (query, limit, within_days, platforms, per_post) essentially to the schema, so it is strong but not fully compensating.
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 and enumerates the three search scopes (keyword, author profile URL/handle, LinkedIn company domain), then explicitly names which sibling tools to use instead for other needs (research_company, prospect_picture). An agent can distinguish it from siblings without opening the schema, even though the tool also carries leads/engagers modes.
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 alternative for 'angles, what's changed, how to approach, or why now' and a concrete precondition for name-only authors (call enrich first, then pass linkedin_url). Mode-selection cues are implied via 'send no query...' phrases, but it never contrasts with closer siblings like find_intent or find_leads, and the guidance is buried in a dense wall of text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns this key's identity and permissions: scopes, monthly spend cap and remaining allowance, today's send and reply capacity, per-action limits, and workspace suspension state. Every external action (buying mailboxes, launching, adding leads to a live campaign, replying) needs a person's approval. Free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: the tool is free, and it discloses that external actions require a person's approval. This helps the agent understand the operational implications of the returned permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by a compact list of returned fields. The closing 'Free.' is a single-word sentence that earns its place by conveying cost behavior without elaboration. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only identity tool, the description fully covers what an agent needs to know: what data is returned and the approval context for external actions. No output schema exists, but the enumerated return fields provide sufficient completeness for correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so there is no parameter burden. The baseline for zero-parameter tools is 4, and the description adds no unnecessary parameter-related noise.
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: 'Returns this key's identity and permissions.' It then enumerates the exact fields returned (scopes, spend cap, remaining allowance, send/reply capacity, per-action limits, suspension state), which clearly differentiates it from siblings like get_usage or get_operation that focus on operation or usage details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is useful for checking permissions and limits before taking external actions, especially with the note that 'Every external action... needs a person's approval.' However, it never explicitly states when to use this tool versus alternatives or mentions any exclusions, leaving usage guidance to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current state of provisioning, campaign creation, launch, company research, or prospect picture work by operation_id; completed research and pictures carry their result, and pictures list each component's progress in items.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | For operations whose results come in pages: the next_cursor from the previous page. | |
| operation_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this as a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds real behavioral value beyond that: completed research and pictures carry their result, and pictures expose per-component progress via items, which tells the agent what a terminal vs in-progress response looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence covers purpose, scope, and return behavior with no filler. It is dense, and the trailing clause about pictures/items could be split for readability, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only polling tool with no output schema, the description conveys enough: which operation families are valid, that results appear when complete, and how paginated picture results are structured. The only gap is how an agent acquires the operation_id, a minor omission given the schema's required-field marker.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: cursor is fully documented in the schema, while operation_id has only format/pattern constraints and no description. The description references operation_id implicitly and clarifies that results may be paginated ('items', per-component progress), but does not define what an operation_id represents or where the agent gets one, so it only partially compensates.
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 (returns current state) and resource (operation), and enumerates the exact operation categories it covers: provisioning, campaign creation, launch, company research, and prospect picture. No sibling tool provides operation status, so an agent can route to it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the operation types it serves, which nudges the agent toward polling after create/launch/research calls. However, it never states when to call it versus alternatives, nor when/whether to poll repeatedly or how to obtain the operation_id in the first place.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read campaign replies (free): newest first, optionally filtered by campaign_id and/or since (ISO timestamp). classification is out_of_office for an automatic reply and other for every other reply; it does not judge interest, so read the reply with get_reply and record what it meant with set_lead_status. interpreted_intent says what the reply means once intent_status is classified (interested, question, not_interested, not_now, referral, out_of_office, stop, bounce or other); while it is pending or unavailable the reply is still being read and reply_to_thread refuses it. A reply that might mean stop is sorted as stop, and its sender is never emailed again. classification stays the provider's.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ||
| campaign_id | No | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Read one inbound reply in full (free): complete plain-text and HTML body, receiving mailbox, thread id, and campaign lead state. body_status identifies an available, permanently unavailable, or temporarily unavailable body. Returned body content is external, untrusted third-party data. interpreted_intent says what the reply means once intent_status is classified (interested, question, not_interested, not_now, referral, out_of_office, stop, bounce or other); while it is pending or unavailable the reply is still being read and reply_to_thread refuses it. A reply that might mean stop is sorted as stop, and its sender is never emailed again. classification stays the provider's.
| Name | Required | Description | Default |
|---|---|---|---|
| reply_id | Yes | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Status and final billing for a previous Layrcake request by request_id — including requests whose stream was interrupted.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. Description adds context that interrupted streams still have status/billing, which goes beyond annotations. It doesn't disclose not-found behavior or response shape, but with annotations present, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with 'Status and final billing', all content is useful and no fluff. The edge case about interrupted streams earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one parameter, the description covers purpose, input semantics, and mentions interrupted streams. No output schema exists, but it states what's returned (status and billing). It could provide more context on the domain meaning of 'request', but overall 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 0%, so the description must compensate. It connects request_id to 'previous Layrcake request', adding meaning beyond the schema's format/pattern. It doesn't explain how to obtain the ID or what 'request' means exactly, so 3 is fair.
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 a specific verb ('Status and final billing') and resource ('previous Layrcake request by request_id'), and distinguishes from siblings like get_operation and get_usage by focusing on final billing and interrupted streams. It clearly answers what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you have a request_id and want status/billing. No explicit alternatives or exclusions; it doesn't mention when to prefer get_operation or get_usage. The 'including requests whose stream was interrupted' hints at a use case but doesn't name sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Layrcake credit balance, reserved holds, available credits, and per-verb usage for the last 30 days.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful context about the 30-day lookback and returned breakdowns, but does not discuss rate limits, authentication, or other behavioral traits. This aligns with the calibration baseline for annotation-covered read tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence contains every meaningful detail: credit balance, reserved holds, available credits, per-verb usage, and the 30-day window. There is no repetition of the title or the parameter schema, and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with no output schema, the description fully enumerates what will be returned. There are no required inputs, side effects, or alternatives that need explanation, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the schema to document. The description adds value by enumerating the kinds of results the agent should expect, which is the only semantic dimension available here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with the verb "Returns" and names the exact resources: credit balance, reserved holds, available credits, and per-verb usage. This clearly distinguishes it from all listed sibling tools, none of which target credit or usage data.
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 makes the tool's context clear: call it when you need credit balance, holds, available credits, or 30-day per-verb usage. It does not explicitly name alternatives or exclusions, but no sibling tool competes for this purpose, so the usage context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Launch a draft campaign so real emails begin sending. An unconfirmed request returns a preview, confirmation_token, approval_url, and removed counts from the launch-time recipient recheck. After a person approves, Layrcake runs it itself when the result's approval block says execution: server (a launch starts at its first-send time); otherwise, repeat the call with that token and a stable idempotency_key. Repeating is always safe and never runs it twice. Calling again without a token while the same request is still waiting for a decision returns that approval and sends no second email; after it was declined, expired or cancelled, calling again without a token asks again with a new confirmation_token. Requires active sending capacity and campaign:launch. Suppression and active do-not-contact entries are rechecked and provider removals fail closed before activation. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| supersedes | No | The confirmation_token of the approval this request replaces. Needed only when that approval was already approved and hasn't started yet; one still waiting for a decision is replaced automatically. Only where Layrcake runs approved actions itself (the result's approval block says execution: server); anywhere else it is refused. A dry run doesn't check it, so it refuses it: send it on the call itself. | |
| campaign_id | Yes | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| daily_send_limit | No | ||
| confirmation_token | No | ||
| first_send_not_before | No | The earliest the first emails may go out (ISO 8601). They start at the first sending-window opening at least 60 minutes after a person approves, and not before this time. It can't be later than the approval's lifetime after this request (7 days by default); a later time is refused. Only where Layrcake runs approved actions itself (the result's approval block says execution: server); anywhere else it is refused. A dry run doesn't check it, so it refuses it: send it on the call itself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare idempotentHint: false, but the description says 'Repeating is always safe and never runs it twice' and describes an idempotency_key preventing double execution. That directly contradicts the annotation. Although the description otherwise adds useful approval, permission, and fail-closed context, the contradiction forces the minimum score.
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 long but front-loaded with the core action and dense with operational detail. Most sentences earn their place, though the idempotency and approval repetition details could be tightened without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, approval-gated launch tool with no output schema, the description covers the return preview, confirmation_token, approval_url, removed counts, and execution-mode branching. It still leaves daily_send_limit and supersedes under-explained, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 43%, so the description must compensate. It adds meaning for dry_run and the confirmation_token/idempotency_key workflow, but it omits guidance for daily_send_limit, campaign_id, and supersedes semantics, leaving several parameters dependent on the schema alone.
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: 'Launch a draft campaign so real emails begin sending.' It clearly separates the launch action from sibling tools such as create_campaign, and an agent can identify the operation 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 gives clear context for when to call the tool, including the approval flow, dry_run for advisory estimates, and repeating with a confirmation token when server-side execution is not available. It does not name explicit sibling alternatives or state when not to use the tool, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One picture of a person, a company, or both, for goal-style asks: who to contact, how to approach them, angles, what's changed, and why now. Optional audience (3–2,000 characters) orders why_now for your goal when checks are available; otherwise dated reasons remain newest first. ranking.by discloses goal or recency; ranking.why_now_judged counts judged reasons at the front of the top 20. Judged-no reasons leave only why_now; datapoints, claims and facts remain. The goal changes neither parts, budget admission nor charges. depth quick = verified contact and current intent signals; standard adds the company profile and funding and source-backed research; deep adds the person's recent LinkedIn posts and deep research. Returns an operation_id to poll with get_operation using the same data:read scope; the finished result has typed datapoints, research claims that each cite a source and a verbatim excerpt, why_now, every component's status with its reason, and the exact cost. Reserves the planner's maximum once and settles once: each completed component at its own verb's price plus a 3-credit assembly fee when data is returned. Eligible pooled research is selected during execution and costs 40% of its equivalent fresh component, so the discount may or may not apply after a dry-run quote; the quoted maximum never increases. An ambiguous provider outcome keeps the whole parent reservation held for operator reconciliation. budget_credits skips components that do not fit, in order, and refuses below the minimum. dry_run: true returns the plan and maxima as of evaluated_at with nothing reserved. idempotency_key is required; reuse it only to retry creation of the same picture.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | standard | |
| person | No | ||
| dry_run | No | ||
| audience | No | ||
| budget_credits | No | ||
| company_domain | No | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| idempotency_key | Yes | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring destructive/idempotent/open-world, the description still adds substantial behavior: reservation of the planner maximum and single settlement, the 3-credit assembly fee, the 40% pooled-research discount and its uncertainty after a dry-run, the ambiguous-provider holds, budget_credits skipping order, and the fact that reuse of idempotency_key is only for retrying the same creation. That is far beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is well front-loaded and the depth tiers are clear, but the middle is a dense run of cryptic clauses ('ranking.why_now_judged counts judged reasons at the front of the top 20', 'Judged-no reasons leave only why_now') that reference fields never defined in the schema. Information is high-value but packed into overlong sentences with weak 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?
No output schema exists, and the description compensates by describing the finished result (typed datapoints, source-cited research claims with verbatim excerpts, why_now, per-component status, exact cost) and the operation_id/get_operation polling flow with the same data:read scope. It is essentially complete for this complexity, though the undefined ranking fields and nested person/company input semantics leave small gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 29%, so the description carries real weight: it explains what quick/standard/deep each add, that audience (3-2,000 chars) reorders why_now, that budget_credits skips non-fitting components and refuses below the minimum, and that dry_run reserves nothing. It leaves the person vs. company_domain object semantics (which identifiers are required, precedence when both are supplied) largely unexplained.
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 composite resource ('One picture of a person, a company, or both') and enumerates the outputs it produces (who to contact, angles, why now), so an agent can tell it is a research/assembly tool rather than a raw lookup. It never names the sibling tools it overlaps with (enrich, research_company, find_intent), so differentiation is inferred rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by 'for goal-style asks' and by the depth tiers (quick/standard/deep) plus dry_run, which tells the agent how to scope a call. There is no explicit when-to-use-this-vs-alternatives guidance, no prerequisites, and no statement of when a cheaper sibling should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a real email in an inbound reply's existing thread from the mailbox that received it. An unconfirmed request returns a preview, confirmation_token, and approval_url. After a person approves, Layrcake runs it itself when the result's approval block says execution: server (a launch starts at its first-send time); otherwise, repeat the call with that token and a stable idempotency_key. Repeating is always safe and never runs it twice. Calling again without a token while the same request is still waiting for a decision returns that approval and sends no second email; after it was declined, expired or cancelled, calling again without a token asks again with a new confirmation_token. Requires reply:send, which is not granted by default. Refuses while any reply from this sender is pending or unavailable; wait until get_reply shows its interpreted_intent. Only one reply is allowed per inbound message; suppressed contacts are refused, and sender and subject are derived. operation_unknown_state includes an operation_id whose status is available from get_operation. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| reply_id | Yes | ||
| body_text | Yes | ||
| supersedes | No | The confirmation_token of the approval this request replaces. Needed only when that approval was already approved and hasn't started yet; one still waiting for a decision is replaced automatically. Only where Layrcake runs approved actions itself (the result's approval block says execution: server); anywhere else it is refused. A dry run doesn't check it, so it refuses it: send it on the call itself. | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| confirmation_token | No |
Source-backed research on one company, for goal-style asks: angles, what's changed, how to approach it, why now. Recent news and identity searches (deep adds the homepage and up to three same-origin pages) are rewritten into typed claims (what it sells, customers, funding, hiring, leadership, partnerships, expansion) that each cite a source URL and a verbatim excerpt; why_now lists the recent dated ones. Optional audience (3–2,000 characters) ranks claims for your goal when goal checks are available; otherwise extraction order and the date rule apply. ranking.by discloses goal or recency, ranking.judged counts claims judged, and ranking.why_now_judged counts the judged reasons at the front of why_now; the rest are dated only. Judged no reasons leave why_now but remain in claims. The goal changes neither the price nor the workspace research cache. Returns an operation_id to poll with get_operation using the same data:read scope (a fresh cache hit arrives already completed with its result). Reserves the planner's maximum (standard: the research price; deep adds per-page reads) and settles the components actually used. An ambiguous provider outcome keeps that reservation held for operator reconciliation. budget_credits trims deep page reads to fit and refuses below the standard minimum. dry_run: true returns the plan as of evaluated_at with nothing reserved. idempotency_key is required; reuse it only to retry creation of the same research.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | standard | |
| dry_run | No | ||
| audience | No | Optional goal for ranking facts. Always accepted; when checks are off or unavailable, extraction order and the date rule apply, disclosed by ranking. Charges are unchanged. | |
| budget_credits | No | ||
| company_domain | Yes | Company website domain or URL, e.g. acme.com or https://www.acme.com/about | |
| idempotency_key | Yes | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: reservation/settlement mechanics, cache behavior ('a fresh cache hit arrives already completed'), the data:read scope needed for polling with get_operation, the held reservation on ambiguous provider outcomes, and idempotency retry semantics. The annotations (destructive/readOnly/openWorld) are consistent with the spend-and-external-call model described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, but the middle is dense internal jargon ('ranking.judged counts claims judged', 'ranking.why_now_judged counts the judged reasons at the front of why_now') that is hard to parse and partially duplicates the audience parameter's schema description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns and does so: typed claims with source URL and verbatim excerpt, why_now, ranking fields, and an operation_id to poll. The claim object's structure is only sketched, but an agent has enough to call and interpret the result.
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 only 50%, and the description compensates: it defines what deep adds, the 3–2,000 character audience constraint (absent from the schema), how budget_credits trims and refuses below the standard minimum, and what dry_run returns. It adds less for company_domain, which the schema already documents well.
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 ('Source-backed research on one company') and specifies the flavor of ask it serves (goal-style: angles, what's changed, how to approach, why now). It never names or contrasts with the close siblings (enrich_company, check_companies, find_companies), so an agent must still infer which company tool to pick.
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 clear context for use ('for goal-style asks', recent news + identity searches, deep for homepage/same-origin pages) and describes the dry_run and budget_credits paths. It stops short of explicit exclusions or naming the alternative tools to use when the ask is not goal-style.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a campaign lead's interest status (free, idempotent): interested, meeting_booked, won, not_interested, out_of_office, or neutral. Accepts the campaign_lead_id exposed by get_reply. not_interested irreversibly suppresses the contact from future campaigns in the workspace and removes them from active campaigns. The status is mirrored to the sending provider in the background; provider_sync_status reports pending, synced, failed, or unsupported. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| dry_run | No | ||
| idempotency_key | Yes | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| campaign_lead_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructive/idempotent/openWorld, but the description adds far more: it flags the irreversible suppression and removal from active campaigns on not_interested, the background mirroring to the sending provider with provider_sync_status outcomes, and that dry_run reserves nothing and may diverge from a real run. This is exactly the destructive/async behavior an agent needs and cannot infer from 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?
Information-dense and front-loaded — the destructive consequence of not_interested and the dry_run caveat each get a clause without filler. Sentences are long and pack multiple facts, so it is slightly heavier than ideal, 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 destructive, provider-syncing mutation with no output schema and thin schema descriptions, the description covers side effects, async status reporting, and dry-run behavior well. It omits auth/permission requirements and the mechanics of the required idempotency_key, so it is strong but not exhaustive.
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 only 25% (only idempotency_key is described), so the description must carry weight: it enumerates the status values and explains dry_run's advisory, no-reservation semantics. It does not clarify idempotency_key's reuse requirement or campaign_lead_id format, leaving a partial gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Record a campaign lead's interest status') and enumerates the exact enum values, so the agent knows precisely what operation this is. It also ties the tool to the sibling get_reply as the source of campaign_lead_id, distinguishing it from other lead-related 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 concrete usage context: take campaign_lead_id from get_reply, and use dry_run:true to get an advisory estimate without committing. It never names an alternative tool or an explicit when-not-to-use condition, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision warmed sending capacity (domains, mailboxes, DNS and warmup). An unconfirmed request returns a free quote, confirmation_token, and approval_url. After signed-in human approval, a request with that token and a stable idempotency_key executes the purchase. Requires assets:purchase. Successful execution returns an operation_id whose status is available from get_operation. dry_run: true returns an advisory estimate as of evaluated_at, reserves nothing, and may differ from a later execution plan.
| Name | Required | Description | Default |
|---|---|---|---|
| sender | No | ||
| dry_run | No | ||
| brand_hint | No | ||
| approval_url | No | ||
| emails_per_week | Yes | ||
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. | |
| prefer_prewarmed | No | ||
| confirmation_token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false) by disclosing the required assets:purchase scope, the human-approval gate, the side-effect-free nature of dry_run, and that the operation_id status is retrievable via get_operation. The 'stable idempotency_key' retry guidance is compatible with idempotentHint=false, since deduplication depends on the caller supplying the same key.
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, front-loaded with the purpose and then the quote/approve/execute flow, with dry_run's caveat last. Dense but every sentence carries operational information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter, nested-object, no-output-schema tool this covers the risky parts well: the approval flow, permission requirement, what dry_run returns, and how to poll the resulting operation. The remaining gap is that several input parameters (sender, brand_hint, prefer_prewarmed) are left entirely unexplained.
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 only 13% (just idempotency_key), so the description must compensate. It meaningfully explains dry_run, confirmation_token, approval_url, and idempotency_key, but says nothing about sender, brand_hint, prefer_prewarmed, or the 50–50000 emails_per_week bounds, leaving half the parameters undocumented.
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 concrete verb and resource ('Provision warmed sending capacity') and enumerates what is provisioned (domains, mailboxes, DNS, warmup). This is clearly distinguishable from every sibling, which are search, enrichment, and campaign 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?
Explicitly lays out the two-phase workflow: an unconfirmed request yields a quote plus confirmation_token/approval_url, and only a signed-in human approval followed by a request carrying that token executes the purchase. It also states exactly when to use dry_run:true (advisory estimate, reserves nothing) versus a real execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the deliverability of one email address (two-stage check incl. catch-all analysis). Returns status valid|invalid|catch_all_valid|catch_all_unknown|unknown|risky and is_catch_all_domain. Costs credits per call. budget_credits is a spend ceiling, never permission to use a dearer source: above it, the call is refused before anything is reserved. dry_run: true returns the plan instead (the most the call can cost, how many sources could answer, and each limit it would trip) with nothing looked up, reserved or charged.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| dry_run | No | Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason. | |
| budget_credits | No | Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason. | |
| idempotency_key | No | A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly=false, destructive=true, openWorld=true, idempotent=false); the description goes well beyond them by disclosing that each call costs credits, that an over-ceiling call is refused before anything is reserved, and that dry_run looks nothing up, reserves nothing and charges nothing. This is exactly the kind of cost-and-side-effect context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and return values are front-loaded in the first sentence, followed by cost and dry_run mechanics. The prose is dense and semicolon-chained but every clause carries operational information; only the dry_run restatement is mildly redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the status values and is_catch_all_domain, and it covers cost/refusal behavior for a paid external call. It omits only minor matters such as how long results are cached or whether re-verification is needed, which the idempotency_key schema text partially covers.
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 75% and the schema already spells out dry_run, budget_credits and idempotency_key in detail. The description largely restates those definitions (ceiling-not-permission, dry_run plan contents) rather than adding new meaning, so it sits at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Verify the deliverability of one email address') plus the method ('two-stage check incl. catch-all analysis'), and even names the exact return vocabulary. No sibling in the list does email verification, so an agent can route to it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose (verify a single address before relying on it) and the dry_run clause hints at a preview-before-spend workflow, but the description never says when to prefer this over enrich/check_companies/find_leads or when not to call it. No explicit alternatives or exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
find_companies2 fields changedInput schema / properties / exclude_keywordsAdded value: +{
+ "description": "Only with mode firmographic: up to 10 phrases, for example \"recruitment agency\" or \"consultancy\". Companies whose own description mentions any of them are left out. Each company then comes back with its description. Where exclude_keywords aren't available to this key yet, a request that sets them is refused with the reason.",
+ "items": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 20,
+ "type": "array"
+}Input schema / properties / keywordsAdded value: +{
+ "description": "Only with mode firmographic: 1 to 10 phrases, for example \"carbon accounting\" or \"dental practice management\". A company matches when its own description, products or specialties mention any of them; with keywords, industries may be left out. Each company then comes back with its description. Where keywords aren't available to this key yet, a request that sets them is refused with the reason.",
+ "items": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 20,
+ "type": "array"
+}add_leads1 field changedInput schema / properties / leads / items / properties / locationAdded value: +{
+ "maxLength": 200,
+ "type": "string"
+}create_campaign1 field changedInput schema / properties / leads / items / properties / locationAdded value: +{
+ "maxLength": 200,
+ "type": "string"
+}add_leads1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."check_companies1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."create_campaign1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."enrich2 fields changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."Input schema / properties / want / descriptionPrevious value: -"What to look up. work_email and profile run the email lookup (5 credits on a hit), which returns a mobile number too when its source has one. mobile_phone also runs a separate mobile search when the email lookup found none: 15 credits when that search finds one, 5 when the mobile came with the email, nothing when no mobile is found; a mobile_phone-only request that finds only an email is free and returns nothing. Where this isn't applied for your key yet, every call runs the same email lookup whatever this lists."New value: +"What to look up. work_email and profile run the email lookup (5 credits on a hit), which returns a mobile number too when its source has one. mobile_phone also runs a separate mobile search when the email lookup found none: 17 credits when that search finds one, 5 when the mobile came with the email, nothing when no mobile is found; a mobile_phone-only request that finds only an email is free and returns nothing. Where this isn't applied for your key yet, every call runs the same email lookup whatever this lists."enrich_company1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."find_companies1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."find_intent1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."find_leads1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."find_posts1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."get_replies1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."get_reply1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."launch_campaign1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."prospect_picture1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."reply_to_thread1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."research_company1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."set_lead_status1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."setup_sending1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."verify_email1 field changedInput schema / properties / idempotency_key / descriptionPrevious value: -"Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."New value: +"A payment_required refusal means services are stopped for unpaid billing; direct the owner to the billing link in the error. Campaigns stay paused after payment until restarted. Optional for search and enrichment tools: supply one so a retry returns the original result without paying again; if that call failed with provider_unavailable, rate_limited or insufficient_credits (after a top-up), a retry runs it once more after its cooldown (30 s, or a longer retry_after_seconds; insufficient_credits as soon as the balance covers it), unless its provider may already have done the work. Required for tools that create an external side effect; reuse the same value after a timeout or an approval. A stored failure comes back with details.replayed: true; with retry_after_seconds, retry the same value after that."create_campaign1 field changedInput schema / properties / sending_window / properties / timezone / enumPrevious value: -[
- "Etc/UTC",
- "Etc/GMT+12",
- "Etc/GMT+11",
- "Etc/GMT+10",
- "America/Anchorage",
- "America/Dawson",
- "America/Creston",
- "America/Chihuahua",
- "America/Boise",
- "America/Belize",
- "America/Chicago",
- "America/Bahia_Banderas",
- "America/Regina",
- "America/Bogota",
- "America/Detroit",
- "America/Indiana/Marengo",
- "America/Caracas",
- "America/Asuncion",
- "America/Glace_Bay",
- "America/Campo_Grande",
- "America/Anguilla",
- "America/Santiago",
- "America/St_Johns",
- "America/Sao_Paulo",
- "America/Argentina/La_Rioja",
- "America/Araguaina",
- "America/Godthab",
- "America/Montevideo",
- "America/Bahia",
- "America/Noronha",
- "America/Scoresbysund",
- "Atlantic/Cape_Verde",
- "Africa/Casablanca",
- "America/Danmarkshavn",
- "Europe/Isle_of_Man",
- "Atlantic/Canary",
- "Africa/Abidjan",
- "Arctic/Longyearbyen",
- "Europe/Belgrade",
- "Africa/Ceuta",
- "Europe/Madrid",
- "Europe/Sarajevo",
- "Africa/Algiers",
- "Africa/Windhoek",
- "Asia/Nicosia",
- "Asia/Beirut",
- "Africa/Cairo",
- "Asia/Damascus",
- "Europe/Bucharest",
- "Africa/Blantyre",
- "Europe/Helsinki",
- "Europe/Istanbul",
- "Asia/Jerusalem",
- "Africa/Tripoli",
- "Asia/Amman",
- "Asia/Baghdad",
- "Europe/Kaliningrad",
- "Asia/Aden",
- "Africa/Addis_Ababa",
- "Europe/Kirov",
- "Europe/Astrakhan",
- "Asia/Tehran",
- "Asia/Dubai",
- "Asia/Baku",
- "Indian/Mahe",
- "Asia/Tbilisi",
- "Asia/Yerevan",
- "Asia/Kabul",
- "Antarctica/Mawson",
- "Asia/Yekaterinburg",
- "Asia/Karachi",
- "Asia/Kolkata",
- "Asia/Colombo",
- "Asia/Kathmandu",
- "Antarctica/Vostok",
- "Asia/Dhaka",
- "Asia/Rangoon",
- "Antarctica/Davis",
- "Asia/Novokuznetsk",
- "Asia/Hong_Kong",
- "Asia/Krasnoyarsk",
- "Asia/Brunei",
- "Australia/Perth",
- "Asia/Taipei",
- "Asia/Choibalsan",
- "Asia/Irkutsk",
- "Asia/Dili",
- "Asia/Pyongyang",
- "Australia/Adelaide",
- "Australia/Darwin",
- "Australia/Brisbane",
- "Australia/Melbourne",
- "Antarctica/DumontDUrville",
- "Australia/Currie",
- "Asia/Chita",
- "Antarctica/Macquarie",
- "Asia/Sakhalin",
- "Pacific/Auckland",
- "Etc/GMT-12",
- "Pacific/Fiji",
- "Asia/Anadyr",
- "Asia/Kamchatka",
- "Etc/GMT-13",
- "Pacific/Apia"
-]New value: +[
+ "Europe/London",
+ "Europe/Dublin",
+ "Europe/Paris",
+ "Europe/Berlin",
+ "America/New_York",
+ "America/Denver",
+ "America/Phoenix",
+ "America/Toronto",
+ "Australia/Sydney",
+ "Asia/Singapore",
+ "Etc/UTC",
+ "Etc/GMT+12",
+ "Etc/GMT+11",
+ "Etc/GMT+10",
+ "America/Anchorage",
+ "America/Dawson",
+ "America/Creston",
+ "America/Chihuahua",
+ "America/Boise",
+ "America/Belize",
+ "America/Chicago",
+ "America/Bahia_Banderas",
+ "America/Regina",
+ "America/Bogota",
+ "America/Detroit",
+ "America/Indiana/Marengo",
+ "America/Caracas",
+ "America/Asuncion",
+ "America/Glace_Bay",
+ "America/Campo_Grande",
+ "America/Anguilla",
+ "America/Santiago",
+ "America/St_Johns",
+ "America/Sao_Paulo",
+ "America/Argentina/La_Rioja",
+ "America/Araguaina",
+ "America/Godthab",
+ "America/Montevideo",
+ "America/Bahia",
+ "America/Noronha",
+ "America/Scoresbysund",
+ "Atlantic/Cape_Verde",
+ "Africa/Casablanca",
+ "America/Danmarkshavn",
+ "Europe/Isle_of_Man",
+ "Atlantic/Canary",
+ "Africa/Abidjan",
+ "Arctic/Longyearbyen",
+ "Europe/Belgrade",
+ "Africa/Ceuta",
+ "Europe/Madrid",
+ "Europe/Sarajevo",
+ "Africa/Algiers",
+ "Africa/Windhoek",
+ "Asia/Nicosia",
+ "Asia/Beirut",
+ "Africa/Cairo",
+ "Asia/Damascus",
+ "Europe/Bucharest",
+ "Africa/Blantyre",
+ "Europe/Helsinki",
+ "Europe/Istanbul",
+ "Asia/Jerusalem",
+ "Africa/Tripoli",
+ "Asia/Amman",
+ "Asia/Baghdad",
+ "Europe/Kaliningrad",
+ "Asia/Aden",
+ "Africa/Addis_Ababa",
+ "Europe/Kirov",
+ "Europe/Astrakhan",
+ "Asia/Tehran",
+ "Asia/Dubai",
+ "Asia/Baku",
+ "Indian/Mahe",
+ "Asia/Tbilisi",
+ "Asia/Yerevan",
+ "Asia/Kabul",
+ "Antarctica/Mawson",
+ "Asia/Yekaterinburg",
+ "Asia/Karachi",
+ "Asia/Kolkata",
+ "Asia/Colombo",
+ "Asia/Kathmandu",
+ "Antarctica/Vostok",
+ "Asia/Dhaka",
+ "Asia/Rangoon",
+ "Antarctica/Davis",
+ "Asia/Novokuznetsk",
+ "Asia/Hong_Kong",
+ "Asia/Krasnoyarsk",
+ "Asia/Brunei",
+ "Australia/Perth",
+ "Asia/Taipei",
+ "Asia/Choibalsan",
+ "Asia/Irkutsk",
+ "Asia/Dili",
+ "Asia/Pyongyang",
+ "Australia/Adelaide",
+ "Australia/Darwin",
+ "Australia/Brisbane",
+ "Australia/Melbourne",
+ "Antarctica/DumontDUrville",
+ "Australia/Currie",
+ "Asia/Chita",
+ "Antarctica/Macquarie",
+ "Asia/Sakhalin",
+ "Pacific/Auckland",
+ "Etc/GMT-12",
+ "Pacific/Fiji",
+ "Asia/Anadyr",
+ "Asia/Kamchatka",
+ "Etc/GMT-13",
+ "Pacific/Apia"
+]check_companiesprospect_picture1 field changedInput schema / properties / audienceAdded value: +{
+ "type": "string"
+}find_posts2 fields changedInput schema / properties / budget_credits / descriptionPrevious value: -"Leads mode only: a spend ceiling in credits; leads beyond it come back not_processed."New value: +"Leads mode, or engagers_of with read_all: a spend ceiling in credits. Leads beyond it come back not_processed; read_all reads people up to it."Input schema / properties / read_allAdded value: +{
+ "const": true,
+ "description": "Engagers mode: read everyone who engaged, not a sample, in the background (about 2 minutes per 500 people). Needs budget_credits and idempotency_key. Returns an operation: poll get_operation, which returns the people 25 at a time with next_cursor.",
+ "type": "boolean"
+}find_posts5 fields changedInput schema / properties / author_filter / descriptionAdded value: +"Engagers mode: keep only people whose headline contains one of these words, e.g. [\"head of sales\", \"VP sales\"]. Each person read costs a small scan fee; Reddit and Facebook are skipped (no headlines)."Input schema / properties / budget_credits / descriptionAdded value: +"Leads mode only: a spend ceiling in credits; leads beyond it come back not_processed."Input schema / properties / engagers_of / descriptionAdded value: +"Engagers mode: up to 5 post URLs (LinkedIn, X, Reddit, Facebook). Returns the people who reacted, commented, replied or reposted. Send no query, platforms, intent or audience."Input schema / properties / leads / descriptionAdded value: +"Leads mode: people from find_leads or enrich. Returns each one's best recent reason to reach out (own post, comment, reaction or company post). LinkedIn only: send no query, platforms or intent."Input schema / properties / per_post / descriptionAdded value: +"Engagers mode: up to this many people from each source (reactions, comments, replies) of each post."find_posts2 fields changedInput schema / properties / audienceAdded value: +{
+ "type": "string"
+}Input schema / properties / intent / enumPrevious value: -[
- "pain",
- "question",
- "any"
-]New value: +[
+ "pain",
+ "question",
+ "any",
+ "competitor_complaint",
+ "hiring_for_it"
+]find_posts3 fields changedInput schema / properties / author_filterAdded value: +{
+ "items": {
+ "type": "string"
+ },
+ "maxItems": 10,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / engagers_ofAdded value: +{
+ "items": {
+ "format": "uri",
+ "type": "string"
+ },
+ "maxItems": 5,
+ "minItems": 1,
+ "type": "array"
+}Input schema / properties / per_postAdded value: +{
+ "maximum": 50,
+ "minimum": 1,
+ "type": "integer"
+}find_posts1 field changedInput schema / properties / leads / maxItemsPrevious value: -10New value: +1000get_operation1 field changedInput schema / properties / cursorAdded value: +{
+ "description": "For operations whose results come in pages: the next_cursor from the previous page.",
+ "pattern": "^\\d{1,7}$",
+ "type": "string"
+}
Add one secure layer between your agents and this server.