MisarReach MCP Server

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

Beyond the readOnly/idempotent annotations, it discloses data provenance ('learned only from addresses that were verified deliverable'), the response shape (per-pattern share and confidence level), and the edge case of returning 'not published' when evidence is thin. This is exactly the behavioral context annotations cannot carry.

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

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

Three compact sentences, front-loaded with what the tool returns followed by provenance and the fallback case. Every clause earns its place, though 'Free.' is slightly fragmentary.

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 beyond safety hints, the description still explains what comes back (patterns, shares, confidence) and what happens when data is absent, so an agent needs nothing further to call it correctly.

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

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

Schema description coverage is 100% and the single 'domain' parameter is fully documented in the schema, including that a full URL is reduced to its domain. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

The description names the exact resource and scope: the email address format a company uses, keyed by domain. An agent can immediately distinguish it from verify_email/verify_emails, which check deliverability rather than infer patterns, though the description never names those siblings 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?

Usage is implied rather than stated — 'Free' signals a cheap lookup versus a paid verification call, and the 'not published' clause tells the agent when the answer will be empty, but there is no explicit when-to-use/when-not rule or named alternative.

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 the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds behavior beyond them: non-deduplicating create semantics, API-key requirement, minor-currency-unit convention, and the resulting pipeline state. This is exactly the beyond-annotations context the dimension rewards.

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, then usage, then warnings, then parameter caveats. Every sentence carries distinct information; 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?

No output schema exists, but the description states the return shape ('Returns the created deal, which enters the pipeline at the first stage'), and there are no nested objects or enums needing further explanation. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the concrete disambiguation '2500 means $25.00, not $2500' and restates the 0/USD defaults for value and currency, which materially reduces a common unit error not fully resolved by the schema text 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?

States a specific verb and resource ('Open a new deal against a lead's email address') and explicitly contrasts itself with update_deal and list_deals, so an agent can route correctly 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?

Gives explicit when-to-use ('when a conversation turns into a real opportunity worth tracking'), an explicit warning that it does not dedupe ('list_deals first if you might be duplicating'), and names the alternative for the update case ('use update_deal').

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

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

Goes well beyond the annotations: adds API-key requirement, zero credit cost, the non-deduplicating create behavior, and what the response contains ('the created list with the id that sync_lead_list needs'). Annotations cover safety/idempotency; the description covers auth, cost, and mutation semantics.

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, followed by scope caveats and operational facts; every sentence carries information. The paragraph breaks are slightly choppy but nothing is wasted prose.

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 the description compensates by describing the return payload and its downstream use. Auth, cost, ordering prerequisite, and mutation semantics are all present for a one-parameter create tool.

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

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

Schema coverage is 100% with a single documented 'name' parameter, so baseline is 3. The description adds real semantic weight about that parameter by noting that nothing deduplicates on name, which tells the agent duplicates are permitted rather than rejected.

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 ('Create a new, empty managed lead list') and distinguishes itself from siblings by explicitly contrasting with sync_lead_list (which populates/imports) and list_lead_lists. An agent can place it precisely 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 preconditions and routing: call list_lead_lists first, use sync_lead_list to actually import leads, and warns that each call creates a NEW list because nothing deduplicates by name. When-to-use and what-this-does-not-do are both stated.

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

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

Goes well beyond the annotations by disclosing the API-key requirement, that fetch_emails=true performs lookups and COSTS CREDITS, and that nothing is persisted to the account. These are cost and side-effect facts the readOnly/idempotent hints 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 sentences with zero filler; the entity scope, the sibling routing, the filter-combination rule and the cost warning are each front-loaded in their own sentence.

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 summarizes the return ('matching companies with firmographics') and covers auth, cost and persistence. Everything an agent needs to invoke this correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real semantics by explaining AND-combination of filters and the cost consequence of fetch_emails. It does not add syntax detail for query or the headcount bounds, so it is above but not far above baseline.

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

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

States a specific verb+resource ('Find COMPANIES matching firmographic criteria') and immediately scopes the entity level ('company-level discovery'). It explicitly distinguishes itself from search_leads, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use triggers (targeting organisations by industry, location, headcount, tech stack) and names the alternative plus its selecting condition ('when they want named people, use search_leads'). Also explains that filters AND together, which shapes how an agent should build a query.

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: consumes enrichment credits per call, requires an API key, updates in place and OVERWRITES existing phone/LinkedIn/seniority/company fields, does not create a record, and is idempotent in record terms but still bills on a second run. These details are consistent with destructiveHint=true and idempotentHint=true, and the credit/auth warnings are things 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, then usage ordering, then cost and mutation behavior, so an agent can stop reading early. Slightly padded by restating the no-duplication point twice ('does not create a new record' and 'running it twice does not duplicate'), which costs it the top 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?

No output schema, but the description says the updated lead is returned in place, and it covers cost, auth, overwrite semantics and idempotency for a one-parameter mutation tool. Nothing an agent needs to decide or invoke 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?

Only one parameter and schema description coverage is 100% ('Lead UUID from list_leads'), so the schema already carries the semantics. The description correctly routes the id's origin to list_leads but adds no format or constraint detail beyond that; baseline 3 applies.

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

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

States a specific verb (fill in / enrich) and resource (a saved lead's missing person and company fields) and enumerates exactly which fields are populated: seniority, department, LinkedIn, phone, company size, industry. An agent can distinguish this from search_leads, list_leads or reveal_company_contacts without opening a schema.

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

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

Explicit when-to-use: one lead at a time, after list_leads supplies the id, typically before writing outreach that needs context. It also gives a when-NOT-to: check the lead first because enriching an already-populated lead wastes credits.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds real operational context: reading never pauses or alters the run, no stop tool exists, calls cost no credits no matter the frequency, an API key is required, and an in-progress run is a normal response rather than an error. That is exactly the kind of disclosure annotations cannot express.

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

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

Front-loaded with the purpose, then the lifecycle routing, then the behavioral caveats; every sentence carries information. It is slightly longer than strictly necessary (the 'there is no tool here to stop it' and API-key notes could be trimmed), 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 single-parameter status tool with no output schema, the description covers polling cadence, side-effect profile, cost, auth, and the non-error meaning of a partial result. It does not sketch the shape of the progress/results payload, which is the one remaining gap given there is no output schema to fall back on.

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

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

Schema description coverage is 100% and the single parameter already documents itself as an 'Autopilot run UUID.' The description only restates that runId is the input, adding no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the current progress and results of one autopilot run') and scopes it to a single run, which distinguishes it from the sibling list_autopilot_runs. An agent can pick it apart from sibling status/listing tools without opening the schema.

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

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

Explicitly ties the tool to the run lifecycle: it is how you follow a run started by start_autopilot, called with the runId and spaced between polls. It stops short of saying when to prefer list_autopilot_runs or get_search_job_status, so it falls just short of full alternative coverage.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real context beyond them: no parameters, requires an API key, and the failure mode ('a disabled or unconfigured one silently delivers nothing'). It does not discuss rate limits or pagination, but for a parameterless read tool this is solid.

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

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

Front-loaded with what it does, then why it matters, then the call contract. Four short sentences, none redundant; the caveat about silent non-delivery is the highest-value sentence and appears early.

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 returned fields (enabled, credentials configured, recent delivery counts). Combined with the annotations and empty schema, 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?

Zero parameters, so the baseline is 4. The description confirms 'takes no parameters' and instead characterizes what comes back per channel, which is the relevant semantic content 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?

Specific verb 'Report' plus explicit resource: configuration, connection state and delivery stats for every outreach channel, with named channels. Easily distinguished from siblings like update_channel or get_autopilot_status.

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 when to use it ('Check this before relying on a channel') and names the concrete downstream alternative ('natural first step before update_channel, so you know the current state rather than toggling blind'). Both the trigger and the relationship to a sibling tool are explicit.

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

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

Annotations already cover safety (readOnly, idempotent, not open-world), yet the description still adds behavior the annotations cannot: the full-board/no-paging nature of the call, the API key requirement, the closed enumeration of stages, and the fact that money is returned in minor units and must be divided by 100 before display. The currency-unit warning is a genuine output-handling hazard that prevents a wrong answer.

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 one-line definition of what comes back, followed by routing guidance, then operational caveats. Every sentence carries a distinct piece of information; nothing is padding.

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

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

With no output schema in the tool definition, the description takes on the burden of describing the return: board grouped by stage with revenue totals, whole board at once, values in minor units, plus the valid stage names. Nothing an agent needs to interpret the result 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?

Only one parameter, and the schema already documents workspaceId at 100% coverage, including that it is an optional workspace UUID filter. The description adds no syntax or scoping detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get the sales pipeline as a board') and immediately characterizes the shape of the result: deals grouped by stage with revenue totals. It also names the sibling it is not (list_deals returns the same deals flat), so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit use case ('how does the pipeline look' questions, stage-by-stage review) and an explicit alternative with the condition that selects it: list_deals when you need filtering or paging, since this returns the whole board. That is exactly the when/when-not/alternative structure.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds real value beyond them: today-only scope, the API-key requirement, the explicit statement that it does not approve or undo actions, and that an empty result is normal rather than an error. It omits return format/pagination detail, so not a full 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 short paragraphs, each earning its place: purpose and contents first, scope/exclusion second, safety and edge-case semantics third. No filler or repetition 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?

With no parameters, a rich annotation set, and a description that states scope, auth, edge-case semantics, return contents, and its non-destructive nature, an agent has everything needed to call this correctly. The absence of an output schema is not a gap because the description enumerates what comes back.

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

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

The tool takes zero parameters, so per the baseline the schema carries the whole contract and there is nothing for the description to disambiguate. No parameter-related text is needed or missing.

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

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

States a specific verb and resource ('Get what the AI sales agent has done today') plus the return contents (actions taken, deals created, replies sent), and names its category ('This is the audit trail'). An agent can distinguish it from siblings like get_sales_agent_config or process_sales_agent 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 explicit context ('sanity-check its behaviour after enabling it') and an explicit exclusion ('Covers TODAY only, so it is not the tool for historical reporting'). It does not name a specific alternative tool for historical reporting, so the routing is clear but not fully resolved to a sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds value beyond that by stating the API key requirement and that the result is scoped to the authenticated account, plus the read-before-write rationale. It stops short of describing error behavior or failure modes, so it is not a full 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 short paragraphs, front-loaded with the payload the tool returns, followed by usage routing and then the behavioral notes. No sentence is padding; each one adds routing or safety 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 parameters, the description carries the burden of saying what comes back, and it enumerates the returned fields. Combined with the account scoping and API key note, 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?

The tool takes zero parameters, which is the baseline-4 case. The description explicitly confirms 'takes no parameters', which is consistent with the empty schema and leaves no ambiguity about whether filters are expected.

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 (fetch the AI sales agent's current settings) and enumerates the concrete field set returned: enabled flag, booking link, offer price, reply limits, confidence threshold. An agent can distinguish it from update_sales_agent_config and the other sibling get_* status tools at a glance.

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 names the alternative (update_sales_agent_config) and gives the two conditions that select this tool: read before updating so a single-field change doesn't clobber the rest, and check the enabled flag before expecting the agent to act. This is exactly the when-to-use/when-not guidance the dimension asks for.

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 the read-only/idempotent safety profile, and the description adds genuinely new operational context: no credit cost regardless of call count, an API key requirement, the shape of the response (run state, progress, leads so far), and the important clarification that a still-running job is a normal answer rather than an error.

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 the polling workflow, then the cost/return caveats. Every sentence carries distinct information; the slightly conversational tone about polling harder doesn't waste space because it encodes a real cost constraint.

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 the description must describe the return value, and it does — run state, progress, and leads found so far, plus the non-error status of an incomplete job. Nothing an agent needs to call and interpret this tool 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% with a single documented jobId parameter, so the schema carries the semantics. The description adds only the provenance hint that the jobId is the one 'you were given' by search_leads, which is minor added value.

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

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

States a specific verb and resource ('Poll one lead-search job for its progress and results') and immediately positions itself relative to the sibling search_leads as its companion. An agent can distinguish it from list_leads or search_leads without opening any schema.

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

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

Gives explicit when-to-use instructions: call repeatedly with the jobId returned by search_leads until the job reports finished, with a concrete cadence ('leave a few seconds between polls'). It also warns against over-polling, covering the when-not case.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety bar is covered. The description still adds genuinely new context: no credit cost, API key required, nothing is started, and results are ordered newest-first with paging. It stops short of describing output shape in depth, but that is largely redundant for a simple list tool.

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

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

Front-loaded with the core purpose, then usage, then constraints in a short paragraph. 'Reads only, costs no credits, and starts nothing' is slightly belt-and-suspenders against the annotations, but it is compact and the sentences otherwise each carry 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?

No output schema exists, and the description compensates by noting return ordering (newest first) and paging, plus auth and cost. For a read-only two-parameter list tool, an agent has everything needed to call it correctly; only the exact response field shape is unstated.

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

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

Schema description coverage is 100%, with both limit and offset documented in the schema itself, so the baseline is 3. The description only gestures at 'paging' without adding format or default details beyond what the schema already provides.

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

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

States a specific verb and resource ('List past and running autopilot runs') plus the payload dimension ('status and result summaries'). It is clearly distinguishable from the siblings start_autopilot and get_autopilot_status, both of which are named or implied.

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 says what to use it for (reviewing prior runs, checking for an in-flight run) and gives a concrete when-not plus alternative: 'For detail on one run, use get_autopilot_status.' It even names the downstream risk it guards against — a duplicate start_autopilot launch.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds valuable non-structured context: API key requirement, that a revenue summary is returned alongside, and the critical unit caveat that money is in minor units (cents) and must be divided by 100. That unit disclosure is exactly the kind of trap-avoiding detail 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 purpose and return shape, then routing to the sibling, then behavioral caveats. Every sentence carries information, though the three-paragraph layout is slightly looser than needed for a three-parameter read.

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 return (deals plus total/closed/open revenue summary) and the currency-unit gotcha. Auth and safety are covered. An agent has everything needed to call and interpret results.

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 limit/offset/status are already fully documented including defaults and max. The description only restates that filtering by status exists and that results are paged; it adds no syntax or format detail beyond 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+resource ('List deals') with the return shape ('flat, paged array... with revenue totals') and explicitly contrasts with the sibling get_pipeline ('board view with deals grouped into stages'). An agent can distinguish the two 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?

Explicit about when to use it ('when you want deals as data — to count them, filter one status, or page through many') and names the alternative tool get_pipeline for the grouped view. Nothing left 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 the read-only, idempotent, non-destructive profile, but the description adds genuinely new operational facts: no credit cost, no parameters, API key required, results scoped to the caller's account, and that an empty result means no lists exist. The only gap is return shape, which is unaddressed and there is no output schema.

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 purpose and then layers usage, cost, and scope in short sentences. The parenthetical about locally stored leads is slightly convoluted but earns its place by preventing confusion with list_leads.

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 list tool with no output schema, the description covers everything an agent needs: auth requirement, cost, scope, empty-result meaning, and the sibling it should pair with. Nothing material is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case; the description correctly states 'takes no parameters' so an agent will not hunt for filters. It adds no further parameter detail, but none is needed.

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 ('List the managed lead lists this account has created or synced') and explicitly scopes it to account-owned lists. It also distinguishes itself from the similarly-named sibling list_leads by noting the local corpus is shown there instead.

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

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

Gives concrete when-to-use triggers tied to named siblings: find a listId before sync_lead_list, or check existence before create_lead_list to avoid a duplicate. It also names the alternative for raw leads (list_leads), so the agent can route without 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds genuinely useful traits: it costs no credits, requires an API key, returns contact/company/enrichment/score fields where present, and empty pages are normal not errors. These are operational details the annotations cannot 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?

Purpose is front-loaded, then usage, then behavioral notes, in tight paragraphs with no filler sentences. Each 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, the description compensates by describing the return shape, pagination context, empty-page semantics, auth requirement, and cost. An agent has everything needed to call it correctly and interpret results.

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 four parameters are already documented in the schema. The description adds only light semantic color ('Narrow to one search job with job_id'), which does not go meaningfully beyond the schema's descriptions. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List leads already saved to the account') plus scope modifiers ('newest first, with paging and search'). It explicitly distinguishes itself from the sibling search_leads, so an agent can route 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?

Names the when ('work with leads you already have'), the when-not ('does NOT find new ones'), and the alternative with its tradeoff ('search_leads, which starts a job and costs credits'). It also gives the job_id narrowing condition. Nothing 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.

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes well beyond that: it explains the revenue-reporting side effect of resolution, the notification and deal-won webhook firing, the close-date re-stamp on repeat close, backwards/forwards movement, and the API-key requirement.

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 analogy, then layered side effects in descending importance. Four paragraphs is more than minimal but every block carries distinct information, with only mild redundancy around the closed-stage warning.

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 2-param mutation tool with destructive annotations, no output schema, and full schema coverage, the description supplies exactly the missing behavioral layer: consequences, side effects, ordering semantics, and auth. Nothing an agent needs to call it safely is absent.

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

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

Schema coverage is 100%, so dealId and the newStage enum are already documented, setting the baseline at 3. The description adds the semantic meaning that stages are unordered and movement can go backwards, which is real value beyond field names but does not change the parameter contract.

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 (move deal to a different pipeline stage) and grounds it with a concrete analogy (dragging a card). It explicitly distinguishes itself from the sibling update_deal by scoping this tool to pipeline progression vs value and notes.

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 when-condition for the risky case ('only do it when the user says the outcome is settled') and names the alternative (update_deal) with a clear division of responsibility. Nothing about selection 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.

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

Adds real value beyond the annotations: nothing is sent, saved, or attached; no API key required; output is non-deterministic ('same input yields different wording each time'); and it returns the drafted text. The non-determinism is in mild tension with idempotentHint=true, but since the tool mutates no state the hint still holds in the side-effect sense.

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 preview framing and the 'nothing is sent' constraint, then the caveats. Three short paragraphs with no filler, though the trailing-space line breaks and the API-key note make it slightly longer than strictly needed.

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 states the return ('the drafted message text') and covers safety, auth, and determinism. For a simple 3-param generative tool this is close to complete; only an indication of length/format of the draft is missing.

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

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

Schema description coverage is 100%, so the schema already documents name/role/company with lengths. The description only restates that role and company are optional, adding no format or semantic detail beyond 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?

Specific verb+resource: 'Draft a sample AI-personalised outreach message for a named person.' It immediately frames the operation as a preview rather than a send, which separates it from send_to_campaign and the many lead-mutation siblings.

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

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

Gives a clear use context ('Use it to check tone before committing to a sequence') and a precondition the agent would not otherwise guess ('The person does not need to exist as a lead'). It does not explicitly name send_to_campaign or other alternatives, so it stops short of a full when/when-not statement.

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 flag destructive and non-idempotent behavior, but the description adds value beyond them: the concrete side effects (replying to the prospect, creating a deal, booking a meeting), the fact there is no dry run or preview, that it consumes AI credits, requires an API key, and that the confidence threshold gates action. This is a rich behavioral disclosure that goes well past what the structured fields 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?

Front-loads the core purpose, then layers constraints, alternates, and warnings in short, scannable sentences. The emphasis on the credit and non-idempotency warnings is deliberate and earns its space given the destructive nature of the call.

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

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

For a single-parameter tool with no output schema, the description covers purpose, side effects, safety warnings, prerequisites, and the sibling alternative to use for read-back. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and the single parameter conversationId is fully documented in the schema, so the description adds no syntax or format detail. The phrase 'over one conversation' loosely contextualizes the parameter but is not meaningfully additive, so the baseline 3 applies.

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

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

States a specific verb and resource ('run the sales-agent pipeline over one conversation') and immediately explains the decision-plus-action nature ('decide the next action and carry it out'). It is clearly distinguishable from siblings like get_sales_agent_actions, which it explicitly contrasts.

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 when-to-use condition ('call it only when the user wants the agent to take its turn on that specific conversation') and names the alternative tool for the read-only case ('For what it has already done, use get_sales_agent_actions'). Both the trigger and the exclusion are spelled out.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description goes well beyond that by disclosing that robots.txt is obeyed, that one enrichment credit is charged only when the site publishes a contact method, and that it runs at most once per company per day. This adds valuable operational context about cost and rate limiting.

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

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

The description is three tightly written sentences. It front-loads the core purpose and return values, then appends the robots.txt and credit/rate-limit constraints. Every sentence earns its place with no redundancy or 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?

There is no output schema, but the description enumerates the returned fields: contact emails, phone number, social profiles, and tech stack. Combined with the annotation coverage for safety and openness, and the complete schema for the sole parameter, the description provides everything an agent needs to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the single parameter is fully described in the schema, including that a full URL is accepted and reduced to its domain. The description adds no additional meaning about the domain parameter, so the baseline of 3 applies.

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

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

The description states a specific verb (Read) and a specific resource (a company's own website) and enumerates what it returns: contact emails, phone number, social profiles, and tech stack. This makes the tool's purpose unmistakable, but it does not explicitly differentiate itself from sibling tools like enrich_lead or discover_companies, so it falls short of a 5.

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 saying 'Read a company's own website now' and describes the cost/rate-limit model, but it never states when to use this tool versus alternatives such as enrich_lead or search_verified_leads. There are no explicit when-not-to-use conditions either, leaving the agent to infer the appropriate context.

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

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

Goes well beyond the annotations: discloses asynchronous/background execution, that the response returns only a count, per-lead AI credit consumption, an API key requirement, that leadIds re-bills already-scored leads, and the 200-id cap. This is exactly the behavioral context annotations cannot 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?

Four short, front-loaded paragraphs, each carrying a distinct operational fact (scope selection, async behavior, cost/auth, rescore semantics) with zero 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?

No output schema exists, yet the description explains the return value (an immediate count, not scores) and the follow-up read path. Combined with cost, auth, and cap disclosure, an agent has everything needed to call this correctly.

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

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

Schema coverage is already 100%, so baselines is 3, but the description adds real meaning: jobId targets only unscored leads while leadIds rescores regardless of existing score (with billing implications), plus the 200 cap and the either/or constraint.

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 ('Queue AI qualification scoring for leads') and immediately delineates the two disjoint scopes: every unscored lead in a job, or a specific id set. This distinguishes it cleanly from scoring-adjacent siblings like enrich_lead or list_leads.

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 the mutual exclusion ('Pass jobId OR leadIds, not both'), when to prefer one over the other ('pass jobId to score only what is unscored'), and how to retrieve results afterwards ('re-read them with list_leads'). Nothing 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.

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

Adds substantial behavior beyond the annotations (which only cover readOnly/idempotent/destructive/openWorld): credit consumption on every call, one job per call, API key requirement, and the extra AI-credit spend implied by useAI. This is exactly the cost/side-effect context an agent needs before calling a non-idempotent job starter.

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 action and return value, then workflow, then usage routing, then cost caveats. Four dense sentences with no filler; the async warning is capitalized and unmissable.

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 asynchronous job-starter with no output schema, the description supplies the missing pieces: what comes back now (jobId), how to get results, and the credit/key prerequisites. Nothing needed to invoke or follow up correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully upgrades useAI by disclosing that it spends AI credits to enrich and score results as they arrive — a cost implication the schema does not state. The nested filters object gets no added semantics, keeping this short of a 5.

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

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

States a specific verb+resource ('Start an AI lead-search job') and the immediate return value ('jobId'), which is unusually precise. It differentiates itself from list_leads explicitly, but the sibling search_verified_leads (another lead-search entry point) is never mentioned, so partial sibling disambiguation.

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 the full when/when-not picture: use this for NEW leads, use list_leads for saved ones, do not retry this call to check progress, and poll get_search_job_status then list_leads with the job_id. Alternatives and the reason to avoid retrying are stated explicitly.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial context beyond that: the call blocks up to wait_seconds, can be resumed via job_id at no extra charge, consumes a billable search from the plan or wallet, and guarantees results come from real records with per-email verification status.

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, then the delivery guarantee, then the async/cost mechanics. Three dense sentences with little waste, though the parenthetical enumeration of contact channels and the two cost clauses make it slightly longer than strictly necessary.

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 present, the description does explain the return payload (leads plus each email's verification status) and the resume protocol, which covers what an agent needs to call it correctly. Pagination or limit interaction with the returned set is not addressed, leaving a small gap for a 5-property, nested-object search tool.

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

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

Schema description coverage is 100%, so every parameter (limit, query, job_id, filters and its nested keys, wait_seconds) is already documented inline; this sets the baseline at 3. The description reinforces wait_seconds and the free-resume semantics of job_id but adds no format, syntax or boundary detail the schema lacks.

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), resource (people or businesses matching a plain-language description), and a distinguishing scope constraint: only leads with a real, record-backed contact method, never generated. This sets it apart from the sibling search_leads without the agent needing to open 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?

Explains the async flow (waits up to wait_seconds; if still running, call again with the returned job_id) and states the cost condition (consumes one search from the plan allowance or wallet). It does not explicitly name when to prefer search_leads or discover_companies over this tool, so it falls short of the full when/when-not/alternatives bar.

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: it does not send or start anything itself, requires an API key, and that an existing contact with the same address is OVERWRITTEN and moved onto this list. That overwrite detail substantiates the destructiveHint=true annotation with the specific data-loss mechanism rather than merely restating it.

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

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

Four short paragraphs, front-loaded with the core action and consequence before prerequisites. Slightly more prose than strictly necessary, but each paragraph carries distinct information (purpose, consequence, failure/overwrite semantics, prerequisites).

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 covers the mutation semantics an agent needs: prerequisites, failure modes, idempotency behavior, overwrite risk, and the fact that it triggers downstream outreach. Nothing material to correctly invoking a consequential bulk-add tool 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 schema already documents listId, leadIds, and campaignId, including the 1-500 range and the default list behavior. The description largely repeats the bulk limit and adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource+scope: 'Add saved leads to a campaign's contact list in bulk, up to 500 at a time.' It also disambiguates from related actions by clarifying that it does not send messages or start the campaign, which an agent could otherwise confuse with start_autopilot.

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 context ('how leads enter an outreach sequence'), a prerequisite ('verify addresses with verify_emails first'), and a concrete failure condition (leads must belong to the authenticated account or the call fails). It routes the agent toward verify_emails and explains the consequence of ignoring that advice.

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

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

Annotations already mark destructive/openWorld/not-idempotent, and the description adds substantial context beyond them: fire-and-forget with no approval loop, real messages sent to real people, credit consumption across multiple pools, API key requirement, and the runId return. It explains side effects the annotations only gesture 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-loads the consequential warnings and the fire-and-forget nature before mechanics. Every sentence carries distinct, action-relevant information (approval, credits, API key, concurrency) 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?

For a high-stakes no-output-schema tool, the description covers the return value (runId), the monitoring path, credit/auth prerequisites, and concurrency behavior. Nothing an agent needs to call it safely 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% and the schema already documents both parameters with examples. The description adds only the framing that 'the goal text is the entire brief', which is useful but marginal against a fully documented 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?

States a specific verb+resource (start an autonomous outreach run) plus scope (agent finds, contacts and follows up on its own). It is clearly distinguished from siblings like get_autopilot_status and list_autopilot_runs, which are referenced by name for monitoring.

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 use ('only start a run when the user has explicitly asked for one') and names the alternative for tracking progress (get_autopilot_status). It also warns that each call spawns a separate concurrent run against the same goal, covering the 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 already declare idempotentHint=true and destructiveHint=false, and the description reinforces this ('sending the same verdict twice is harmless', 'rather than changing anything now'). It adds genuinely new context: an API key is required and the call costs no credits, which annotations do not 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?

Three tight sentences with the purpose front-loaded, followed by usage boundaries and behavioral facts. Slight redundancy between 'improves later output rather than changing anything now' and the later side-effect 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?

With no output schema and a full-coverage input schema, the description covers the remaining gaps an agent needs — auth requirement, cost, idempotency, and explicit non-mutation of the message and lead.

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

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

Schema description coverage is 100%, so the three parameters are fully documented in the schema itself. The description adds no syntax or format detail beyond the notion of a verdict, so the baseline of 3 applies.

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

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

Names a specific verb and resource ('Record ... feedback ... as training signal') and scopes it to an AI-generated outreach message for a lead. An agent can separate this from siblings like preview_message or send_to_campaign 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?

States explicitly when to use it ('when the user judges a drafted message') and what it is not for ('does not edit, resend, or delete the message, and it sends nothing to the lead'). The negative boundaries are exactly the ones an agent would otherwise guess wrong about.

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 destructive=true, idempotent=true, and readOnly=false, and the description reinforces and expands this: it names exactly which fields get overwritten (name, role, company, score, verification status), notes detachment from search job, clarifies re-sync refreshes rather than duplicates, and adds auth (API key) and cost (no credits) context. This is well 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?

Purpose is front-loaded and each sentence carries needed information. Slightly long, but the overwrite warning and billing note are high-value and not 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?

For a one-param mutation with no output schema, everything an agent needs is present: prerequisites, side effects, overwrite semantics, idempotency behavior, auth and cost. Nothing material is missing.

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

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

Schema description coverage is 100% and the single listId parameter is documented as coming from list_lead_lists. The description corroborates the source but adds no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: importing/syncing a managed lead list into local lead records. It clearly distinguishes itself from siblings by naming create_lead_list and list_lead_lists as its inputs, so an agent immediately knows this is the ingestion step.

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 conditions ('Run it after create_lead_list, or on any existing list from list_lead_lists') and consequences of not doing it (contacts invisible to list_leads, enrich_lead, send_to_campaign). No inference required.

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

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

Goes well beyond the annotations by disclosing real-world consequences: disabling silently stops delivery on live campaigns/autopilot runs, enabling without credentials will not work, the operation is safely repeatable, and an API key is required. This is exactly the kind of operational context models need for a destructive, side-effecting mutation.

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 imperative sentence, then consequences, then prerequisite, then constraints. Every sentence adds distinct information and none is filler.

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

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

For a 2-param mutation tool with no output schema, the description covers prerequisites, side effects, idempotency, credential caveats, and auth requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with an enum on 'channel', so the schema already documents both parameters (baseline 3). The description adds a meaningful constraint beyond the schema ('Handles one channel per call'), which reduces ambiguity about batched calls.

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 ('turn on or off') and resource ('one outreach channel'), and enumerates the exact channels (WhatsApp, SMS, push). An agent can distinguish this from siblings like get_channels_status or send_to_campaign without opening the schema.

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

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

Explicitly names a prerequisite step ('Call get_channels_status first to see where things stand') and the one-channel-per-call constraint. It stops short of stating when-not to use the tool versus alternatives, but the context is clear and actionable.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds concrete consequences beyond them: sparse update semantics ('only the fields you pass are altered'), activity-history logging per call, close-date re-stamping on repeat 'closed', notes replacing rather than appending, and removal from open pipeline revenue.

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 sibling alternative, then layered constraints. It is on the long side and a few clauses (e.g. the CRM-pipeline rationale) could compress, but nearly every sentence 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?

For a 4-parameter mutation tool with no output schema, the description covers preconditions, sparse-update behavior, side effects, unit conventions, and the semantic distinction from its closest sibling. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: 'value' is in MINOR CURRENCY UNITS (2500 = $25.00) and notes REPLACE the existing note. Those are exactly the semantics an agent would otherwise get wrong.

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

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

Opens with a specific verb and resource ('Change a deal's status, value, or notes') and immediately draws a boundary against the sibling move_deal_stage, which an agent can use to disambiguate 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?

Explicitly routes the agent: prefer move_deal_stage for pipeline movement, use this tool for value and notes. It also states the precondition (API key plus deal ownership) and warns against blind repeated calls.

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 destructiveHint=true and idempotentHint=true, so the bar is lower; the description still adds real value by explaining what enablement actually does (agent starts replying autonomously), that a wrong value takes effect immediately, that it is a partial update, and that an API key is required. 'Safe to repeat' largely restates idempotentHint but the rest is genuinely additive.

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

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

Three short paragraphs, front-loaded with the action and field list, then the risk framing, then the operational note. Efficient overall, with minor redundancy in 'Safe to repeat' echoing the idempotentHint annotation.

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-required-fields mutation with a destructive annotation and no output schema, the description covers the essentials an agent needs: partial-update semantics, immediate effect, autonomy implications, and auth requirement. It does not describe error behavior, but nothing critical is missing.

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

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

Schema description coverage is 100%, so ranges, defaults, and clear-on-null semantics are already documented per field. The description provides interpretation of intent (confidence threshold = how sure before acting, reply limits = cap on sends) but no syntax or format detail beyond 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?

States a concrete verb and resource (change the AI sales agent's settings) and enumerates the mutable surface — enabled, booking link, offer price, reply limits, confidence threshold. It also implicitly distinguishes itself from the read sibling by instructing 'Read the current config first', so an agent can tell it apart from get_sales_agent_config.

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 operating context: read current config first, only passed fields change, and the effect is immediate. It stops short of explicitly naming the alternative tool (get_sales_agent_config) or stating when-not to use this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, and the description corroborates this by disclosing two real behaviors: it consumes one verification credit and it overwrites the previous verification status on any matching lead. That side-effect and cost disclosure is genuinely additive. It does not explicitly address idempotency or the auth/permission requirements.

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, then the verdict set, then cost, then side effect — a logical order with little waste. It is slightly dense (enumerating six verdicts plus the accept_all caveat), but each 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, the description correctly supplies the full return vocabulary (valid, invalid, accept_all, webmail, disposable, unknown) and flags the ambiguous accept_all case. Combined with the credit cost and the lead-status overwrite, an agent has everything needed to call it 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?

One parameter with 100% schema description coverage, so the schema already documents 'email'. The description adds no syntax, format, or validation detail beyond what the schema says, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('Check whether one email address can receive mail') and scopes it to a single address, which implicitly distinguishes it from the bulk sibling verify_emails. An agent can tell what it does and that it operates on one address 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?

Usage is implied by the single-address scope and by the credit-cost note, but there is no explicit when-to-use/when-not guidance and no direct routing to the sibling verify_emails. The accept_all caveat ('cannot be confirmed — do not treat it as valid') is useful handling guidance rather than selection 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?

Adds substantial behavior beyond the annotations: credit consumption per address, an API key requirement, the fact that 'undeliverable' is a valid success outcome, that nothing is sent to the addresses, and that verdicts overwrite the previous verification status on stored leads. The overwrite disclosure is exactly the mutation side effect that destructiveHint=true implies, and it is consistent with the annotations.

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

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

Front-loads purpose, then usage, then cost, then side effects and return semantics — a logical order with no filler. Every sentence carries a distinct, decision-relevant 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?

Covers cost model, auth requirement, parameter exclusivity, return semantics ('deliverability verdict per address'), and the write side effect on stored leads, so the description stands in for the absent output schema. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule ('Pass either email for one or emails for a batch, not both') and the 20-item batch ceiling that the schema only states on one property. That is genuine value beyond the structured fields.

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

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

States a specific verb and resource ('Check whether email addresses are deliverable') and immediately scopes capacity ('one or up to 20 at a time'), which distinguishes it from the singular sibling verify_email. 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?

Gives an explicit when-to-use trigger ('Run this before a send to protect sender reputation') with the rationale for doing so. It does not name the sibling verify_email as the single-address alternative, leaving that routing inference to the agent, 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.