LeadMarina

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuine context beyond them: pause/stop take effect only after in-flight batches, a queued batch is cancelled and refunded, and resume continues from where it left off. This is useful mutation semantics. It still omits whether stop is irreversible and what state the search ends in.

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?

A single sentence with a parenthetical, zero waste, but the most important element — the primary statement of what the tool does — is absent, so it is under-specified rather than well-structured. The action semantics are front-loaded, but the reader must reconstruct the 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?

With an output schema and rich annotations, the description needn't explain returns or safety. However, for a destructive control tool it should state valid preconditions (which search states each action accepts) and whether stop is final; those gaps leave an agent guessing about error cases.

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 50%: campaign_id is documented in the schema, but the action enum has no per-value descriptions. The description compensates by explaining what pause, stop (queued batch cancelled and refunded) and resume actually do, which is meaning an agent cannot get from the bare enum. It says nothing extra about campaign_id beyond the schema's own pointer.

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 never states the primary action ('pause, resume or stop an advanced search'); it only explains the timing semantics of those actions, leaving the title and name to convey purpose. An agent can infer the verb+resource, but the description itself is close to a restatement of the action enum. No differentiation from siblings like run_advanced_search or get_advanced_search.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. the search must be running to pause, or paused to resume), and no routing against alternatives such as run_advanced_search or get_advanced_search. Only the action enum and the phrase 'resume carries on' imply 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 this is a non-read-only, non-idempotent, open-world write, but the description adds the crucial cost behavior the annotations cannot express: it spends one lead per result on every run, and the user should be consulted first. It also discloses hard limits (20 automations, 25 cities each), integration prerequisites per destination, and the atomic failure mode ('nothing is created and the error says what to fix').

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

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

The core action and its purpose are front-loaded, followed by the cost warning, then prerequisites and limits. It is dense and a few clauses are long (the Advanced-search exclusion list in particular), but essentially every sentence carries operational information.

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

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

For a 6-parameter creation tool that spends credits, this covers cost, quotas, prerequisites, failure behavior, and geographic scope, while an output schema handles return values and annotations handle the safety profile. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the schema baseline is 3. The description still adds real meaning: cities are plain strings that get resolved server-side, destination values are grouped by setup requirement (close/ghl/google_sheets need a connected integration; csv/xlsx/json just email a file), and Close falls back to its own fields when no mapping is saved. It says nothing extra about start_at, leaving that to 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 pair ('Create an automation') and immediately defines what an automation is: a scheduled re-run of a search that delivers results automatically. That definition cleanly separates it from list_automations, update_automation, and delete_automation without needing the schema.

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

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

It gives an explicit precondition ('confirm the niche, cities and cadence with the user before creating one') and states when the tool is not usable: US places only, and Advanced-search options like non-US countries, max_leads, or exact_category are refused. It does not explicitly compare itself to update_automation for modifying an existing automation, so it is clear context rather than full routing 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 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 safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), and the description adds substantial non-obvious behavior: 1 lead charged per distinct domain, spelling-variant deduplication, US-only phone handling, and the returned search_id polling flow.

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

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

Three tight sentences, front-loaded with the precondition, then cost rules, then the return/polling contract. Every clause carries information; nothing is filler.

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

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

Despite an output schema, the description still supplies the essential async contract (search_id → get_search_results), covers cost and eligibility limits, and fully specifies the one input. An agent has everything needed to call and follow up 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% with a single documented array parameter, so the baseline is 3. The description adds real meaning beyond the schema by explaining the max-10 limit in context and, crucially, the distinct-domain billing/dedup semantics that the schema does not convey.

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

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

States a specific verb+resource (run enrichment + verification pipeline on website domains) and lists exactly what is produced (verified emails/phones, owner name, socials). It is clearly distinguishable from siblings like search_leads and get_search_results.

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?' frames the precondition for using this tool instead of a search tool, and it explicitly routes the follow-up to get_search_results by name. There is no explicit when-not-to-use or named alternative for the 'I don't have domains' case, so it falls 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: nothing is started and nothing is spent, i.e., a free preview — a cost trait annotations cannot express. It stops short of noting any rate limits or latency 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?

Two sentences, the cost-free preview claim front-loaded, and the return-value semantics confined to one follow-up sentence. No filler and nothing repeated from the schema.

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

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

With an output schema present and 100% parameter coverage, the definition covers what an agent needs to call it: it is a non-executing, non-charging estimator. It could still note whether an estimate must precede run_advanced_search or how stale an estimate becomes, but nothing essential is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description adds no syntax or format detail beyond that. It does clarify the lead accounting model ("each business is charged once however many keywords or places find it"), which gives useful context for lead_cap, but that is marginal against a fully described schema.

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

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

Specific verb (estimate) plus resource (an advanced search), with the scope spelled out: "What an advanced search (many keywords across many places) would find and how long it would take." The clause "without starting it or spending anything" cleanly separates it from run_advanced_search and control_advanced_search.

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

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

The phrase "without starting it or spending anything" clearly signals the when: a dry-run check before committing. However, no sibling is named explicitly — an agent has to infer that run_advanced_search is the follow-up, and there are no stated preconditions or 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?

The description adds substantial behavior beyond annotations: per-destination limits, truncation and next_cursor semantics, live-library consistency caveats for multi-call exports, and exact update-in-place behavior for Close, GoHighLevel, and existing sheets. It clarifies that the tool never touches user CRM notes/columns and explains when update_existing changes semantics. This is rich, non-contradictory context for a destructive, non-idempotent write tool.

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

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

The first sentence is a strong, front-loaded purpose statement, and most sentences carry operational detail that an agent needs. The description is long and dense, but the complexity of six destinations, cursor continuation, and update semantics justifies most of the length. Some grouping or bullet-style structure would improve readability.

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 an output schema exists, the description supplies the return-value semantics an agent must act on: next_cursor, truncated, not_sent, and spreadsheet_id continuation. With 10 parameters, six destinations, and destructive writes, the description covers the key decisions an agent must make before and after calling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: destination-specific limits, the interaction of filters with search_id/all, cursor reuse, spreadsheet_id continuation behavior, and update_existing effects. It explains parameter behavior in operational terms that the schema alone does not.

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: pushing leads into a connected destination. It enumerates all destination types and makes the export scope clear (one search vs. whole library). This is far more specific than the title and distinguishes it from read-only siblings like query_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?

It explicitly states when to use search_id, campaign_id, or all=true, and how filters interact with each. It also gives alternatives, such as exporting CSV and importing the file for large CRM exports, and explains cursor-based continuation with exact parameters to repeat. Exclusions and edge cases (e.g., not_sent, truncation) are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds a real behavioral constraint — coverage is limited to the US and territories 'for now' — plus what each input shape returns, which is context the annotations cannot supply.

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 scoping statement is front-loaded and the three modes are laid out in a compact parallel structure with no filler. It is telegraphic to the point that the 'With country' / 'With q' clauses read as fragments, but every sentence carries information.

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

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

With an output schema present, the description doesn't need to explain return shapes, and it still names the key returned fields (codes, states). All input modes are addressed; the one gap is the unspecified behavior for a territory code passed as `country`.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by tying each parameter to a distinct result set (country='US' → states; q → name substring matches with states). The only unexplained case is what a territory code like 'PR' returns under `country`, which keeps it from a 5.

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

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

The description states the specific resource — the places/codes an advanced search can run against — and explicitly scopes it to the US and its territories, which separates it from the list_*/search_* siblings. The verb 'find' is only implicit, but the phrase 'with their codes' makes the returned entity 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?

It enumerates every invocation mode and what each selects: no args → countries/territories, country='US' → states, q → matching places. It also routes the output to the exact consumers ('run_advanced_search's places, or search_leads' location_code'), so the agent knows both when to call it and where the result goes.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the shape of the payload (status, progress, top places, newest running batch), which is genuinely useful context, but because a full output schema exists it largely restates structured data rather than disclosing behavior beyond it.

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

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

One short sentence with no filler, and the key scoping word 'One' and the payload contents are front-loaded. The telegraphic, verbless phrasing means it reads more like a caption than a definition, which keeps it just short of a 5.

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 single-record fetch, the description plus the 100%-covered single parameter, rich annotations and an output schema give the agent nearly everything needed to call it correctly. The missing piece is routing information versus the sibling list/search tools.

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?

There is a single parameter with 100% schema description coverage, and the schema already explains where the campaign_id comes from. The description adds no further meaning about the id format, resolution, or error behavior, so the baseline 3 applies.

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

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

The description enumerates what is returned ('status, leads so far, progress by keyword, its top places and the newest batch') for a single advanced search, and the word 'One' implicitly distinguishes it from list_advanced_searches. However, there is no verb and no explicit statement that it retrieves a single search by id; the agent must infer that from the tool name and title alone.

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?

There is no guidance on when to call this versus list_advanced_searches or get_search_results. The only reference to siblings appears in the schema's campaign_id description ('An id from run_advanced_search or list_advanced_searches'), which explains id provenance rather than tool 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: it explains the reset behavior and how balance differs by plan type, going beyond the binary annotations. No contradiction; it enriches understanding of the tool's output.

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 tightly worded sentences, with the core purpose ('what the account has left, and when it resets') front-loaded. The second sentence clarifies plan-specific nuances without redundancy. 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?

With no parameters and an output schema available, the description fully covers what the tool does and how to interpret the result. It clarifies reset timing and plan distinctions, leaving no ambiguity about the return value's meaning.

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 baseline is 4 per rubric. The description adds no parameter details because none exist, but it effectively explains what the returned value represents, which is more relevant than 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 the tool's purpose: reporting remaining lead balance and reset timing. It distinguishes between rate-limited (7-day period) and metered (monthly) plans, providing specificity beyond the title. No sibling tool covers balance queries, so it stands apart.

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

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

The description implies usage: check balance to know remaining leads before operations. It does not explicitly contrast with alternatives, but given the sibling list contains no similar tools, that omission is acceptable. It clearly explains when the value applies (current period) without needing 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 cover the safety profile (readOnly, non-destructive, closed-world), but the description adds the non-obvious behavioral trait that results are asynchronous and progressively enriched, which drives polling. It also enumerates what each lead carries; that partially overlaps the output schema but the polling semantics are real added value.

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

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

Three compact sentences, front-loaded with the core action and the polling rule right after. Minor redundancy in listing lead fields that the output schema already exposes, but nothing is wasted 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?

With an output schema present, the description does not need to detail return values, and annotations cover safety. It closes the main gap an agent would face—that results arrive asynchronously and require polling—though it stops short of stating pagination or completion-latency expectations.

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 limit, offset, and search_id are already documented with defaults and ranges. The description adds nothing about parameter meaning or interaction (e.g. how pagination relates to the enrichment status), so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (a search's leads) plus the enrichment-fill behavior, which is more precise than the generic title. It implies results come from a search created elsewhere but never names the sibling tools (search_leads, query_leads, list_searches) that an agent might otherwise pick.

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 instruction 'Poll until enrichment is complete' is a genuine usage cue about when to call this tool repeatedly. However, it gives no guidance on when to prefer this over query_leads, export_leads, or list_searches, so differentiation from the sibling set is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description's main added value is ordering ('newest first') and a partial return-field preview. It does not explain pagination behavior beyond the schema's limit field or any other operational 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?

The description is a single compact fragment with no wasted words, and the ordering and return-field preview are front-loaded. It is efficient, though the sentence-fragment style is slightly terse.

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 an output schema present, the description needn't explain return values in full, and annotations cover the safety profile. It is nearly complete for a simple one-parameter list tool, though it could mention sibling alternatives or pagination expectations.

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

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

Schema description coverage is 100%, and the single limit parameter is already documented in the schema. The description adds no further meaning about limit behavior, 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 identifies the resource (this account's advanced searches) and implies a list operation, plus it previews key return fields. It does not distinguish the tool from siblings like get_advanced_search or list_searches, which keeps it from a 5.

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

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

It provides no explicit guidance on when to use this tool versus get_advanced_search, list_searches, or other search-related siblings. The list intent is implied by 'newest first' and the resource name, but no alternatives or exclusions are given.

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, destructiveHint=false and a closed world, so the safety profile is covered. The description adds a useful conceptual framing of what an automation is, but says nothing about pagination, result limits, or ordering that a listing caller might need.

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 front-loaded sentences with no filler. The second sentence enumerates return fields, which partly duplicates the output schema, but it works as a quick orientation rather than padding.

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

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

With an output schema present and zero parameters, the description does not need to explain return values, and the safety profile is carried by annotations. Only the missing routing guidance against siblings keeps it from being 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify or compensate for.

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

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

States a specific resource and defines it: 'the account's automations — saved searches that re-run on a schedule and export themselves.' That definition is what separates it from the sibling list_searches, which lists plain saved searches without scheduling or export behavior.

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?

There is no when-to-use guidance at all. It never says this is the way to discover automation IDs before calling update_automation or delete_automation, nor does it exclude any scenario, so the agent must infer routing from the name alone.

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, openWorldHint=false and destructiveHint=false, so safety is covered; the description adds the operational prerequisite chain and the default Close field-mapping behavior (name, website, address, contact, phone, email) that determines readiness. The field-mapping sentence leans toward explaining export_leads rather than this tool, which slightly dilutes focus, but it does help interpret what "ready" means.

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

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

Three sentences, each doing distinct work: what is returned, when to call it and why, and the caveat that file exports bypass the check. The prerequisite warning is front-loaded before the edge-case detail.

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

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

With no parameters, a documented output schema, and full annotation coverage, the remaining burden is explaining call timing and failure conditions — both are covered explicitly. Nothing an agent needs to invoke this correctly is missing.

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

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

Zero-parameter tool, so the baseline is 4 and there is nothing for the description to disambiguate. The absence of arguments is implicitly conveyed by the description scoping everything to "this account".

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

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

States a specific resource (connected export destinations) and scope (Close, GoHighLevel, Google Sheets) plus what is reported for each (whether it is ready to receive leads). This is far more specific than the title and cannot be confused with any sibling tool, which all deal with searches, leads, or automations rather than connection state.

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

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

Gives explicit timing ("Check this BEFORE export_leads or create_automation with a CRM destination") and names the exact failure mode those calls hit. It also states the exclusion — file destinations need nothing connected — so the agent knows when to skip the call entirely.

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 readOnly/non-destructive/closed-world, but the description adds genuinely non-obvious behavior: no credits are spent, duplicate listings collapse to the most recent record, pagination is cursor-based with the cursor carrying its own filters and sort (and mismatched filters being refused), and invalid field/operator/value combos return a self-describing error. That is real operational context beyond the annotation set.

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

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

Front-loaded with the differentiator and the pagination rule before any detail, and the example is compact. Minor weakness: the campaign_id clause is stranded at the very end after the error-handling sentence, breaking the otherwise logical flow of the search_id/campaign_id scoping discussion.

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 six-parameter, zero-required query tool with a full output schema, everything an agent needs is present: scope, cost, dedup semantics, page size, cursor reuse rules, scoping by search or campaign, and error recovery. Nothing material is left to inference.

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 earns above baseline by supplying a concrete filter example (plumbers in Austin, rating >= 4.5, safe email, sorted by reviews desc) that shows how the nested objects compose, plus the default-25 / 1,000-cap behavior. It does not restate the operator taxonomies, which the schema already handles well, so it stops short of 5.

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

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

States a specific verb and resource ("Search ALL leads the account has ever collected") and immediately scopes it against the obvious alternative: "no new search is run and no leads are spent," which is exactly what distinguishes it from search_leads. The dedup rule ("a Google listing found more than once appears once, with its most recent data") further pins down what the result set actually is.

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

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

Gives explicit routing conditions: use this to query the existing library, pass search_id for one search, campaign_id for one advanced search, and it names the sibling that produces those ids (search_leads, list_searches, run_advanced_search, list_advanced_searches) as well as export_leads. The exclusion "Not with search_id" is stated in the schema and implied by "instead of search_id" in the description.

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

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

Annotations only say it is a non-idempotent write with open-world scope; the description adds the material traits: it runs in the background in batches, each business is charged once (1 lead), spending stops at lead_cap, and it requires user confirmation before spending. It also discloses hard concurrency and daily quota limits (25 running/paused, 40 new or 250,000 searches a day), which is exactly the operational context an agent cannot get from the schema.

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

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

Front-loads what the tool does, then cost/confirmation, then chaining, then rate limits — dense but ordered by decision importance. Every clause carries a fact (cost, cap, quota) rather than 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 costly, non-idempotent, open-world mutation with an output schema already defined, the description covers everything an agent needs before invoking: cost model, confirmation requirement, prerequisite estimator, downstream retrieval tools, and throttling limits.

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 all seven parameters including lead_cap ranges and the keywords × places cap are already documented. The description reinforces the geographic trichotomy (whole US / whole states / single places) and the lead_cap stop rule, but adds no value beyond what the structured schema already states — baseline 3.

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

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

States a specific verb and resource ("Start an advanced search") and immediately scopes it as "many keywords across many US places — the whole US, whole states or single places," which separates it from single-query siblings like search_leads and from the non-mutating estimate_advanced_search.

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

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

Gives an explicit pre-call workflow ("Estimate first with estimate_advanced_search and confirm with the user: it spends leads") and an explicit post-call path ("Follow it with get_advanced_search; read its leads with query_leads or send them with export_leads (campaign_id)"). It names the alternatives and the condition that selects each, leaving nothing to inference.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, and the description adds far more: 1 lead spent per result, background enrichment with SMTP email checks and phone line-type/carrier verification, the queued 'in_progress' discovery path, and what `capped` means. This is exactly the cost/async/side-effect context an agent needs before a metered call.

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

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

Front-loaded with the core action and return shape, and essentially every clause carries real information. The long em-dash-chained sentences make it denser than ideal to parse, which keeps it from a 5.

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?

Output schema exists, yet the description still explains the tricky return semantics an agent can't infer: `search_id` plus immediate `results` with unverified contacts, enrichment lifecycle, and `capped`. Combined with annotations and a full schema, nothing needed to invoke or follow up is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter behavior beyond the schema: territory search with `country`, `max_leads` stopping early, and `exact_category` restricting to the query's Google category while running in the background. It stops short of restating formats (e.g. code ranges) already in the schema.

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

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

States a specific verb and resource ('Run a live search for local businesses by niche + city') and grounds it with a concrete example query/location. It is clearly distinguishable from run_advanced_search, which it calls out by name for multi-keyword/multi-place work.

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

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

Explicitly says to poll get_search_results until enrichment is 'complete', points to find_places for territory place codes, and routes the agent to run_advanced_search for many keywords or places. It also states the degenerate case ('if enrichment is already complete, nothing was found').

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=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: pausing stops the automation from running and from spending leads, and is framed as the reversible option. It does not discuss auth requirements or what happens to in-flight leads, keeping it short of a 5.

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

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

Two sentences, zero filler, and the primary behavior plus the cost consequence are front-loaded ahead of the alternative-tool guidance.

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

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

An output schema exists, so return values need no explanation. For a two-parameter state-toggle with clear safety annotations, the description covers purpose, the consequence of the action, and routing to the destructive sibling.

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

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

Schema description coverage is 100% and both parameters are documented in-schema (id source, true/false meaning). The description's restatement of active=false/true adds emphasis but no new syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (pause/resume) on a specific resource (automation), and pins each state to its parameter value (active=false / active=true). It is immediately distinguishable from delete_automation, the other mutating sibling.

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

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

Explicitly names the alternative and the condition that selects it: pause is for automations you might want back, delete_automation only when the user wants it gone for good. This is a genuine when-to-use / when-not-to-use rule, not an inference.

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