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

Beyond the annotations (read-only, open-world, non-destructive), the description discloses the mechanism ('queries a real search engine (Brave Search)... reads back only the public snippet text'), explicitly states it does NOT scrape LinkedIn, and explains error handling (missing BRAVE_API_KEY, no candidates found). This adds significant behavioral context.

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

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

Although the description is longer than average, it is tightly structured with clear sections: purpose, args, returns, examples, error handling. The content is front-loaded with the core purpose, and every section adds necessary information without 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 tool with 4 parameters, no output schema in structured fields, and external dependencies, the description is remarkably complete. It covers purpose, mechanism, parameter semantics, full return schema, examples, error handling, and the recommended next tool. This gives an agent everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples that map natural language to parameter values ('Find e-mobility companies in India...' → category, region, extra_keywords) and explains how the returned 'domain' integrates with leadgen_enrich_company. This goes beyond the schema's property 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 opens with a specific verb ('Searches') and clearly states the resource (public web) and the output (de-duplicated, signal-ranked candidate list for one of four practice areas). It distinguishes itself from sibling tools by explicitly directing users to leadgen_enrich_company for deeper enrichment and providing a 'Don't use when' example.

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 concrete 'Use when' examples with natural-language-to-parameter mappings and a clear negative case ('Don't use when: you already have a company name...'). It also recommends the next step (leadgen_enrich_company), giving explicit guidance on when to use this tool vs 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?

Beyond the annotations (readOnlyHint=true, etc.), the description adds substantial behavioral context: legitimate/ToS-compliant sources, partial results when domain is unreachable, error conditions for BRAVE_API_KEY, and the multi-category coverage. It transparently documents limitations and edge cases.

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

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

The description is long but well-structured with sections (overview, Args, Returns, Examples, Error Handling). Every section contributes necessary information, and the return JSON schema is essential given no output schema. The first sentence front-loads the core purpose, and the length is justified by the tool's complexity.

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

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

The description fully equips the agent to use the tool: it explains what enrichment covers, provides a detailed return schema, error handling, and explicit examples. Despite no output schema in annotations, the description carries the burden and fulfills it completely.

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 complete descriptions for both parameters (100% coverage). The description adds value by explaining the impact of the optional domain parameter ('enrichment is much richer with it') and showing example values in context. This goes beyond the schema's basic type/length constraints.

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: 'Builds a technical profile for a specific company by crawling its own public website... and cross-referencing an indexed LinkedIn snippet plus public job postings.' It uses specific verbs and resources, and distinguishes from siblings by explicitly naming leadgen_score_lead as an alternative for single-category 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 provides explicit usage guidance with 'Use when' examples and a 'Don't use when' section that names the alternative tool (leadgen_score_lead). It also clarifies when to include the optional domain parameter, making the decision framework complete.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses critical behavioral traits: results are UNVERIFIED candidates parsed from snippets, the 'verified' field is always false, and the tool never finds emails. It also explains error handling for missing API keys and empty searches, giving the agent a full picture of caveats and failure modes.

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

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

The description is long but well-structured into sections: overview, IMPORTANT note, Args, Returns, Examples, and Error Handling. Every section serves a purpose, and the first sentence establishes the core function. The Returns JSON block is somewhat verbose but compensates for the lack of an output schema, so it earns its place.

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

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

Given the tool's moderate complexity (2 params, 1 required) and rich annotations, the description goes beyond the minimum by supplying return format, error cases, default behavior, and usage examples. The lack of an output schema is fully compensated by the inline JSON schema, making the tool's behavior and expected output completely clear.

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 describes both parameters (100% coverage), so the baseline is 3. The description adds value by listing the default titles tried when role_hint is omitted, and by providing concrete example mappings from natural language to parameter values. This goes beyond the schema's generic description but does not fully transform parameter understanding.

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

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

The description opens with a specific verb phrase: 'Searches public, search-engine-indexed snippets... for a likely engineering decision-maker at a company.' It clearly identifies the resource (public snippets), the target role (CTO, VP Engineering, etc.), and the output (candidates). It also distinguishes itself from a LinkedIn scrape, setting it apart from common contact-finder 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?

The description provides explicit 'Use when' examples ('Who leads engineering at ElectreeFi?') and an explicit 'Don't use when' exclusion (need a verified email address). It also advises manual confirmation before outreach. However, it does not name sibling tools as alternatives (e.g., leadgen_enrich_company for verified data), so it falls just short of the top score.

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, idempotentHint=true, and destructiveHint=false, and the description adds crucial context: 'This tool does NOT send anything — it only drafts text for you to review and send yourself.' It also discloses validation behavior: 'Returns a validation error if friction_point is missing or too short — this tool refuses to draft a pitch with nothing specific to say.' These details go well beyond the structured metadata.

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 (purpose, args, returns, examples, error handling) and front-loads the core purpose. Despite its length, every section earns its place by providing necessary operational detail for a tool with a specialized framework. No fluff or repetition of schema property names.

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 includes an inline JSON example of the return structure, covers error behavior, defines the framework's principles, and gives practical usage guidance. For a six-parameter tool with a specified framework, this description fully equips an agent to select and invoke it correctly without reference to external documentation.

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 enhances this by explaining the strategic role of key parameters, e.g., category 'determines which authority/experience line is used' and friction_point should be 'pulled from leadgen_enrich_company's matched_signals or crawled content.' It also warns that 'generic friction points make for generic (worse) pitches,' adding guidance not present 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?

The description clearly states the tool's function: 'Drafts two personalized outreach email variants for a qualified lead' using a specific framework. It distinguishes itself from pipeline siblings (discovery, enrichment, scoring, contact-finding, lead management) by focusing on content generation, not data retrieval or lead manipulation.

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

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

The description provides explicit usage guidance: 'Use when: you've scored a lead as "hot" and identified its top missing/matched signal' and 'Don't use when: you haven't identified a real, specific friction point yet... go back to leadgen_enrich_company first.' This gives clear when-to-use, when-not-to-use, and points to the appropriate alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the return format ('JSON: { "leads": StoredLead[], "count": number }') and the fields of StoredLead, which helps the agent understand what the tool produces. It does not contradict 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 well-structured with a one-sentence summary, an Args section, a Returns section, and Examples. Every element adds value and there is no unnecessary verbosity. The use of code blocks and examples makes it easy to parse.

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

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

Despite having no output schema, the description fully documents the return structure. It covers the optional parameters, provides usage examples, and given the simple nature of the tool (list with filters) and the rich annotations, the description is complete enough for an agent to use it correctly. Sibling tools are also distinguishable.

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?

With schema description coverage at 0%, the description compensates by explaining that category, tier, and status are optional filters, and provides examples showing how each filter can be used. It also describes the StoredLead fields, which clarifies what the filters operate on. This goes beyond the raw schema enums, though it could be more explicit about the meaning of each parameter.

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 'Lists saved leads from the pipeline, optionally filtered by category, tier, or status.' This uses a specific verb ('lists') and resource ('saved leads from the pipeline'), and distinguishes from sibling tools like discover, enrich, score, save, update, which perform different actions.

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

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

The description provides concrete usage examples: 'Use when: "Show me all hot e-mobility leads" -> category="e_mobility", tier="hot"' and 'Use when: "What's still uncontacted?" -> status="new"'. This gives clear context for when to use the tool and how to map natural language queries to parameters, though it does not explicitly mention alternatives or when not to use it.

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

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

Beyond the sparse annotations (readOnlyHint=false), the description discloses storage location (local JSON file), persistence behavior, and that it returns a generated 'id' needed for leadgen_update_lead. This is rich behavioral context not available elsewhere.

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 an Args list, Returns note, and Examples section. Every sentence adds value—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?

With 10 parameters, no output schema, and minimal annotations, the description covers all critical aspects: persistence semantics, storage details, return value, and usage context. It is complete enough 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 0%, but description fully compensates by listing each parameter with required/optional status and origin (e.g., 'from leadgen_score_lead', 'from leadgen_find_contact'). This adds meaning beyond the bare types/enums 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?

The description clearly states the tool's purpose: "Persists a qualified lead to the local pipeline store." This uses a specific verb ('persists') and resource ('lead'), and distinguishes it from siblings like leadgen_update_lead (updating existing leads) and leadgen_list_leads (listing).

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 guidance is provided: "Use when: you've scored a company as hot/warm and want to track it for follow-up" and "Don't use when: you're just browsing candidates." This clearly states when to use vs. avoid.

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?

Even with readOnlyHint=true, the description adds rich behavioral context: it shares a cache with leadgen_enrich_company, explains tier and confidence thresholds, defines the low-confidence+hot-tier caveat, and details error handling (including the score=0/cold/low no-signal case). No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (Args, Returns, thresholds, Examples, Error Handling). Every sentence adds operational or decision-relevant detail, and the first sentence front-loads the core purpose. 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?

The tool is moderately complex (3 params, no output schema in the tool definition, error cases, thresholds). The description compensates by providing a full return schema, threshold values, confidence semantics, cache-sharing behavior, and error handling. Contextually complete for an AI 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%, so the schema already documents all parameters. The description adds value by specifying that domain makes scoring 'more reliable,' clarifying that category is a practice area, and providing a concrete example mapping natural language to parameter values. This goes beyond the schema's basic 'Company name' / 'Which practice area' 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 opens with a specific verb and resource: 'Computes a weighted 0-100 ICP fit score for one company against one 72BPM practice area.' It clearly distinguishes this from sibling tools by explaining the single-category scoring focus and pointing to leadgen_enrich_company for multi-category breakdowns.

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 'Use when' and 'Don't use when' examples with a concrete query and a named alternative: 'Don't use when: you want the full multi-category breakdown (use leadgen_enrich_company instead).' This is model-level guidance for when to select this tool versus a sibling.

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 safety profile (not read-only, not destructive, idempotent). Description adds that it returns the updated lead record or an error if lead_id doesn't exist, plus the at-least-one constraint. 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?

Format is front-loaded with purpose, uses a structured Args list, constraint line, and return statement. Every sentence earns its place; 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?

For a 3-param update tool with no output schema, it covers return values and error behavior, usage examples, and constraints. Slightly sparse on notes semantics, but overall adequate given annotations.

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 low (33%); description repeats the lead_id source (already in schema) and enum values for status, but adds no meaning for notes beyond type. The only new info is the at-least-one requirement, which is more a usage rule 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?

States clearly it updates a saved lead's status and/or notes, with examples of when (after outreach/reply). Distinguishes from siblings like save_lead (create) and list_leads (read).

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

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

Provides clear context (after outreach/reply) and a hard constraint (at least one of status/notes required). Does not explicitly name alternatives, but the example plus sibling set make the intended use evident.

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