leadmarina

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

Annotations already mark this as a write operation with open world implications, but the description goes further by disclosing that each run spends leads (one per result), which is a critical side effect. It also reveals nuances like 'Close also needs one manual export first to save its field mapping' and that 'csv' | 'xlsx' | 'json' require no setup, adding substantial behavioral context 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 three sentences long and front-loaded with the primary purpose. It packs in essential warnings and limitations without excessive fluff, though the capitalized warning sentence ('IT SPENDS LEADS ON EVERY RUN...') may be slightly jarring but effectively emphasizes the risk. Each 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 creation tool with an output schema, the description covers all major aspects: what the tool does, cost implications, integration requirements, and limits. It does not need to explain return values because the output schema exists. The inclusion of the 20-automation limit and 25-cities-per-run cap adds important context that would otherwise be 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 parameters are already documented. The description adds extra meaning by clarifying that cities can be passed as plain strings and are resolved automatically, and by explaining that certain destinations require existing integrations while others do not. This goes beyond the schema's basic descriptions, though it does not cover every parameter in equal depth.

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 starts with 'Create an automation: re-run a search on a schedule and send the results somewhere automatically,' which uses a specific verb (create) and resource (automation) and explains the core functionality clearly. It distinguishes from sibling tools like delete_automation, update_automation, and list_automations by focusing exclusively on creation.

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 clear context on when to use this tool: it creates scheduled recurring searches and requires user confirmation due to lead spending. It also mentions integration prerequisites and limits (up to 20 automations). However, it does not explicitly name alternatives (e.g., update_automation for modifying existing automations), so it stops short of a 5.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context: the deletion is irreversible, leads already collected are retained, and only the schedule is removed. This goes well beyond the annotations and fully discloses the operational 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?

Three tightly written sentences, each earning its place: the first states the action, the second adds critical safety guidance, and the third clarifies behavioral consequences. No filler or 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 single-parameter destructive mutation, the description fully covers prerequisites (confirmation), alternatives (disable instead of delete), effects (schedule removed, leads kept), and irreversibility. An output schema exists, so return-value details are not required. The description is self-sufficient.

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 the single required parameter, id, and explicitly states it comes from list_automations. The description does not add parameter-specific details, but with complete schema coverage the baseline of 3 is appropriate.

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

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

The description opens with 'Permanently delete an automation,' using a specific verb and resource while clearly distinguishing this from the sibling update_automation. It also clarifies the destructive nature, leaving no ambiguity about the tool's 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 explicitly states when to use this tool and when not to, recommending update_automation with active=false as a less destructive alternative for temporary suspension. It also instructs the agent to confirm with the user first, providing direct guidance for safe 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?

Annotations cover the mutability hints, and the description adds important behavioral details: the cost of 1 lead per domain, the asynchronous nature (returns a search_id to poll), and the pipeline stages (enrichment + verification). This goes 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?

The description is three sentences, each carrying distinct information: the use case, the pipeline outputs, and the cost/return behavior. It is front-loaded with the main purpose and contains no filler words or redundant details.

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 one parameter, no nested objects, and an output schema, the description covers the input constraints, the processing pipeline, the cost, and the follow-up mechanism (get_search_results). It is sufficiently complete 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?

Schema coverage is 100% for the single 'domains' parameter, which already includes an example and maximum count. The tool description restates the 10-domain limit but does not add extra semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool enriches up to 10 business domains by running a full enrichment + verification pipeline, listing specific outputs (verified emails, phones, owner name, socials). It distinguishes itself from sibling tools like search_leads by focusing on existing domains rather than querying for new leads.

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

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

The opening 'Already have businesses?' sets the use case for enriching existing domains, and the mention of cost per domain and polling with get_search_results gives operational context. It does not explicitly exclude alternatives or state when not to use, but the context is clear enough for an agent to decide.

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

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

Adds extensive behavioral context beyond annotations: per-destination rate limits, file delivery via email/download link, in-place update semantics (never duplicated), preservation of user's CRM notes/columns, and the truncated=true response flag requiring relay to the user. This goes far beyond the basic annotations and concurs with idempotentHint.

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 dense but every sentence earns its place, covering purpose, destination details, selection modes, limits, fallback advice, and update behavior. It is logically ordered and front-loads the core purpose before elaborating on constraints.

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 (multiple destinations, modes, limits, side effects), the description fully prepares an agent: it covers selection, filtering, error/partial export signaling, update semantics, and cross-tool references (query_leads-style filters). The presence of an output schema reduces the need to describe return payloads, and the description covers the remaining operational concerns.

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 every parameter: clarifies destination enum values (e.g., google_sheets can create new or reuse spreadsheet_id), explains search_id vs all vs filters semantics, and specifies per-destination limits that affect parameter usage.

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, 'Push leads into a connected destination,' and enumerates all destination types (close, ghl, google_sheets, csv/xlsx/json). It clearly distinguishes the tool from siblings like query_leads or search_leads, which read/query leads rather than export them.

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 which path: pass search_id for one search, set all=true for the whole library, and use filters with all=true. It also gives an explicit alternative instruction: 'For a big library going to a CRM, export csv and import the file instead' due to per-call limits.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds the specific data returned (remaining leads and plan) but does not disclose any additional behavioral details such as caching or real-time accuracy. This is adequate for a simple status query.

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 sentence with no filler words. It front-loads the key information about what the tool returns and is appropriately sized for the tool's simplicity.

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

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

For a zero-parameter read-only tool with an output schema available, the description captures the essential purpose completely. No additional context is needed to understand when or how to invoke it. The sibling tools are clearly unrelated to account balance.

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 has no parameters, so schema coverage is trivially 100%. The description does not need to explain parameters. With zero parameters, the baseline is 4, and the description adds no missing 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 clearly states that the tool returns the account's remaining monthly leads and current plan. The name 'get_balance' reinforces the action. It is distinct from sibling tools which focus on searching, enriching, or exporting leads.

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

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

No explicit guidance is given on when to use this tool versus alternatives. However, the description implies its use for checking account quota and plan, which is straightforward for a zero-parameter read-only tool. There are no exclusions or alternative tools mentioned.

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

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

Annotations already declare the tool read-only and non-destructive, so the description adds value by explaining that data changes as enrichment progresses and includes verified fields (emails, phones, owner, socials, business profile). This gives the agent useful expectations about dynamic results and polling 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?

The description is two concise sentences, front-loaded with the core action and polling guidance. Every sentence delivers meaningful information without redundancy or fluff.

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 presence of an output schema covers return value structure, and the description provides the essential context: polling behavior, enrichment progression, and the fields included per lead. It is complete for a read-only retrieval tool with good annotations and schema coverage.

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 100% of parameter descriptions, so the description doesn't need to add much. It doesn't elaborate on limit/offset/search_id beyond what the schema already says, landing at the baseline for well-covered 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 uses a specific verb ('Fetch') and clearly identifies the resource ('a search's leads'), while also describing what each lead includes. It distinguishes itself from sibling tools by focusing on retrieving results with enrichment verification, not creating searches or exporting data.

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

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

The description provides clear usage context: fetch results and poll until enrichment is complete. It implies this tool is meant for retrieving in-progress results, but it doesn't explicitly state when to use it over alternatives like query_leads or export_leads.

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 destructiveHint=false, so safety is established. The description adds meaningful context by explaining what automations are (scheduled searches that export themselves) and what status information is returned. It does not add details like pagination or rate limits, but given the annotation coverage, the bar is met.

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, well-structured sentence that front-loads the core purpose and then provides specific details about returned fields. Every word contributes value, 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 simple list tool with no parameters and an existing output schema, the description is complete. It defines the domain concept (automations), states what is listed, and enumerates the output fields, leaving no significant ambiguity about the tool's 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?

The tool has zero parameters, and the schema is fully covered (100%) by virtue of being empty. The description adds no parameter details because none exist, which matches the baseline expectation for a no-parameter tool.

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

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

Description clearly identifies the tool as listing the account's automations (scheduled searches that re-run and export themselves) and enumerates the exact fields shown (niche, cities, cadence, destination, active status, next run, last run). This distinguishes it from sibling list_searches, which likely lists one-off searches.

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

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

Usage context is implied: an agent would use this to inspect scheduled search automations. However, there is no explicit statement about when to choose this over list_searches or other alternatives, nor any exclusions. The definition of automations provides implicit guidance but not direct comparison.

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, but the description adds valuable context: that export_leads/create_automation fail without integration and that Close requires a manual export first. This goes beyond the structured 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 a single, information-dense sentence that front-loads the purpose and then provides essential usage guidance. Every clause contributes value 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?

With zero parameters and an output schema present, the description fully covers purpose, usage timing, and edge cases (Close's manual export requirement, file destinations always working). No 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?

Tool has 0 parameters, so baseline is 4. The description uses this freedom to explain the meaning of 'connected' and 'ready', adding semantic context even though no parameters need clarification.

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 connected export destinations (Close, GoHighLevel, Google Sheets) and their readiness for receiving leads. It uses specific resource names and distinguishes itself from sibling export/automation tools.

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

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

Explicitly instructs to check this tool before export_leads or create_automation with CRM destinations, noting these fail without a connected integration. Also states file destinations always work, providing clear when-to-use and 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value beyond this by clarifying account scoping ('the account's recent searches'), listing the return fields, and indicating how the results should be used downstream, which are behaviors not captured by 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 a single sentence that front-loads the main purpose and returned fields, followed by a concise usage clause. Every word contributes useful information 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?

Given the tool's simplicity (one optional parameter, existing output schema, read-only annotations), the description provides all essential context: what it returns, account scope, and how the results connect to sibling tools. This is fully complete for the tool's complexity level.

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 provides 100% coverage for the single 'limit' parameter, including its default (10) and max (25) values. The description does not repeat or extend the parameter semantics, so it adds no extra meaning beyond what the schema already offers.

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 ('List recent searches') and the resource ('account's recent searches'), and enumerates the returned fields (id, niche, location, result count, when). It differentiates from sibling tools by explicitly mentioning that search_ids from this tool are used with get_search_results or export_leads, making its role distinct.

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 the usage context by explaining that the search_id obtained from this tool is used with get_search_results or export_leads, which positions list_searches as the entry point for those operations. It does not provide explicit exclusions or alternative scenarios, but the guidance is clear and helpful for an agent deciding when to call 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=true and destructiveHint=false, so the safety profile is well covered. The description adds valuable behavioral context by stating the output format is compatible with query_leads and export_leads, and clarifies that views are user-defined named filters. This goes beyond the annotations and helps the agent understand the data and its reuse. 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 concise, consisting of two sentences. It front-loads the purpose, provides an example, and explains the key integration point without unnecessary elaboration. Every sentence contributes meaning and 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?

With no parameters, an existing output schema, and read-only annotations, the description covers all essential aspects: what is listed, the format compatibility, and the practical use case. It does not discuss pagination or limits, but these are likely in the output schema. Overall, it is complete for a simple list 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?

The tool has zero parameters, so the description correctly focuses on output rather than inputs. Schema description coverage is 100% by default, and the description adds no parameter details because none are needed. The baseline of 4 is appropriate for tools with no 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 clearly states that the tool lists the account's saved views from the leads table, each being a named set of filters, with a concrete example ('Roofers with a mobile number'). This distinguishes it from sibling tools like list_searches by specifying 'saved views' as the resource. The verb 'list' is unambiguous and directly matches the title.

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 that the returned filter conditions are in the exact shape query_leads and export_leads accept, implying this tool is used to retrieve saved views before querying or exporting them. It does not explicitly state when not to use it or compare it to alternatives, but the context makes the primary use case 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 declare readOnlyHint=true and destructiveHint=false, but the description adds valuable context by stating 'no new search is run and no leads are spent', which discloses the cost/impact behavior beyond the annotations. It also details filter operators and behavior, providing deep transparency.

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 message, then provides detailed operator lists and a practical example. Every sentence contributes essential usage information, and the structure is efficient for a tool with complex filtering logic.

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 complex filtering and sorting, the description covers the most important behavioral aspects comprehensively. The presence of an output schema means return values need not be explained, and the description fully addresses the tool's unique value proposition.

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?

Although schema coverage is 100%, the description elevates parameter understanding by enumerating all filterable fields, supported operators, conjunction semantics, and a concrete example. This goes far beyond the schema's bare parameter definitions.

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 searches ALL leads the account has ever collected, distinguishing it from search_leads by noting it does not run a new search. The verb 'Search' and resource 'lead library' make the purpose explicit and 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?

The description explicitly states that no new search is run and no leads are spent, which implicitly guides when to use this tool versus search_leads. It does not name the alternative tool directly, but the context is clear and it includes a concrete example of 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?

The description discloses several non-obvious behaviors beyond annotations: asynchronous processing (immediate first batch with background verification), the verification methods (SMTP email check, phone line type + carrier), and the cost implication ('Spends 1 lead per result'). This is highly valuable contextual information that the agent could not infer from the schema or basic 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 front-loaded: the first sentence states the core purpose and gives an example. The following sentences efficiently deliver critical details (async behavior, verification, cost, and polling instruction) without any redundancy or filler. 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 that an output schema exists and parameter schema coverage is 100%, the description is complete enough. It covers purpose, asynchrony, verification, cost, and the next step (poll get_search_results). No critical gaps are apparent for the agent to use 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 all three parameters thoroughly (query, location, location_code) with 100% coverage, providing the baseline. The description adds a concrete example ('electrician', 'Austin, TX') and reinforces the 'niche + city' relationship, but does not introduce new parameter meanings 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 clearly states the tool's function with a specific verb ('Run a live search'), a resource ('local businesses'), and a scope ('by niche + city'). It distinguishes itself from siblings like get_search_results and list_searches by defining its role as the search initiator and explicitly referencing the polling workflow.

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 clear usage context: it is for starting a live search and returning a search_id for subsequent polling. It explicitly names the companion tool (get_search_results) and instructs the agent to poll until completed, which implies this tool is used for initiating rather than retrieving results. However, it does not explicitly state when not to use this tool or contrast with alternatives like query_leads.

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 mutability (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds context beyond these: pausing stops the automation from running and 'stops spending leads', which is a meaningful incidental effect. 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?

Two sentences, front-loaded with the primary action. Every clause contributes to understanding: the mechanism (active flag), the consequence (stops spending leads), and the alternative (delete_automation). No fluff or redundancy.

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

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

For a simple two-parameter tool with full schema coverage, an output schema, and solid annotations, the description covers all necessary context: what the tool does, when to use it vs an alternative, and the practical effect. No important 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%, with clear descriptions for both id and active. The description reinforces the active mapping (false to pause, true to resume) and adds a slight nuance about stopping lead spending, but does not substantially enrich parameter meaning beyond what the schema already provides. 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?

Description uses specific verbs 'pause' and 'resume' with the resource 'automation', and explicitly maps them to the active field values. It distinguishes from sibling delete_automation by noting when to use which, 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?

Explicitly states when to use pause/resume vs delete: 'Pausing is the safe way to stop an automation you might want back — use delete_automation only when the user wants it gone for good.' This provides direct alternatives and clear usage context.

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