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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds that it's free, no credit consumed, hits a specific edge function, and values only change on Stripe webhooks, providing rich behavioral context beyond 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?

Description is somewhat long but well-organized with clear sections (Behavior, Usage, Returns). Every sentence adds value, though minor redundancy could be trimmed.

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 lacking an output schema, the description enumerates return fields and their possible values. Combined with usage context, it fully equips the agent to understand and invoke the tool correctly.

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

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

No parameters exist in the schema, so description doesn't need to add parameter info. Baseline for 0 params is 4, and the description provides no parameter details, which 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 it checks billing status including specific fields like plan, runs, credits. It distinguishes itself from sibling tools (e.g., leads.find) by being about billing rather than lead 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?

Explicitly advises to call before leads.find or leads.search to confirm runs availability, and after billing-error responses. Also warns against polling on a schedule, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true. Description adds key behaviors: 'Consumes one credit,' 'Stateless; nothing persists,' and that it uses the same endpoint as leads.find. This goes beyond the annotations to explain side effects and internal mechanics, but does not cover all potential edge cases.

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

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

The description is well-structured with clear sections (Behavior, Usage, Returns). It is somewhat lengthy but every sentence adds value, including the warning about double-billing. However, it could be slightly more concise by removing minor 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 tool with one parameter and no output schema, the description covers everything: purpose, behavior, usage, return structure, and important caveats (credit consumption, statelessness, double-billing risk). No gaps remain for effective agent usage.

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 clear description for 'idea'. The description adds context by framing the parameter as a 'product idea' and specifying the output categories (core keywords, etc.), which helps the agent understand the transformation.

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?

'Generate the keyword scaffolding... for a product idea, without running searches' clearly states the action and output. It distinguishes from sibling leads.find by noting that leads.find runs theme expansion itself, thus avoiding conflating the two.

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: 'when the user wants to see the search scaffolding before committing to a full run, or when planning manual outreach copy.' It also gives an explicit when-not: 'Do NOT use this as a precursor to leads.find... calling both is double-billing.' This provides clear alternatives.

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

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

The description claims the tool is idempotent, but annotations set idempotentHint=false, creating a direct contradiction. While the description adds useful behavioral details (stateless, no DB writes, no credit consumption), the contradiction undermines transparency and could mislead the agent.

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 well-organized: purpose first, then behavioral notes, usage instructions, and return fields. Every sentence adds value; there is no redundancy or fluff. It is concise for the complexity involved.

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 (multi-turn conversational refinement) and no output schema, the description fully explains the return structure (status, refined_idea, readiness_score, etc.) and the stopping condition (score ~75 or max_turns). It is self-contained and complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema descriptions, such as that 'idea' stays the same across turns, 'current_refined_idea' should be omitted on first turn, and 'history' is appended each turn. This enriches the meaning for the agent.

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 refines a SaaS idea conversationally, with a specific verb ('refine') and resource ('SaaS idea'). It distinguishes itself from siblings by warning not to call after leads.find, establishing it as a pre-search step.

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

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

The description provides explicit step-by-step usage: first turn with just idea, then subsequent turns with history. It also states when not to use ('Do NOT call idea.refine after leads.find has already run') and implies alternatives (leads.find, idea.expand).

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

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

Discloses pipeline dispatch, blocking (60-120s), credit consumption, and idempotency via run_id, adding context beyond 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?

Somewhat lengthy but every sentence adds value; front-loaded with purpose and behavior.

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

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

Given no output schema, the description thoroughly details return structure and behavior (blocking, credit, run_id), making it complete for the agent.

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

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

Adds context to the 'idea' parameter (e.g., 'the problem the user's SaaS solves', suggests refining short ideas), which improves upon the schema's basic description.

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

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

The description clearly states the tool finds ranked social posts across multiple platforms matching the user's SaaS problem, distinguishing it from siblings like leads.search and idea.refine.

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: when to call, not to call twice, pair with idea.refine, and hand run_id to outreach tools. Also warns against duplicate spending.

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 that it bypasses AI scoring, consumes one credit per call, and conditionally persists results via run_id. Annotations only provide basic hints (readOnlyHint=false), so the description carries the transparency burden well, though it could mention that it is effectively non-caching or rate-limited.

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

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

The description is well-structured: purpose first, then behavior, usage, and return info. Each sentence adds value, but it is slightly verbose for a search tool (could shorten the alternative guidance to one sentence).

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

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

With no output schema, the description explains the return format (leads array with no lead_score, plus count). It also covers credit consumption and integration with runs. For a tool with 3 parameters, it is nearly complete, though it omits any error conditions or pagination behavior.

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

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

Schema coverage is 100%, and the description adds meaning: it explains that queries are passed through unaltered, that source accepts aliases ('twitter' for 'x'), and that run_id causes persistence. This goes beyond the schema's basic descriptions.

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

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

The description states a specific verb and resource ('Run an ad-hoc search against ONE social platform') and lists the exact platforms, clearly distinguishing from the sibling leads.find via behavioral differences (bypassing theme-expansion and AI scoring).

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 says when to use this tool ('when leads.find under-fetched on a specific platform, or to test custom query phrasings') and when not to ('Do NOT use this as a substitute for leads.find when you want full pipeline behaviour'). Also provides an alternative (leads.find).

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

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

Discloses key behaviors beyond annotations: persists nothing, consumes one credit per draft, and each call is independent. No contradiction with readOnlyHint=true or other 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?

Well-structured and concise: starts with purpose, then behavior, usage, and exclusions. Every sentence is necessary and informative.

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?

Thorough for a complex tool with 9 parameters and no output schema. Covers behavior, side effects, usage patterns, and negative examples. Return format is adequately described.

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 good descriptions. The description adds extra context for outreach_action options and clarifies optional parameters like post_handle. However, schema already handles basic 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 it generates platform-tuned outreach messages for a specific lead. It distinguishes from sibling tools like outreach.plan and leads.find by specifying the purpose and context.

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 usage guidance: call once per lead from leads.find, detailed explanations of outreach_action variants, and negative instructions to avoid COMPETITOR-flagged leads and generic copy.

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 idempotent and read-only; description adds client-side synthesis, fetching via runs.get, bucketing leads at >=0.7, per-channel cadence heuristics (Reddit/X 3-4/day, others 2/day), and free. No contradictions.

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

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

Well-structured with purpose first, then behavior, usage, returns. Somewhat lengthy but every sentence adds value. Could be slightly more concise but clear.

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 single param with full schema and no output schema, description fully explains return format (multi-line text with breakdown, cadence, action register, deprioritisation rule) and prerequisites (run completed, HIGH leads >=5). 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?

Only one parameter (run_id) with 100% schema coverage, description merely restates the schema (run_id returned by leads.find). Adds no new meaning beyond schema, so 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?

Clearly states it builds a Week-1 outreach plan from HIGH-intent leads with per-channel cadence and per-category action register. Distinguishes from siblings like leads.find (raw lead dump) and outreach.draft (drafting messages).

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 call immediately after leads.find, skip if HIGH lead count is under 5 (heuristic fails), and not to call on still-running run. Provides clear when-to-use and when-not-to-use.

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

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

Annotations already declare readOnly, non-destructive, idempotent. Description adds valuable behavioral context: read-only DB query, no external calls, no credit consumed, 'safe to poll', and partial results if status is 'running'.

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?

All sentences are relevant and front-loaded. Slightly verbose with repeated mentions of 'outreach.plan or outreach.draft' and 'leads.find', but still efficient.

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

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

No output schema, but description fully explains return structure: run_id, status, idea text, results array with field details, and metadata. Covers all necessary information for the agent.

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

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

Schema coverage is 100% with run_id description already clear. Description adds meaning by specifying the source of run_id (from leads.find) and giving example format 'run_abc123', plus contextualizing its 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?

Clear verb 'Fetch the full result' and resource 'previously-started run by its run_id'. Distinguishes from siblings by mentioning runs.list for finding run_ids and leads.find for starting runs.

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

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

Explicit when-to-use scenarios: re-analyse earlier run without spending credit, hand leads to outreach.draft/plan, poll long-running job. Also states what NOT to do: 'Do NOT call this without an existing run_id; use runs.list first.'

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

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

Discloses read-only DB query, user-scoped, no external calls, no credit consumed, idempotent. Annotations already cover readOnlyHint and idempotentHint, but the description adds context on scope and credit consumption, which is helpful but not essential.

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?

Concise and well-structured: front-loaded with main functionality, then behavior, usage guidance, and return format. Every sentence adds value with no 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 no parameters and no output schema, the description fully covers the tool's purpose, behavior, usage context, and return format (fields, ordering). No gaps.

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?

No parameters in schema (100% coverage). Description doesn't need to add parameter details; baseline 4 for zero 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?

Clearly states the tool lists the user's recent lead-generation runs with specific constraints: newest first, capped at 50. Distinguishes from siblings like runs.get and leads.find by specifying the resource and scope.

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

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

Provides explicit when-to-use scenarios (revisit previous hunt, get run_id, confirm completion) and a when-not-to-use (enumerate other users' runs). Names alternative tools like runs.get and outreach.plan.

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