MisarReach MCP Server

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the side-effectful nature is known. The description adds context beyond annotations: requires an API key, `value` is in minor currency units, defaults, and that the returned deal enters the pipeline at the first stage. It does not contradict any annotation and provides valuable operational detail.

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 divided into three focused paragraphs: purpose, usage guidance, and key implementation semantics. Every sentence adds value—no filler. It is front-loaded with the verb+resource statement, making it easy for an agent to quickly grasp the tool's core function.

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 create operation with 8 parameters but no output schema, the description covers essential behavioral nuances: duplicate-avoidance strategy, currency unit scale, default currency, pipeline entry, and return value. It gives enough context to use the tool safely and effectively, complementing the schema descriptions. No major gaps remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description highlights the `value` unit convention (minor currency units) and the meaning of `leadEmail` as the key, but this information is already present in the schema (e.g., 'Deal value in minor currency units', 'Lead's email address'). The description adds minimal semantic value beyond the schema, so 3 is appropriate.

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

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

The description clearly states the tool's function: 'Open a new deal against a lead's email address.' It specifies the resource (deal) and the key parameter (leadEmail). It also differentiates from sibling `update_deal` by explicitly telling the agent to use `update_deal` for modifying existing deals.

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

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

It explicitly states when to use: 'Use it when a conversation turns into a real opportunity worth tracking.' It provides a critical caution: 'it does not check for an existing one on the same email, so list_deals first if you might be duplicating.' It also names the alternative: 'To change a deal that exists, use update_deal.' This fully satisfies the when/when-not/alternatives criteria.

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

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

Annotations already set readOnlyHint=false, idempotentHint=false, etc., but the description adds substantial behavioral context: it clarifies the list is empty, does not import anything locally, each call creates a new list with no name dedup, costs no credits, and returns the created list with the id needed for sync_lead_list. This goes beyond the annotations and gives the agent a full picture.

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 concise and efficiently front-loaded. The first sentence states the purpose, subsequent sentences clarify side effects, usage sequence, and return value without any fluff. Each sentence contributes essential information, making it model-friendly.

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 low complexity (single param, no output schema) and the presence of sibling tools, the description is complete. It explains the relationship with sync_lead_list and list_lead_lists, prerequisites, costs, and the return value (the id needed by sync_lead_list). No essential context is missing.

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

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

The schema covers the only parameter (name) with a clear description ('List name (1-200 chars)') and 100% coverage, so the description doesn't need to add much. The description implies the name is the list's identifier but provides no extra semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Create a new, empty lead list') and the resource ('lead list in Hunter.io'), and distinguishes from siblings by explicitly noting that sync_lead_list handles importing and that each call creates a NEW list with no deduplication. This is a specific verb+resource with clear differentiation.

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

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

It gives explicit directives: 'Call list_lead_lists first' and explains that sync_lead_list is the tool for importing, thus telling when to use this tool vs. the alternative. It also mentions requirements (API key, connected account) and provides a critical caveat about no deduplication, offering clear context for usage.

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, openWorldHint, and idempotentHint. The description adds API key requirement, cost for fetch_emails, states no lead is saved (side effect), and mentions return of firmographics. This adds meaningful behavioral context beyond annotations, though it doesn't describe exact response format or pagination. No contradiction.

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

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

Description is front-loaded with core purpose, then usage guidance, then cost and side effects. Each sentence adds new information without fluff. Efficient and well-structured.

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 8 parameters and no output schema, the description covers key operational aspects: API key requirement, cost trigger, side effects, and return type. It doesn't mention pagination or error handling, but the limit parameter is already in schema. Adequate for the tool's complexity.

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

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

Schema covers all 8 parameters (100% coverage), so baseline is 3. The description adds semantics by explaining filter combination (AND), clarifying that headcount and technology are firmographic criteria, and warning about fetch_emails cost. This goes beyond the schema to improve parameter understanding.

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

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

The description clearly states the tool finds COMPANIES via firmographic criteria using Hunter.io, with optional email pulling. It explicitly distinguishes from search_leads by stating 'When they want named people, use search_leads,' giving a clear verb-resource and sibling differentiation.

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

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

Provides explicit when-to-use guidance ('reach for it when the user is targeting organisations...') and when-not-to ('When they want named people, use search_leads'). Also explains filter combination logic (AND) and mentions cost implications for fetch_emails, giving practical usage 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?

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds valuable extras: 'CONSUMES ENRICHMENT CREDITS per call', 'Requires an API key', and clarifies in-place update and no duplication. It also mentions returns the lead. No contradiction with annotations.

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

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

The description is two paragraphs with purpose first, then usage and cost details. It is not overly long, though could be slightly tightened. Every sentence adds necessary context (fields, usage sequence, credit consumption, return behavior).

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 simple interface (1 parameter, no output schema, annotations provided), the description adequately covers when to use, cost, side effects, and what it returns. It doesn't describe the return format, but that's not critical for this simple 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% (leadId described as 'Lead UUID from list_leads'), so description doesn't need to add much. It reinforces to use after list_leads, but does not significantly augment parameter meaning 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?

The description clearly states the tool's function: 'Fill in a saved lead's missing person and company detail' and lists specific fields (seniority, department, LinkedIn, phone, company size, industry). It distinguishes itself from siblings like list_leads or search_leads by focusing on enrichment of a single saved lead.

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

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

Provides concrete use guidance: 'Use it on one lead at a time, after list_leads has given you its id, and typically before writing outreach.' Also advises checking first to avoid wasting credits. It does not name alternative tools explicitly but frames when it's appropriate relative to lead flow.

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), the description adds valuable behavioral context: reading status does not pause or stop the run, there is no stop tool, it costs no credits however often called, requires an API key, and an in-progress response is normal. This goes well beyond structured metadata and helps the agent set expectations.

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

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

The description is front-loaded with the core purpose, then adds essential usage and behavioral notes without fluff. Every sentence earns its place, including the reassurance that in-progress is not an error.

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 simple signature, strong annotations, and no output schema, the description sufficiently covers what an agent needs: how to poll, cost implications, auth requirement, non-destructive behavior, and expected semantics for in-progress runs. No important usage gap is apparent.

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 covers runId well with 'Autopilot run UUID' at 100% coverage. The description adds practical meaning by explaining that the runId comes from a run started by start_autopilot and that polling should be spaced out, which is useful behavioral guidance for the single parameter even if not strictly required.

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 resource ('one autopilot run') and the action ('get the current progress and results'). It also distinguishes itself from siblings like list_autopilot_runs and start_autopilot by framing this as following a run started by start_autopilot with a runId.

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

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

It explicitly says when to use this tool ('This is how you follow a run started by start_autopilot'), how to use it ('call it with the runId, leaving time between polls'), and what not to do: it does not pause, stop, or alter the run, and there is no tool here to stop it. It also clarifies that an in-progress run is a normal response, not an error.

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 'Reads only, takes no parameters, and changes nothing. Requires an API key.' This adds concrete behavioral details beyond the annotations (readOnlyHint, idempotentHint), and it clarifies the return values: 'whether it is enabled, whether credentials are configured, and recent delivery counts.' No contradiction with annotations.

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

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

Three well-structured sentences: purpose, usage guidance, then safety/return summary. Every sentence earns its place with no fluff or repetition. The main verb appears first, followed by actionable context.

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 no-parameter read-only tool with no output schema, the description covers all necessary context: what it does, when to use it, that it requires an API key, and the specific fields it returns. This is sufficient for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so the schema already provides 100% coverage (vacuously). The description reinforces this by explicitly noting 'takes no parameters,' which adds no new semantics but confirms the schema. Per rubric with 0 params, baseline is 4.

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

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

The opening sentence clearly states 'Report the configuration, connection state and delivery stats for every outreach channel — WhatsApp, SMS and push.' This identifies a specific verb (report), resource (outreach channels), and scope (every channel, with types enumerated). It distinguishes itself from mutation siblings like update_channel and other getters like get_pipeline.

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 guidance: 'Check this before relying on a channel: a disabled or unconfigured one silently delivers nothing. It is also the natural first step before update_channel.' This tells the agent the best practice and references an alternative tool, making the usage context clear.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds important context beyond that: API key requirement, the exact stage vocabulary, and the critical detail that monetary values are in cents. These details are not present in annotations or schema, enriching behavioral understanding.

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?

Every sentence earns its place: the first defines the output, the second gives usage and sibling differentiation, and the third covers critical operational details. It is compact and front-loaded with the core purpose.

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 a simple one-param read-only tool with no output schema, the description fully covers purpose, alternatives, auth, stage values, and currency units. There is no significant gap that would leave an agent guessing about how to invoke or interpret the tool.

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

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

Schema coverage is 100% for the single optional workspaceId parameter, so the schema already documents it. The description adds context that this tool returns the whole board (with workspaceId being the only possible filter), which helps but does not substantially extend the parameter's semantic meaning beyond what the schema 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?

The description clearly states the tool returns a sales pipeline board with deals grouped by stage and revenue totals. It explicitly distinguishes from the sibling list_deals by framing this as a 'board view' versus a flat list, showing precise resource and scope.

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 guidance: 'for how does the pipeline look questions and stage-by-stage review.' It names the alternative tool (list_deals) for filtering/paging needs, making the decision between them unambiguous.

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

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

Annotations already declare readOnly, non-destructive, idempotent. The description reinforces 'Reads only and changes nothing; it does not approve or undo any action' and adds beyond annotations: requires an API key, and that 'no actions today' is a normal response — useful for setting expectations. This adds contextual value without contradicting annotations.

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

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

The description is three sentences: first conveys the core purpose, second explains usage context and scope limit, third clarifies read-only behavior, API key requirement, and empty-result handling. Every sentence adds value, with no redundancy.

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

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

Despite having no parameters or output schema, the description thoroughly covers purpose, scope (today only), safety (read-only, doesn't approve/undo), authentication requirement, and expected behavior (no actions is normal). It is fully self-contained for an agent to invoke correctly.

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

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

The tool has zero parameters, so per rubric the baseline is 4. The description adds no parameter details (none needed), and even clarifies scope ('today only'), which is effectively the parameter context since there is no schema.

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

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

The description clearly states a specific verb and resource: 'Get what the AI sales agent has done today' — an audit trail of agent actions. It distinguishes itself from sibling tools like list_deals or get_autopilot_status by focusing on the agent's activity trail, not on pipeline data or system 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?

It explicitly says when to use it ('to see what the agent did', 'to sanity-check its behaviour after enabling it') and gives a clear limitation: 'Covers TODAY only, so it is not the tool for historical reporting.' This gives strong context, though it doesn't name a specific alternative tool for historical queries.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior, and the description adds an authentication requirement ('Requires an API key') and clarifies the return scope ('configuration for the authenticated account'). This adds meaningful context beyond the 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?

Three terse sentences front-load the purpose, then provide usage guidance and safety/auth notes. 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?

For a parameterless read-only tool with strong annotations and no output schema, the description is complete: it states what is fetched, why to call it, that it is safe, and what the response pertains to.

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

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

The tool has zero parameters, so the schema already covers everything; the description reinforces this by stating 'takes no parameters.' No additional parameter explanation 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?

The description uses a specific verb ('Fetch') and identifies the resource ('AI sales agent's current settings') while enumerating the exact fields returned. It clearly distinguishes itself from the sibling update_sales_agent_config 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?

Explicitly instructs to read this tool before update_sales_agent_config to avoid clobbering fields and to verify whether the agent is enabled. This provides clear when-to-use guidance and names the relevant 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 already indicate readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds valuable context beyond those: it costs no credits, requires an API key, returns run state/progress/leads found so far, and clarifies that a still-running job is a normal response rather than an error. No contradiction exists.

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

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

The description is three sentences with a clear front-loaded purpose, followed by usage guidance, cost/polling behavior, and return details. Every sentence earns its place and there is no redundant exposition or repetition of annotation fields.

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 simple one-parameter schema and strong annotations, the description provides all essential runtime context: how to poll, cadence, credit cost, required authentication, return contents, and error semantics. The absence of an output schema is well compensated by the explicit list of returned fields (run state, progress, leads found so far).

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 documents jobId as a 'Lead search job UUID' with 100% coverage. The description adds useful semantic context by indicating the jobId comes from a prior search_leads call, reinforcing the companion relationship and the polling pattern, though it does not add much 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?

The description opens with a specific verb and resource: 'Poll one lead-search job for its progress and results.' It clearly distinguishes this tool from the related search_leads tool and from other status tools like get_autopilot_status or get_channels_status by scoping it to lead-search jobs specifically.

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 usage instructions: call it repeatedly with the jobId from search_leads until the job finishes, leave a few seconds between polls, and treat a running job as normal. It also states that read-only polling costs no credits, providing clear practical guidance for when and how to use it.

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. The description adds beyond that: 'costs no credits, and starts nothing. Requires an API key. Returns runs newest first with paging.' These are valuable behavioral details (pricing, side-effect confirmation, auth, ordering). Not quite a 5 because the core safety profile is already covered by annotations, but the extra context earns a solid 4.

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

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

Four sentences, each with a distinct job: purpose, usage guidance, alternative tool, and behavioral details. No filler, all information is actionably relevant. Well-structured and front-loaded.

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

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

For a simple read-only list tool with no output schema, the description covers enough: what is returned (status and result summaries), ordering (newest first), paging, side effects (none), pricing (no credits), and auth requirement. It also correctly points to get_autopilot_status for single-run detail. This is complete for the tool's complexity.

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

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

Schema coverage is 100%: both 'limit' and 'offset' have descriptions. The description adds no additional parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

Description opens with a specific verb-action ('List past and running autopilot runs with their status and result summaries'), clearly identifying the resource and scope. It also distinguishes itself from the sibling tool get_autopilot_status by noting that the latter provides detail on a single run.

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: 'Use it to review what has already been run — and to check for a run already in flight before start_autopilot launches a second one.' It also names the alternative: 'For detail on one run, use get_autopilot_status.' This gives clear context and exclusions.

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, and non-destructive behavior. The description adds value by mentioning the requirement of an API key and explaining that money amounts are in cents, which are not covered by annotations. This enhances transparency beyond the annotations.

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

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

The description is concise and well-structured, with a clear first paragraph on purpose and a second paragraph on usage and additional notes. No unnecessary information, so it is highly efficient.

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?

Although there is no output schema, the description specifies what the tool returns (deals plus revenue summary) and notes currency units. It also contrasts with get_pipeline, making the context complete. All necessary information is provided.

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

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

The input schema provides thorough descriptions for all three parameters: limit (with default and max), offset (pagination), and status (with examples of allowed values). The schema coverage is complete, and the tool description reinforces the filtering and pagination 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 clearly states the tool lists deals as a flat, paged array, optionally filtered by status, and includes revenue totals. It explicitly differentiates from get_pipeline which presents deals in a board view, so the purpose is unambiguous.

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

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

Usage is explicitly described: use when you want deals as data for counting, filtering, or pagination. It also explicitly states when not to use it (use get_pipeline for board view), providing clear 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 indicate read-only, idempotent, non-destructive behavior. Description adds context: reads only, costs no credits, requires API key and connected account, and explains empty result meaning. No contradiction.

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

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

Well-structured, front-loaded with main purpose. Each sentence adds value (usage guidance, distinction from siblings, prerequisites, result meaning). Appropriate length for a simple tool.

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

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

For a parameterless read-only list tool, the description covers purpose, usage context, prerequisites, and result interpretation. No output schema exists, but the description sufficiently implies return of lead lists.

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?

Tool has zero parameters, so baseline is 4. Description explicitly states 'takes no parameters', providing clarity beyond schema. No additional parameter semantics 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?

Clearly states it lists Hunter.io lead lists connected to the account. Distinguishes from siblings like list_leads (local leads) and sync_lead_list by specifying scope.

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 when to use it: before sync_lead_list to find a listId, or before create_lead_list to avoid duplicates. Also distinguishes from list_leads, providing clear alternatives.

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

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

Annotations already declare read-only and non-destructive behavior, but the description adds useful context beyond them: costs no credits, requires an API key, returns saved lead records with enrichments and scores, and treats an empty page as normal rather than an error. This fully sets agent expectations.

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

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

The description is front-loaded with the core purpose, then gives usage guidance, then behavioral notes. Every sentence earns its place, and there is no filler or excessive repetition.

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

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

For a read-only list tool with no output schema, the description makes the return contents clear (contact and company fields, enrichment, score) and covers important edge behavior (empty page). With no required parameters and strong annotations, the description is fully sufficient for correct invocation.

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

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

The input schema already provides complete descriptions for all 4 parameters, so the baseline is 3. The description adds general context about paging and the job_id filter but does not materially change or enhance parameter meaning beyond what the schema already states.

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

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

The description immediately states 'List leads already saved to the account, newest first, with paging and search', giving a specific verb, resource, scope, and behavior. It also differentiates from search_leads by explicitly saying it does NOT find new leads but rather works with existing ones.

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

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

It gives clear guidance: 'Use this to work with leads you already have' and explicitly contrasts with search_leads, noting that search starts a job and costs credits. It also instructs when to filter by job_id, making the selection and invocation guidance strong.

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 well beyond annotations by explaining the real-world effect of moving to 'closed'/'lost' (deal resolution, removal from open pipeline revenue), the idempotence behavior in concrete terms, and the ability to move backwards or forwards. This is useful context that annotations only hint at via idempotentHint and openWorldHint.

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 purpose, then flows naturally into usage guidance and behavioral warnings. It is slightly wordy in places—such as 'Requires an API key,' which is not tool-specific—but overall each sentence contributes useful information without redundancy.

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

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

For a two-parameter mutation tool with a rich enum schema and meaningful annotations, this description covers purpose, alternatives, side effects, idempotence, and directional flexibility. It is complete enough for an agent to select and invoke the tool correctly without additional external knowledge.

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 both parameters fully. The description adds meaningful semantic depth by explaining the special consequences of the 'closed' and 'lost' enum values, which goes beyond the schema's 'Target stage' description.

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

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

The description opens with a specific verb and resource: 'Move one deal to a different pipeline stage' and adds a vivid metaphor ('dragging its card on the board'). It also explicitly distinguishes itself from update_deal ('update_deal is for value and notes'), so sibling differentiation is clear.

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 positions this tool as the one for pipeline progression and names update_deal as the alternative for value/notes. It also gives clear when-not-to-use guidance for 'closed' or 'lost' stages, warning that these resolve the deal and change reported figures unless the outcome is settled.

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?

Annotation Contradiction: The description says 'the same input yields different wording each time,' directly contradicting idempotentHint=true. Even though it usefully discloses that nothing is sent/saved and that no API key is needed, the contradiction is serious.

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 with a clear lead sentence followed by useful operational details. It is a bit longer than strictly necessary, but each sentence adds relevant context such as no API key, no persistence, and non-deterministic output.

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

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

For a simple 3-parameter tool with no output schema, the description covers purpose, use case, side effects, return value, and non-determinism. The only issue is the contradiction with idempotence, which is addressed separately, but the remaining content is largely complete.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds valuable context beyond the schema by explaining that the person need not be a lead and that role/company should be passed 'if known.' This clarifies the purpose of the optional parameters.

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

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

The description opens with a specific verb and resource: 'Draft a sample AI-personalised outreach message for a named person.' It clearly distinguishes itself from sibling tools by framing itself as a PREVIEW that sends/saves nothing, so it is not confused with send_to_campaign or create_deal.

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

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

It provides explicit guidance: 'Use it to check tone before committing to a sequence,' and clarifies that the person does not need to exist as a lead. It does not name explicit alternative tools, but the use case is clearly scoped.

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, the description discloses several important behavioral traits: it can reply to prospects, create deals, or book meetings; it consumes AI credits; calling twice processes twice and may send two messages; it requires an API key; and the configured confidence threshold governs action. This significantly exceeds what annotations alone 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 front-loaded with the core purpose, then each subsequent sentence adds essential operational context: real-world effects, non-reversibility, idempotency warning, credit consumption, API key requirement, and confidence threshold. No sentence is wasted.

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

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

Given the tool's side-effectful nature and lack of output schema, the description provides comprehensive context: it warns about irreversible actions, duplicate invocations, credit consumption, and prerequisites. It also clarifies what it will not do (dry run/preview), making the tool's behavior sufficiently predictable for safe invocation.

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

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

The input schema already fully describes conversationId as 'UUID of the conversation to process' with 100% coverage. The description repeats that it operates over 'one conversation' but adds no additional parameter-level nuance, so the schema carries the burden and the description is not penalized heavily.

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

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

The description states a specific verb and resource: 'Run the sales-agent pipeline over one conversation: decide the next action and carry it out.' It clearly distinguishes itself from siblings by emphasizing that it ACTS on a real conversation, is not a dry run, and refers to get_sales_agent_actions for past actions.

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 usage guidance is provided: 'call it only when the user wants the agent to take its turn on that specific conversation.' It also clarifies what it is not for ('not a dry run and there is no preview') and points to the alternative get_sales_agent_actions for already-completed actions.

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?

This is a standout. The description discloses that execution is background (returns count immediately, scores appear later), that AI credits are consumed per lead, that an API key is required, and — critically — that passing leadIds forcibly rescore leads and re-bills. These are critical operational details well beyond what the annotations (which only mark readOnlyHint: false) convey. No contradiction with annotations.

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

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

Every sentence earns its place. The structure flows from purpose → usage → behavior → important caveats, using a clear 'no' rules and a bolded emphasis for emphasis. The warning about credits/rate limits is prominent without being buried. No wasted words.

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

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

Despite having no output schema and no required parameters, the description addresses the surface area comprehensively: what happens when you call it, how to get results, what costs are involved, and what edge cases exist (rescore behavior). There's nothing left ambiguous for a tool of this complexity.

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

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

Even though schema coverage is 100%, the description enriches the parameters with high-value semantics: jobId scores only unscored leads while leadIds unconditionally rescores, the mutual exclusivity is reinforced, the upper bound of 200 is explained, and the causal chain of 'rescore → rebilling' is revealed. The description fully carries its weight 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?

The description opens with a specific verb+resource combination — 'Queue AI qualification scoring for leads' — which immediately distinguishes this from sibling tools like list_leads, enrich_lead, or verify_emails. It clearly communicates what the tool does (queue async scoring) and what it doesn't do (return scores synchronously).

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 either/or choice between jobId and leadIds, warns about the 200-id cap, and instructs users to re-read with list_leads for results. It even provides decision guidance for choosing between jobId (score only unscored) vs leadIds (force rescore) based on billing implications — going well beyond any baseline.

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?

Discloses asynchronous behavior, credit consumption, API key requirement, and effect of useAI. Annotations indicate openWorldHint=true and idempotentHint=false, but the description adds richer context about side effects and credits. No contradiction.

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

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

The description is moderately concise, with a clear first sentence stating the core function, followed by important usage and caution information. The structure is effective, though the last sentence on useAI could be integrated more tightly.

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

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

Given the tool's complexity (asynchronous, credit-based, with filters), the description covers key aspects: async workflow, credit warning, and API key requirement. It lacks explicit mention of output schema, but the return is just jobId which is implied. Overall, reasonably complete.

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

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

Schema has 100% coverage for all parameters, so baseline is 3. The description adds meaning for useAI (spends credits) and the query parameter (describing ideal lead) beyond schema. It doesn't add detail for filters, but schema already covers them.

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 starts an AI lead-search job and returns a jobId immediately. It distinguishes from siblings by noting 'Use it to find NEW leads; use list_leads for ones already saved.' The verb and resource are specific.

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 explains when to use this tool (to find new leads) versus list_leads, and provides a workflow: poll get_search_job_status and then list_leads. Also warns against using it to check progress and explains credit consumption.

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 readOnly (false) and idempotent (true), but the description adds critical context: consequences (leads can start receiving messages on a running campaign), idempotency (no duplicates), constraints (leads must belong to authenticated account or call fails), and the API key requirement. It enriches beyond annotations 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 concise and front-loaded: the first sentence states the core purpose. Each subsequent sentence adds meaningful behavioral or usage context (consequence, non-action, validation, idempotency, verification prerequisite) with zero filler. All within a short paragraph.

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 3 params and no output schema, the description covers: the operation, limits, consequences, prerequisites, failure conditions, and relationship to other tools (verify_emails, campaign starting). It is remarkably complete for the complexity involved, leaving little ambiguity for the agent.

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 baseline is 3 per the rubric. The description adds minimal parameter-level detail beyond the schema (e.g., 'up to 500 at a time' echoes the schema's '1-500', and the note about lead ownership). It does not explain parameter relationships beyond what schema provides, so it stays at 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?

Description clearly states the action: 'Add saved leads to a campaign's contact list in bulk, up to 500 at a time.' It distinguishes from siblings by explicitly noting it does NOT send or start campaigns, and positions it as the final step before outreach. Specific verb+resource+scope.

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 it ('This is how leads enter an outreach sequence'), what it does not do ('does NOT send anything by itself and does not start the campaign'), and provides a clear prerequisite/recommendation ('Verify addresses with verify_emails first; importing dead ones damages sender reputation'). It even names the alternative tool for verification.

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 annotations (readOnly=false, openWorld=true), the description discloses high-impact behaviors: it sends real messages without approval, consumes credits, requires an API key, and each call starts a separate run. It even labels itself 'the most consequential tool'—far beyond what annotations convey.

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

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

The description is front-loaded with the essential action and then packs critical warnings into dense, imperative sentences. Every sentence serves a purpose—no fluff. Despite being long, it's tightly structured and appropriately verbose for the stakes.

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

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

Given the tool's complexity (fire-and-forget, side-effects, credits, concurrency), the description covers all key aspects: what it does, what it returns, how to monitor, resource consumption, and the caution about multiple calls. No output schema exists, but the return value (runId) is disclosed explicitly. Complete for practical 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?

Schema coverage is 100% for the two parameters, so baseline is 3. The description adds semantic value by stating 'the goal text is the entire brief,' which clarifies the goal parameter's significance and intent. This modest addition justifies a 4.

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

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

The description opens with a specific verb+resource: 'Start an autonomous outreach run' and clearly differentiates from siblings by emphasizing it is fire-and-forget, sends real messages, and returns a runId. It distinguishes itself from status and management tools like get_autopilot_status and list_autopilot_runs.

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 understands the goal as written.' It also provides warnings about not calling twice unless intended, and directs to get_autopilot_status for progress. This is strong guidance with clear exclusions.

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

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

Annotations already indicate readOnlyHint=false and idempotentHint=true; the description adds valuable context by stating 'Writes a feedback record', 'sending the same verdict twice is harmless', 'Requires an API key', and 'Costs no credits'. These details go beyond what annotations convey, especially regarding auth and cost.

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 compact sentences, beginning with a clear purpose statement, followed by when-to-use, behavioral notes, and side effects. There is no fluff or redundancy; every sentence earns its place.

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

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

Given the tool's simplicity (a single write operation with three well-documented parameters, no nested objects, no output schema), the description covers purpose, usage, side effects, idempotency, auth, and cost. It is entirely sufficient for correct agent behavior.

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 each parameter has a concise description (jobId, leadEmail, feedback). The description does not add significant new meaning beyond the schema—it only generally refers to 'feedback'—so it meets the baseline of 3 without needing 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 uses a specific verb-resource combination ('Record whether an AI-generated outreach message for a lead was good or bad') and clearly distinguishes the tool from siblings like preview_message or send_to_campaign by stating it is a training signal and explicitly noting what it does not do (edit, resend, delete, send to the lead).

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

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

The description states explicitly when to use it ('when the user judges a drafted message') and provides exclusions and clarifications ('it does not edit, resend, or delete the message, and it sends nothing to the lead'), giving the agent clear context for appropriate invocation.

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 adds valuable details beyond annotations: it states it 'Writes local lead records' (consistent with readOnlyHint=false), explains re-syncing 'refreshes rather than duplicating' (deepening idempotentHint), and reveals authentication and billing context (API key, no credits). This goes beyond the structured hints and is not contradictory.

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 four tight sentences: purpose, usage sequence, side effects, and prerequisites/cost. Each sentence contributes new information without redundancy, making it concise and well-structured.

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?

Despite a single parameter and no output schema, the description covers all necessary aspects: what it does, when to use it, what happens if you don't, prerequisites, idempotency, and cost behavior. This fully supports an agent in invoking 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?

The schema already documents the sole parameter listId with type and format, so baseline is 3. The description adds semantic context by explaining that the list comes from create_lead_list or list_lead_lists, telling the agent where to source the value. This linkage exceeds the schema's simple type description.

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

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

The description clearly states the verb 'Import' and the specific resource 'Hunter.io lead list' into 'local lead records'. It distinguishes itself from siblings such as create_lead_list (which creates a list) and list_lead_lists (which lists lists), making the tool's role 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?

Explicit usage guidance is provided: 'Run it after create_lead_list, or on any existing list from list_lead_lists' tells the agent when to invoke. It also explains the consequence of not syncing ('invisible to list_leads, enrich_lead and send_to_campaign') and prerequisite ('Requires an API key and connected Hunter.io account'), giving clear context for selection.

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

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

The description goes well beyond the annotations by explaining that disabling silently stops delivery, enabling without credentials has no effect, changes affect live campaigns/autopilot, and repeating the same state is safe. It also notes the API key requirement and aligns with openWorldHint via real-world delivery impact.

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

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

The description is compact but information-dense. Every sentence serves a purpose: purpose, impact, caveats, usage guidance, idempotence, and authentication. It is well-structured and front-loaded with the primary action.

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 two-parameter mutation tool with no output schema, this description is fully complete. It covers what the tool does, when to use it, what side effects to expect, prerequisites, idempotence, and auth requirements, leaving no important operational question unanswered.

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 parameter descriptions are already clear, so the baseline is 3. The description adds meaningful behavioral context for enabled: true requires configured credentials to work and false silently stops delivery, while also clarifying that each call handles only one channel. This adds value beyond the schema, though the core parameter meaning is still schema-driven.

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

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

The description opens with a specific verb phrase, 'Turn one outreach channel on or off,' and names the exact channels (WhatsApp, SMS, push). It clearly distinguishes update_channel from the read-oriented sibling get_channels_status by focusing on state mutation and delivery impact.

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 tells the agent to 'Call get_channels_status first to see where things stand,' establishing a clear prerequisite and alternative tool. It also gives practical guidance about live campaigns, autopilot runs, credential requirements, and the one-channel-per-call constraint.

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 (readOnly=false, idempotent=true, destructive=false), the description discloses idempotency ('Safe to repeat'), auth requirements (API key, deal ownership), value currency interpretation with a concrete example, and notes-replace-not-append semantics. This adds substantial behavioral context beyond boolean hints, with no contradiction.

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

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

The description is compact yet information-dense: first sentence states the core function, second covers usage guidance, third explains idempotency and auth, fourth clarifies unit and string semantics. No filler or repetition—every sentence earns its place.

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

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

For a mutation tool with no output schema, the description covers all essential aspects: purpose, alternative usage, partial updates, idempotency, auth/ownership, currency units, replacement behavior, and status effects. It is fully sufficient for an agent 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?

The input schema covers all parameters with descriptions (100% coverage), giving a baseline of 3. The description enriches this with partial-update behavior ('Only the fields you pass are altered'), an explicit currency example, and the replace/append distinction for notes, which are not evident from the schema alone.

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

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

The description opens with a precise verb+object+fields: 'Change a deal's status, value, or notes.' It explicitly differentiates from the sibling move_deal_stage, clarifying that this tool is for value/notes while stage moves belong to the sibling. This is a model of purpose clarity.

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: 'For moving a deal along the pipeline board prefer move_deal_stage, which is the same operation expressed in stage terms; use this one for value and notes.' Also explains the consequence of setting status to closed/lost, offering clear when-to-use and exclusion information.

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 idempotency and non-destructiveness, but the description adds valuable behavioral context: enabling makes the agent respond autonomously, confidence threshold gates actions, reply limits cap sending, and changes take effect immediately. This goes beyond the structured hints 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 well-structured with a clear first sentence listing the action, followed by a focused paragraph explaining live implications and a short note on idempotency and auth. It is slightly verbose in the middle but each sentence earns its place by contributing critical context.

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 6 optional parameters, no output schema, and the tool's live-impact nature, the description covers the essential aspects: the live behavior, partial update semantics, need to read current config, and API key requirement. It lacks explicit return/error behavior, but the tool is a straightforward update and the description is largely adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches several parameters: explains the impact of 'enabled' (starts responding), the meaning of 'confidence_threshold' (how sure before acting), and 'max_replies_per_day' (caps sending). While not all parameters get extra context (e.g., cal_link, offer_price), the description adds meaning to the most consequential ones.

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 changes the AI sales agent's settings, listing specific fields (enable/disable, booking link, offer price, reply limits, confidence threshold). It distinguishes from sibling get_sales_agent_config by the action verb and scope, and from process_sales_agent by focusing on configuration rather than actions.

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 context: it advises reading the current config first, notes that only passed fields change, warns that enabling has immediate live effects, and indicates the tool is safe to repeat. It does not explicitly state when not to use it or name alternatives, but the guidance is sufficient for most scenarios.

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 annotations (readOnlyHint, idempotentHint, etc.), the description discloses credit consumption per address, API key requirement, and clarifies that 'undeliverable' is a successful result, not an error. It also reassures that nothing is sent to addresses, adding valuable behavioral context.

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

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

Two compact paragraphs with an effective front-loaded purpose statement, but contains slight redundancy like 'Pass either `email` for one or `emails` for a batch, not both' where the latter part is redundant. Still efficient overall.

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 no output schema, the description explains what a return looks like (deliverability verdict per address) and covers auth, cost, and safety. Given moderate complexity and strong annotation coverage, it is fully complete.

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

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

Schema description coverage is 100% for both parameters, but the description adds the either/or relationship between email and emails, and the credit cost per address, providing meaningful semantic detail beyond the schema itself.

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: 'Check whether email addresses are deliverable' with a specific verb and resource, and distinguishes it from sibling tools by focusing solely on verification. The mention of one or batch up to 20 adds specificity.

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 clear context for when to use: 'Run this before a send to protect sender reputation' and gives explicit parameter usage (pass either email or emails, not both). However, it does not explicitly mention alternative tools or when not to use, though no sibling tool is similar.

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