Onsa

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

Adds important behavioral details beyond annotations: returns a jobId for polling, cannot answer back, does not remove or skip leads, counts against prospect quota, and de-duplicates per workspace. These align with the destructiveHint annotation without contradicting 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?

The description is quite verbose with multiple caveats and examples, but every sentence carries relevant operational guidance. It could be trimmed slightly, but the structure is logical and scannable.

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 all necessary aspects for correct use: purpose, when to use vs alternatives, expected behavior, limitations (quota, de-dup), and how to handle the asynchronous jobId response. 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 provides clear descriptions for both campaignId and message, covering 100% of parameters. The description reinforces message examples but adds little beyond what the schema already states, so 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 clearly that it sends a message to an agent in an existing campaign and returns a jobId to poll with fetch_leads, distinguishing it from find_leads which creates a new campaign.

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 to prefer this over find_leads when the user means 'more of this' or 'not quite, adjust', and explains why find_leads is not suitable (creates a separate campaign, splits the funnel).

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

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

The description thoroughly discloses read-only behavior, polling semantics, the meaning of null agentMessage, and the lack of a reply channel. It adds substantial nuance beyond the readOnlyHint and idempotentHint annotations without contradicting them.

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

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

The description is highly informative but verbose, with repeated clarifications about null values, polling, and the agent's inability to be replied to. The opening sentence is clear, but the later paragraphs could be tightened without losing essential guidance.

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

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

The description covers the asynchronous job lifecycle, response fields, polling logic, error/edge-case handling, and next-step actions such as presenting campaignUrl. Given the output schema exists, this is complete for an agent to use 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 schema already provides 100% coverage for jobId and limit with useful descriptions. The tool description reinforces that jobId must come from find_leads and adds the default limit, providing clear guidance without redundancy.

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?

Clearly states the tool fetches status/results for a find_leads job by jobId, distinguishing it from initiating a search (find_leads) and from general campaign lead retrieval. The title and description align well and are unambiguous.

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

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

Provides explicit guidance on when to use the tool: to poll a find_leads job, interpret pending/completed states, and stop polling if the agent asks something while no leads arrive. It also instructs to relay the question and start a new find_leads. It does not explicitly contrast with get_campaign_leads, but the context is strong enough for correct selection.

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

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

The description discloses critical behavioral traits beyond annotations: it returns a jobId immediately, takes 3–10 minutes, and counts every lead against the workspace's prospect quota. It also clarifies that `limit` is a target, not a hard cap, and the search may return more. The annotations already flag destructiveHint=true and openWorldHint=true, and the description adds concrete context without contradiction.

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

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

The description is informative and front-loaded with the core purpose, then details the async flow and quota nuance. It is slightly verbose but every sentence carries necessary information. The structure is logical: purpose → workflow → parameter caveat. It could be tightened but is not padded.

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

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

Given an output schema exists, the description covers all essential aspects: the async initiation, the polling contract, the parameter semantics, and the quota impact. It provides enough detail for an agent to correctly call the tool and handle the result without ambiguity.

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?

Both parameters have full schema descriptions (100% coverage), and the description adds important semantic nuance: `limit` is a target the agent aims at, not a strict cap, and `query` is a natural-language brief with an example. This goes beyond the schema and helps the agent craft a correct invocation.

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 action ('Start a live B2B lead search') with a clear resource (Onsa's AI agent) and outcome (finds real people with LinkedIn profiles). It explicitly differentiates itself from fetch_leads by naming it as the polling step, and it is distinct from other siblings like get_campaign_leads. The purpose is unambiguous and action-oriented.

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 explains when to use this tool (to initiate a search) and provides a clear follow-up workflow: poll fetch_leads until completion. It does not explicitly list when not to use alternatives, but it names the complementary tool and the async pattern. This is sufficient guidance for an agent to select the right tool among siblings.

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

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

Beyond the readOnlyHint annotation, the description discloses exact behavior: the ICP is returned exactly as stored, uses snake_case, warns that keys may be absent ('Do not assume any key is present'), and explains the structure and meaning of fields. This goes beyond what annotations provide.

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 wordy but well-organized, front-loading the purpose and then detailing the returned structure and usage notes. Each sentence adds value, though it could be tightened without losing key information.

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

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

Given the output schema is present but generic, the description compensates by explaining the exact fields, their meanings, and how to interpret them (e.g., identifying the real scoring rules in company.critical). It also flags potential missing keys, making it complete for effective use.

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 single parameter campaignId is described with actionable guidance: 'Campaign id from list_campaigns or fetch_leads — never invent one.' This adds clear meaning beyond the schema's type/format constraints, helping the agent select valid input.

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

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

The description clearly states the tool's purpose: 'Get one campaign's details' including ICP, outreach template, and settings. It distinguishes from siblings like get_campaign_leads and get_campaign_stats by specifying what data is returned.

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 context through advice like 'Read company.critical / person.critical before proposing a refinement' and checking outreachTemplate personalization, but it does not explicitly compare with sibling tools or state when to prefer this over alternatives. Usage is more implied than explicitly guided.

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

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

The description states 'Read' and is fully consistent with the readOnlyHint and idempotentHint annotations. It adds behavioral context about return fields and the constraint that fetch_leads only works with a jobId from your own find_leads call, though it does not detail auth, rate limits, or error behavior.

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

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

Two dense sentences front-load the core verb and resource, then add targeted usage differentiators and parameter provenance. No filler or redundant wording.

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

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

Given the output schema exists, the description gives sufficient context: it describes what is returned (same fields as fetch_leads, including score and scoreExplanation), when to use the tool, and how the parameters connect to sibling tools like get_campaign_stats, list_campaigns, and fetch_leads.

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?

All three parameters are described with useful semantic context beyond the schema: campaignId must come from list_campaigns or fetch_leads and must never be invented, limit has a documented default of 50, and leadIds is optional with an example (positiveLeadIds from get_campaign_stats).

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?

Clearly states it reads leads for a given campaignId and explicitly contrasts it with fetch_leads (jobId-specific) and get_campaign_stats (aggregate reply buckets), making the tool's purpose and scope immediately distinguishable from siblings.

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

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

Explicitly tells the agent when to use this tool (for campaigns not started in this session), when not to use fetch_leads, and how to use leadIds to resolve reply buckets from get_campaign_stats. It also names the correct sources for campaignId (list_campaigns or fetch_leads) and warns never to invent one.

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

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

The description goes far beyond the readOnlyHint and idempotentHint annotations by detailing lead de-duplication, handling of null rates, the fact that scheduled counts include all queued items, and that sentiment is scored once per lead. It also notes potential misinterpretations like invitesSent exceeding leadsTotal and explains why.

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

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

The description is long but every sentence carries necessary caveats. However, it is structured as a single dense paragraph rather than using bullets or section breaks, making it harder to parse quickly. The front-loading of the core purpose followed by detailed caveats is good, but the wall of text hurts readability slightly.

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

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

Given the high complexity of the tool—multiple rates, denominator issues, null handling, and common misinterpretations—the description is exceptionally complete. It covers all edge cases, explains when counts and rates differ, and provides follow-up tool recommendations, leaving no important scenario unaddressed.

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

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

The single parameter campaignId is fully described in the schema, and the description adds the crucial guidance to source it from list_campaigns or fetch_leads and never invent one. This contextualizes the parameter beyond its type and format.

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

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

The description clearly states the tool's purpose: 'Get the outreach funnel for one campaign' and enumerates the exact metrics returned. It distinguishes itself from sibling tools like get_campaign and get_campaign_leads by focusing on counts and rates rather than details, and explicitly contrasts with list_replies.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, including directing users to list_replies for actual reply text and list_next_steps for action items. It warns against using replyPct for ranking and tells the model to interpret high replyPct with high negativePct as annoyed audience, not engagement.

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

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

The description goes beyond the readOnlyHint and idempotentHint annotations by explaining critical runtime behavior: memo: null is normal, not an error, and the memo is usually richer than scoreExplanation. This significantly aids an agent in interpreting results correctly.

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

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

The description is well-structured and mostly efficient, but there is some redundancy in repeating that most leads have no memo and that null is the common case. All content is nonetheless relevant and purposeful.

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

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

The description provides sufficient context for correct invocation: what the tool returns, when null appears, and how to fall back. Combined with the schema and sibling tool list, an agent has everything needed to use this tool effectively without missing information.

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

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

The schema already fully describes leadId with format and required status. The description adds useful sourcing context ('from any tool that returns leads'), going slightly beyond the schema and helping the agent know where to obtain the parameter 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?

The description clearly identifies the tool as retrieving the research memo for a single lead, a specific resource distinct from sibling tools like list_campaigns or get_campaign_leads. It also explains the memo's value relative to scoreExplanation, making the purpose unmistakable.

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

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

The description explicitly instructs to read the memo before calling rewrite_outreach, providing direct usage context. It also clarifies that a null memo is the common case and directs fallback to scoreExplanation, giving clear guidance on when and how to handle missing data.

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), the description explains behavior: results are newest first, limit defaults to 50, returned vs total indicates omitted campaigns, and the newest entry may be empty (leadsTotal 0). This is transparent about what the tool does and does not do.

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 a single but somewhat long paragraph. It contains no redundancy and flows logically, but it packs several distinct pieces of advice (use case, key to other tools, title caveat, empty-newest note) into one sentence run. It is still concise enough for the information conveyed.

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

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

For a simple read-only list tool with one optional parameter, the description completely covers what the tool returns (fields listed), how to interpret pagination (returned vs total), common pitfalls (generic titles, empty newest), and relations to sibling tools. Nothing an agent needs to use it effectively 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 single parameter limit is fully described in the schema and further clarified in the description ('newest first (default 50)') and the note about comparing returned vs total. The meaning and effect of the parameter are completely clear.

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

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

The description clearly states the verb 'list', the resource 'campaigns', and the scope 'in this workspace that the user takes part in, newest first'. It also differentiates from sibling tools by explaining that passing an id to get_campaign, get_campaign_leads, etc. provides details for individual campaigns, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: 'Use it to see which ICP cohorts have already been tried before proposing a new one.' It also directs users to other tools for single-campaign details and warns about generic titles from MCP searches, giving clear usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description goes well beyond this by disclosing honest limitations: Onsa does not record whether you already replied, 'replied' is a floor because it only includes sentiment-scored replies, withdrawn/unreachable invites leave no trace, sentiment is judged once per lead, and leadIds are capped at 200. This adds substantial behavioral context the agent needs to interpret results correctly.

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

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

The description is long but densely packed with actionable information. It front-loads the core purpose and usage, then moves to sibling comparisons and limitations. Every sentence earns its place; no fluff. It could be slightly tightened, but the length is justified by the number of edge cases an agent must know to use results correctly.

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

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

For a tool with many caveats and sibling relationships, the description covers everything: what it returns, how to interpret each bucket, when to use it, which alternative to prefer for replies, how to drill into lead IDs, and every known limitation. An output schema exists (not shown but indicated), so return-value format is handled. Nothing an agent needs to call and use it correctly is missing.

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

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

Schema description coverage is 100%—campaignId has a clear description ('Campaign to inspect, from list_campaigns or fetch_leads'). The tool description adds no extra parameter-level meaning; it only mentions leadIds as an output hint for a different tool. With full schema coverage, baseline 3 is appropriate; the description does not need to compensate.

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

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

The description opens with a precise statement: a ranked to-do list of what a campaign still needs from a human, and enumerates the exact buckets (replied, accepted-but-never-messaged, drafts, leads found, setup missing). This clearly distinguishes it from siblings like get_campaign_stats (numbers) and list_replies (reply specifics), so an agent can tell them apart without inspecting schemas.

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

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

Explicitly states when to call: whenever the user asks for recommendations/advice/next steps, and alongside get_campaign_stats for performance questions. It also gives a strong routing rule—'Use it before suggesting new searches'—and points to list_replies as the better source for replies, with reasoning about timestamp comparison. This is the gold standard for usage guidance.

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

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

Annotations already mark this as read-only and idempotent. The description adds valuable behavioral context beyond that: it clarifies the tool returns draft text, the lead, and scoring rationale, and explicitly states it does not send messages. No contradiction with annotations; it reinforces them with concrete details.

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

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

The description is front-loaded with the primary purpose and then provides usage and workflow guidance. Each of the five sentences contributes distinct information: what it lists, what each entry contains, how to use it, a parameter tip, and a clear note on what it does not do. No redundancy or wasted words.

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

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

Given the tool's low complexity (2 optional parameters) and the presence of an output schema, the description fully equips an agent to call it correctly. It covers the review workflow, parameter behavior, and the safe read-only nature, and even suggests reading get_lead_memo before rewriting. Nothing essential is missing.

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

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

Schema coverage is 100%, so both limit and campaignId have descriptions. The description adds a meaningful semantic hint ('Omit campaignId for the whole workspace') that goes beyond the schema, clarifying the parameter's scope. This extra guidance pushes it slightly above the baseline 3.

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

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

The description clearly states the tool lists outreach drafts awaiting human approval, using specific verbs ('list', 'review') and a defined resource (the pending-outreach queue). It distinguishes itself from rewrite_outreach and send_outreach by explicitly noting it does not send anything, and the mention of the 'a message for X is ready' queue anchors the purpose.

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

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

The description provides explicit usage guidance: use for bulk review or spotting mail-merge copy, and gives a complete workflow (read get_lead_memo, rewrite with rewrite_outreach, then send with send_outreach after approval). It also clarifies that omitting campaignId covers the whole workspace, leaving no ambiguity about when and how to invoke the 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 carry the safety profile (readOnlyHint=true, idempotentHint=true), and the description adds deep behavioral context beyond them: sentiment is written once per lead and null means UNSCORED not neutral, derived fields are structural-only and must be cross-checked, and the tool can show more replies than the funnel because unscored replies are missing from get_campaign_stats. It even warns about interpretation limits (Onsa cannot see manual LinkedIn replies). This is rich, honest disclosure of data semantics and edge cases.

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

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

The core purpose is front-loaded in the opening sentence, and every paragraph earns its place by explaining critical interpretation semantics rather than padding. It is verbose, but the density of non-obvious caveats (derived-field traps, label vs text trust) justifies the length for a tool with subtle data semantics. Slightly more prose 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?

Given an output schema covers return values and annotations cover the safety profile, the description fills every remaining gap: what the tool returns, how to interpret the three derived fields, edge cases (unscored replies, broadcasts, manual replies), and how the data relates to the funnel. Nothing an agent needs to call and interpret 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% — both campaignId and limit are documented in the schema — so the baseline is 3. The description adds real value on top by telling the agent to raise `limit` when awaitingOurReplyCount exceeds `returned`, which is behavioral guidance the schema cannot express. That pushes it above baseline.

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

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

Opens with a specific verb-plus-resource statement — 'THE ACTUAL WORDS people replied with, for every lead in this campaign that answered' — and immediately differentiates itself from the sibling get_campaign_stats by stating what that tool does not provide. An agent can distinguish this from the stats/funnel siblings without opening their schemas.

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

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

Names the alternative explicitly ('get_campaign_stats tells you HOW MANY replied') and gives a concrete trigger condition: 'Use it before you draw any conclusion about an ICP from response counts.' It also warns against trusting labels over text. Usage context is fully explicit with no ambiguity about when to select 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?

The description clearly states the destructive nature ('Replace the text'), confirms idempotence implicitly (rewriting is idempotent), and explicitly notes that the draft 'stays in the approval queue; it is not sent.' It also discloses the behavioral constraint 'Do not invent facts — use only what the lead data gives you,' and clarifies the omit-vs-null semantics for the subject parameter, all beyond what annotations provide.

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

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

The description is two sentences (plus parameter descriptions) with no redundant phrasing. The key guidance—what it does, how to use it, and what it doesn't do—is front-loaded in the first sentence, and the rest adds necessary context without bloat.

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

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

Given the tool's moderate complexity (3 parameters, one optional with nuanced omit-vs-null semantics, and cross-tool naming), the description covers purpose, usage flow, side effects (stays in queue, not sent), behavioral constraints, and parameter semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, and the descriptions add value beyond the schema. leadId is sourced from list_pending_outreach; text explains that the same string is called draftText and confirmText in other tools (preventing confusion); subject clearly distinguishes between omitting (leave untouched) and passing null (clear it). This cross-referencing and edge-case clarification elevates the parameter semantics.

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 explicitly states the tool's function: 'Replace the text of an outreach draft that is waiting for approval.' The verb 'replace' and resource 'outreach draft' are specific, and it distinguishes itself from siblings like send_outreach (which sends) and list_pending_outreach (which lists) by noting 'it is not sent by this tool.'

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

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

The description gives explicit guidance on when to use this tool: 'This is how you fix copy that reads like a mail-merge' and instructs the agent to 'get the draft and the lead's scoreExplanation from list_pending_outreach.' It also clarifies when not to use it (not for sending) and provides subject-handling guidance in the parameter description (omit vs. null).

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

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

The description richly discloses side effects: it reaches a human, queues rather than delivers immediately, is subject to daily limits, places a confirmation dialog in front of the user, and refuses mismatches without revealing the actual stored text. These details go far beyond the annotations, which only mark readOnly=false and destructive=true.

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

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

The description is front-loaded with the core action, but it is verbose and repeats safety concepts: showing the message, getting explicit approval, the confirmation dialog, and the queue behavior are each mentioned multiple times. It could be condensed without losing essential safety guidance.

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

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

Given the high-stakes nature of sending a human-facing message, the description covers all necessary context: required confirmation, behavior on mismatch, user dialog flow, queue semantics, and daily limits. No critical operational detail 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?

All three parameters are fully described in the schema, and the description adds crucial semantic detail: confirmText must be exact verbatim, confirmName must match the recipient as shown, and leadId comes from list_pending_outreach. This clarifies usage beyond the basic schema.

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

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

The first sentence clearly states the verb and resource: 'Queue an approved outreach draft for sending to a real person on LinkedIn.' It also distinguishes the tool from siblings like rewrite_outreach and list_pending_outreach by focusing on the send action.

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

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

The description explicitly instructs when to use the tool: only after showing the exact message and recipient and receiving explicit user approval. It also states when NOT to call it (after user declines/dismisses the dialog) and directs re-reading with list_pending_outreach on mismatch.

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