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

Annotations only declare the generic write/openWorld/idempotent=false profile, but the description adds substantial non-obvious behavior: no activation flag is sent, the returned status is whatever Instantly reports (normally "draft"), read-only env gating, demo mode returning simulated:true with no HTTP call, and a mandatory opt-out line in every email body. This is exactly the context annotations cannot express.

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

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

Front-loaded with purpose and safety scoping, then the two-phase workflow, then edge behaviors. Every sentence delivers operational information an agent must act on; no filler or restatement of the title.

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

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

For a mutation tool with nested objects, no output schema, and no parameter descriptions, the definition still tells the agent what is returned (Instantly's status), what is required for compliance (opt-out line), and how the confirmation cycle works. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the two most non-obvious parameters well (confirm and confirmation_token, including the token's origin and ordering), but name, steps, schedule, and sending_accounts are left to the JSON Schema constraints alone. Partial compensation for a 6-parameter tool.

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

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

States a specific verb+resource ("Create an Instantly campaign") and immediately scopes it ("never activates it"). An agent can distinguish this from sdr_push_to_campaign or sdr_save_prospects 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 an explicit two-phase protocol: call without confirm for a preview + confirmation_token, show the preview to the user, then call again with confirm=true and the token after explicit approval. It also names the conditions that change behavior (OPENSDR_READ_ONLY, demo mode), leaving nothing to inference.

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

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

Adds substantial context beyond annotations: credit consumption (~1/query, budgeted), the required EXA_API_KEY/TAVILY_API_KEY, the shape of each returned signal, and a prompt-injection warning about untrusted `excerpt` text. This is exactly the kind of operational and safety disclosure annotations cannot carry.

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

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

Front-loads what the tool returns and closes with the credit/auth constraints; dense but no filler. The integrity warning is long but justified for a tool ingesting third-party text.

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

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

With no output schema, the description compensates by naming the return fields (URL, published date, confidence, matched rule), and it covers auth, cost, and security posture for a 6-parameter networked tool.

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

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

Schema coverage is 67%; the description adds meaning for max_credits (consumes credits, budgeted) and signal_types (enumerates the categories), while remaining parameters (lookback_days, max_results_per_company, attach_to_prospects) are already documented in the schema.

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

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

Specific verb + resource ('Find ... buying signals for companies') with the enumerated signal types spelled out, so an agent can distinguish it from sdr_research_account or sdr_enrich_company 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?

The description implies usage (recent, sourced signals, budgeted, key required) but never states when to prefer this over sibling tools like sdr_research_account or sdr_enrich_company, nor any when-not condition.

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

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

Annotations only cover the generic safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false). The description adds material behavior beyond that: ~1 Apollo credit consumed per domain, a per-call budget check performed first, and result caching. These are exactly the cost/side-effect traits an agent needs before invoking a metered enrichment call.

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

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

Three sentences, front-loaded: capability and returned fields first, cost/cache behavior second, workflow placement last. None is filler; every sentence carries distinct 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 and no annotations describing behavior, the description covers purpose, returned fields, cost, caching, and workflow placement adequately. It could mention partial-failure or per-domain error handling, but it is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the '~1 Apollo credit per domain' model gives context to the max_credits cap and the 10-domain limit, and the caching statement explains force_refresh's purpose. That is useful semantics beyond the terse schema descriptions.

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

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

States a specific verb (Enrich), resource (company domains), and enumerates the returned firmographic fields (industry, headcount, location, technologies, funding) plus the provider (Apollo). It is clearly distinguishable from sibling tools like sdr_waterfall_enrich_person (person) and sdr_search_companies (search, not 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?

Explicitly positions the tool in the workflow: 'after sdr_search_people to qualify accounts, or before sdr_prepare_outreach_brief for grounded personalization,' naming both siblings. It gives clear context but stops short of explicit exclusions or a direct 'use X instead when Y' routing.

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

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

Annotations already signal readOnlyHint=false, openWorldHint=false, destructiveHint=false, but the description adds real behavioral detail: UTF-8 BOM for Excel/Sheets, RFC 4180 quoting, a formula-injection guard, suppression exclusion unless include_suppressed=true, refusal to overwrite without overwrite=true, and no upload. The overwrite-refusal behavior in particular is exactly the kind of destructive-safety contract annotations cannot express.

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

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

Five short, front-loaded sentences that each convey a distinct fact (format, selection, encoding safety, suppression default, overwrite/upload behavior). No filler or restatement of the tool name.

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

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

For a 6-parameter, no-output-schema tool with zero required params, it covers output format, safety behavior, and selection semantics well. The gap is what path and columns accept or default to, which matters for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden. It explains list, prospect_ids, overwrite, and include_suppressed semantics well, but says nothing about the path or columns parameters, leaving 2 of 6 parameters undocumented anywhere.

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

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

States a specific verb and resource ('Export prospects to a ... CSV') and immediately names the selection modes (list or prospect_ids). It is clearly distinguishable from every sibling, which list, search, enrich, or push data rather than writing a local export file.

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 when the tool applies: exporting prospects by list or by prospect_ids, with suppressed prospects excluded by default. However, it never names an alternative or a when-not condition (e.g. use sdr_list_prospects first to inspect, or that free/local means no sync occurs) beyond the implicit 'does not upload anything'.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds value beyond them by disclosing cost characteristics ("Free, local") and pagination mechanics ("opaque cursor"), which an agent needs to iterate results correctly.

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: the first front-loads the filterable dimensions, the second handles usage, cost, and pagination. No filler and nothing 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?

For a read-only, paginated query tool with no output schema, the description covers purpose, filtering, cost, and pagination adequately. It could note the default page size or the shape of the per-list summary, but no critical gap blocks correct invocation.

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

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

Schema description coverage is only 11% across 9 parameters, so the description carries much of the burden. It conceptually covers list, status, email status, company domain, search, and include_lists_summary, but omits limit, cursor semantics, and has_email, and gives no enum-value meaning for status. Partial compensation warrants a mid score.

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 (query) plus resource (saved prospects) and enumerates the filter dimensions it supports (list, status, email status, company domain, free-text search). It also names the sibling tools it precedes, so an agent can distinguish it from sdr_export_csv and sdr_push_to_campaign without inspecting schemas.

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

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

"Use it to review a list before sdr_export_csv or sdr_push_to_campaign" gives explicit usage context and names the downstream alternatives. It doesn't address when to prefer sdr_search_people over this tool (saved vs. net-new prospects), so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds cost/network context ('Free and local: no network call, no credits') and return shape ('Returns up to `limit` matches'), which is meaningful value beyond the annotations, though it stops short of error or empty-result behavior.

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

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

Three sentences, front-loaded with purpose, then cost, then workflow guidance; every sentence carries distinct information with no 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?

For a simple 3-parameter local lookup with no output schema, the description covers purpose, the full taxonomy set, zero-cost/offline behavior, workflow placement, and the shape of the result. 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by demonstrating the input-to-output mapping ('vp eng' returns 'VP Engineering'), clarifying what 'normalized' actually means for the query parameter. It does not elaborate on kind or limit beyond what the schema already states.

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

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

Specific verb (look up) plus a precisely scoped resource (normalized filter values/taxonomies), and it enumerates the six taxonomies so an agent knows exactly what it resolves. It also implicitly distinguishes itself from the search siblings by framing itself as a value-normalization utility rather than a search.

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

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

Explicitly states when to call it ('before sdr_search_people or sdr_search_companies') and the goal ('turn plain-English ICP terms into exact values'), naming the relevant siblings directly. The workflow position is unambiguous.

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

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

Adds substantial context beyond the annotations: the list is honored by every outward tool, cannot be bypassed from a tool call, is free and local, and that add is idempotent while remove needs the exact value. The annotation idempotentHint=false is a coarse tool-level hint for a four-action tool and is consistent with the non-idempotent-sensitive actions, so there is no true conflict, but the mismatch on 'add' is worth noting.

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?

Five compact sentences, front-loaded with the core purpose and the suppression semantics that matter most. Slightly telegraphic in the closing sentence 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 6-parameter, 0%-coverage, no-output-schema tool, the description covers the domain semantics well but leaves pagination (limit/cursor) and the check/list response shape undocumented, so an agent calling list or check lacks full guidance.

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 0% across 6 parameters, so the description must carry the burden. It clarifies the email/domain value types and per-action semantics for add (idempotent) and remove (exact value required), but says nothing about limit, cursor, or reason, and does not explain what list and check return.

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

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

The description names a specific resource (the do-not-contact list of emails and domains) and a specific capability set (maintain + check values against it). No sibling tool (search, enrich, verify, campaign push) overlaps this resource, so the agent can route 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?

It gives concrete triggers: 'when a prospect opts out, bounces, or asks not to be contacted.' That is clear usage context, though it does not explicitly state when NOT to use it or name an alternative path for checking suppression status.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds materially beyond that with the suppression flag convention (`suppressed: true`) and, notably, a prompt-injection warning that signal titles/excerpts are untrusted third-party text. It does not discuss rate limits or output sizing, which is why it falls short of a 5.

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

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

Three dense sentences, front-loaded with the artifact produced, then the write handoff, then the safety caveat. No filler; each sentence adds a distinct operational fact.

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 5-parameter tool with 0% schema description coverage and no output schema, the description does a good job on output contents, safety, and the save handoff — but the near-total absence of parameter guidance (tone/channels/touches semantics or defaults) leaves a real gap 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 description coverage is 0% and there are 5 parameters, so the description carries the full burden — but it never explains tone, touches (default 4, range 2-6), channels (email/linkedin_note), or the prospect_ids cap of 25. 'Seller context' and 'sequence framework' only loosely gesture at seller_context and touches/channels, leaving required semantics to inference.

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 ('Prepare') and a specific artifact ('outreach brief'), then enumerates its contents (seller context, per-prospect facts, signals, sequence framework, compliance rules). It also distinguishes itself from the write path by naming sdr_save_prospects for saving drafts, so an agent can tell it apart from siblings without opening schemas.

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

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

Makes the division of labor explicit ('It does NOT write the copy — you do') and routes the follow-up action to sdr_save_prospects with the exact field (custom_fields.first_line). It also gives a skip rule for suppressed prospects. It stops short of naming a specific alternative in sibling terms for isolating signals or research, but the context for when to call it is clear.

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

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

Beyond the annotations, which already cover read-only, non-destructive, idempotent, and non-open-world behavior, the description adds that the tool is 'Free and local: makes no network calls' and that it 'Does not reveal API key values, not even partially.' Those are meaningful extra guarantees about cost, execution locality, and secret-handling that an agent cannot infer from the annotations 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?

Three tightly packed sentences: the first lists the reported content, the second adds the free/local/no-network and secret-safety guarantees, and the third gives usage guidance and another security assurance. Every sentence earns its place, and the most important usage instruction is not buried.

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

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

There is no output schema and no parameters, so the description must carry the full burden, and it does: it enumerates the categories of information returned (providers, mode, read-only state, data directory, capability resolution, credit estimate, limits) and explicitly states the one thing it will not return (API key values). For a diagnostic status tool this is complete enough to call correctly without further context.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline for a zero-parameter tool is 4. Nothing in the description is missing on this dimension because there is nothing for the schema to document.

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

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

The description gives a specific verb (reports) and enumerates the exact resource surface: configured providers, mode, read-only state, data directory, per-capability resolution, credit estimate, and limits. It is unmistakably a diagnostic status tool and cannot be confused with the search, enrichment, or campaign siblings.

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

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

It gives clear usage context with 'Use it first to see what OpenSDR can do and which env vars are missing,' which tells the agent when this tool is appropriate. It does not name alternatives or state when-not to use it, but for a status tool with no real alternative this is still strong guidance.

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

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

Annotations already state mutating, non-idempotent, non-destructive, open-world, but the description adds far more: the draft/paused gate, the two-phase preview/confirm workflow with a token, the token-invalidation-on-change behavior, the verified-email inclusion policy and allow_unverified exception, the never-suppressed/invalid invariant, OPENSDR_READ_ONLY enforcement, and demo-mode simulated output. This is rich operational context well beyond 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, then constraints, then procedure; every clause carries information and none is filler. It is dense to the point of being a run-on block, but nothing can be dropped without losing an operative rule.

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 still tells the agent what the preview returns (campaign status, eligible vs. excluded with reasons like suppression, no email, unverified, invalid, already in campaign, over cap) and how the mutation behaves. The remaining gap is what the successful confirm returns and the role of the `list` parameter.

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

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

Schema description coverage is 0%, so the description must carry the load: it explains confirm, confirmation_token (obtained from the preview call), allow_unverified (still never permits suppressed or invalid), and campaign_id implicitly via status constraints. It does not explain the `list` parameter or how prospect_ids interact with it, leaving one of six 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?

"Enroll prospects into an existing Instantly campaign" gives a specific verb (enroll) and resource (prospects into a campaign), and the word "existing" plus the campaign-status constraint cleanly separates it from the sibling sdr_create_campaign. An agent can pick this over its siblings without inspecting 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?

Explicit when-to-use (existing campaign in draft/paused), when-not (active campaigns are rejected because they start sending), and the exact two-phase procedure with preview-then-confirm. The invalidation rule ("if any approved lead changes before confirming... preview again") closes the main usage ambiguity.

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

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

Adds substantial context beyond annotations: it discloses the return shape (raw sources with title/url/date/excerpt plus known_facts), the important boundary that it does not write prose, a security warning that excerpt is untrusted third-party text to be treated as data not instructions, and that it consumes credits and is budgeted. The readOnlyHint=false is consistent with the disclosed credit consumption, and openWorldHint=true aligns with the web-gathering behavior.

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

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

Four tightly packed sentences, front-loaded with purpose then outputs, boundaries, security, and cost. Every sentence earns its place, and the prompt-injection warning is placed appropriately after the return-format 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 usefully covers the return shape, and it addresses the credit/budget dimension for a costly open-world tool. The main gap is parameter coverage, which the 20%-covered schema does not fill, so the agent lacks guidance on max_credits/max_sources/company_name.

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 20%, so the description must carry parameter meaning, but it only gestures at 'focus area' and 'if configured' for Apollo. It never explains domain, company_name, max_credits, or max_sources (limits, defaults, or why to set them), leaving most parameters undocumented in both schema and 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?

The description names a specific verb+resource ('Gather cited source material about an account') and scopes the outputs (firmographics from Apollo, web results per focus area, known_facts from structured fields). It clearly differentiates research-gathering from other SDR operations, though it never names a sibling like sdr_enrich_company or sdr_prepare_outreach_brief to route the agent explicitly.

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

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

It states the workflow expectation ('write the dossier yourself and cite the source URLs') and flags cost behavior ('consumes credits and is budgeted'), which implies when this deep-research tool is appropriate. However, it gives no explicit when-to-use/when-not or comparison against alternatives such as sdr_enrich_company, leaving the choice to inference.

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

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

Annotations already declare idempotent, non-destructive, closed-world; the description adds genuinely new behavior: dedup keys (email, LinkedIn URL, Apollo id, name+domain), no credits/no network, and the non-obvious rule that suppressed people are still saved but flagged. This is exactly the kind of extra trait annotations cannot express.

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

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

Front-loaded purpose sentence followed by progressively finer detail (inputs, use cases, sidEEffects, next steps). Dense but every sentence carries distinct 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 a nested, 4-param write tool with no output schema, it covers input shapes, side effects, suppression, and next steps well. It leaves the merge-strategy default and any return/summary unstated, a minor gap given the schema handles parameter typing.

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

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

Schema coverage is 100% (baseline 3), but the description adds semantics the schema lacks: the dedup identity keys and the two accepted people shapes, plus the patch custom_fields.first_line example. That exceeds the schema's bare type info, though it doesn't fully explain merge or default status behavior.

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 (save or update prospects) plus scope (in a local named list) and distinguishes the two accepted input shapes. An agent can tell this apart from read/enrich siblings like sdr_list_prospects or sdr_waterfall_enrich_person without opening the schema.

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

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

Gives concrete when-to-use cases (persist drafted copy via patch custom_fields.first_line, set status/notes/signals) and routes to next tools (sdr_list_prospects, sdr_export_csv). It does not name a when-not or an alternative write path, but the usage context is clear.

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

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

Annotations cover read-only/idempotent safety, and the description adds behavior beyond them: credit consumption (~1 credit/page), budget pre-check, and the 'requires at least one filter' constraint. That is exactly the kind of cost/eligibility context annotations cannot express.

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

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

Three tight sentences: what it searches, the cost/constraint, and the workflow chaining. Front-loaded and every sentence 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?

Complete for a 10-param search tool with full schema coverage and annotations covering safety. Return-value format is not described, but no output schema exists, so a minor gap remains.

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

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

Schema coverage is 100%, so all 10 parameters are documented in the schema. The description adds a pagination usage hint ('pass it back unchanged') but no syntax or format detail beyond that. 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 (Search) and resource (companies) plus the filter dimensions. Clearly distinguishes from sdr_search_people by routing accounts to people search as a follow-up.

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 states preconditions ('requires at least one filter') and names the workflow alternatives: chain to sdr_search_people with organization_domains, or sdr_enrich_company for details. When-to-use is unambiguous.

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

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

Annotations already cover read-only, idempotent, non-destructive, open-world. The description adds real behavioral value beyond them: no-credit/free cost, the no-contact-data limitation, opaque cursor pagination, and that each person carries an apollo id. It stops short of stating rate limits or result shape.

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?

Compact set of sentences, front-loaded with purpose, then cost, limitation, constraint, pagination, and the enrichment pointer. Every sentence carries a distinct, actionable fact.

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 9-param search tool with no output schema, it covers cost, coverage limits, pagination, and the filter constraint. Return-field detail is (correctly) delegated to apollo ids and the enrichment sibling, though result shape isn't described.

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

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

Schema coverage is 100%, so the schema already documents all 9 parameters with constraints. The description adds only the cross-parameter rule (at least one filter) and the cursor round-trip contract, which is modest beyond the schema baseline of 3.

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 (search people/prospects) and enumerates the filterable dimensions. It clearly distinguishes itself from sdr_search_companies and sdr_waterfall_enrich_person.

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 hand-off: 'Does NOT return emails or phones — use sdr_waterfall_enrich_person on the people you want' and 'Use sdr_lookup_filters first'. It states the 'Requires at least one filter' constraint, routing the agent precisely.

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

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

Annotations cover safety (readOnly=false, destructive=false, idempotent=true, openWorld=true), yet the description adds substantial extra context: idempotency by email, the confirm/token gate, overwrite_existing default of fill-empty-only, suppressed exclusions, OPENSDR_READ_ONLY honoring, and demo-mode simulated:true. This is richer than the annotations 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, then layers the two-phase protocol, idempotency, defaults, and mode notes. Every sentence conveys actionable information with no filler, despite the tool's complexity.

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, so return values are handled by the demo-mode note. For a mutation tool with 8 params the workflow, defaults, and environment flags are well covered, but the semantics of list and prospect_ids remain unstated, a minor completeness gap.

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

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

With 0% schema description coverage, the description does heavy lifting: it explains confirm, confirmation_token, overwrite_existing, include_suppressed, lifecycle_stage, and the note behavior. However, the list and prospect_ids parameters are never explained, leaving part of an 8-param schema 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 precise verb+resource+keying scheme: 'Upsert prospects into HubSpot as contacts (keyed by email), with an optional lifecycle stage and a note.' This clearly separates it from siblings like sdr_push_to_campaign and sdr_save_prospects without needing their schemas.

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

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

Explicitly prescribes the when/how flow: call without confirm to preview, show the preview, then call again with confirm=true plus the confirmation_token after approval, and re-preview if any approved contact changes. It also states default behavior for overwrite_existing and suppression inclusion, so the agent knows which choices to surface.

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

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

Adds materially beyond the annotations: credit cost (1 credit each), caching behavior, and the explicit disclaimer that it does no SMTP probing and sends nothing. The annotations (readOnlyHint=false, openWorldHint=true) signal side effects, and the credit/caching disclosure complements them well.

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 purpose, then the conditional provider behavior, then return values, then a negative boundary. Four dense sentences, each carrying information with no padding.

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

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

With no output schema, the description still documents the return shape (status enum values, confidence, individual checks) and the cost/behavior of each path, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches use_provider beyond the schema's terse 'Also run the Hunter verifier' by tying it to a Hunter key requirement, the credit cost, and caching.

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?

Clear specific verb+resource: 'Check whether email addresses are deliverable,' and it enumerates the actual checks performed (syntax, MX, disposable domain, role address). This is distinct from the search/enrich siblings, though it never names an alternative explicitly to lock in the differentiation.

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

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

Gives a concrete condition for the optional path ('With use_provider=true and a Hunter key...') and states the local checks always run, plus a negative boundary ('Does not do SMTP probing or send anything'). It stops short of explicitly routing the agent against any sibling tool.

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

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

Annotations only cover read/write and open-world hints; the description goes well beyond by disclosing cost governance (paid tiers halt at budget exhaustion), the exact provider order attempted, cache-related behavior implied by force_refresh, and the response shape (status, confidence, cost `trail`). It also declares data boundaries: no email sending, no phone exposure. This is exactly the extra context the annotations cannot carry.

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

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

Front-loaded with the core action and waterfall order, then cost behavior, then return shape, then required input form, then exclusions. Four dense sentences with no filler; every clause carries operational 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 correctly compensates by explaining what each person comes back with (email status, confidence, and a trail of attempts and costs). Combined with the cost/budget semantics and identifier requirements, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it enumerates the five acceptable ways to identify a person (prospect_id, apollo_id, linkedin_url, an email, or first_name + last_name + domain) and the 1-25 cardinality, clarifying that the nested object fields are alternative identifiers rather than required together. It does not explain max_credits vs the budget narrative or verify_with_hunter's cost tradeoff in detail.

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

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

States a specific verb+resource (find and verify a work email for people) and immediately distinguishes itself from siblings by naming the mechanism: a cost-aware waterfall of Apollo -> Hunter finder -> optional Hunter verifier -> free local checks. An agent can tell this apart from sdr_verify_email (verification only) and sdr_enrich_company (companies) without opening a schema.

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

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

Gives clear context for use: supply 1-25 people, each identified by one of five identifier forms, and paid tiers stop when budget runs out. It also states explicit exclusions (does NOT send email or reveal phones), which bounds the tool. It stops short of naming an alternative tool to prefer when only verification (sdr_verify_email) or search (sdr_search_people) is needed.

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