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

The description adds valuable behavioral context beyond annotations: it explains that this tool marks results as 'seen' to prevent them from appearing in future calls, which clarifies the 'reset' effect. Annotations provide hints (e.g., not read-only, idempotent, non-destructive), but the description enhances this by detailing the queue management aspect. No contradiction with annotations is present.

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, usage, input, workflow), front-loading the core action. Each sentence adds value without redundancy, such as explaining the tool's effect and integration in a workflow. It is appropriately sized for 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?

Given the tool's moderate complexity (single parameter, no output schema), the description is complete: it covers purpose, usage guidelines, behavioral effects, and workflow integration. Annotations provide additional hints (e.g., idempotent), and the description fills gaps by explaining the 'reset' functionality, making it sufficient for an agent to use the tool effectively.

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

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

Schema description coverage is 100%, with the input schema fully documenting the 'search_id' parameter. The description adds minimal semantics by listing 'search_id' in the 'Input' section but does not provide additional meaning (e.g., format examples or sourcing guidance) beyond what the schema already states. This meets the baseline for high schema coverage.

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 explicitly states the specific action ('Mark all net new results as "seen"') and the resource ('saved search net new results'), clearly distinguishing it from sibling tools like harmonic_get_saved_search_net_new_results (which retrieves results) and harmonic_get_saved_search_results (which may retrieve all results). The purpose is precise and avoids tautology.

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 includes a dedicated 'When to use' section that explicitly states to call this tool 'AFTER you've processed net new results to reset the queue,' and it names the alternative tool (harmonic_get_saved_search_net_new_results) for comparison. It also provides a workflow with step-by-step guidance, making usage context clear and actionable.

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

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

The description adds valuable behavioral context beyond what annotations provide: it explains the similarity algorithm ('characteristics like industry, stage, business model'), describes the return format in detail with JSON structure, and provides 'Next Steps' guidance. While annotations cover safety (readOnly, non-destructive, idempotent), the description adds practical implementation details. No contradiction with annotations exists.

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

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

The description is well-structured with clear sections (What it does, Input, Returns, Next Steps, Example workflow), front-loads the core purpose, and every sentence earns its place by providing distinct value. It's comprehensive without being verbose, using bullet points and JSON examples efficiently.

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, rich annotations, and 100% schema coverage, the description provides excellent completeness: it explains the algorithm, provides input examples, details the return format (compensating for no output schema), gives next steps, and includes a full workflow example. It covers all necessary aspects for an agent to understand and use this tool effectively.

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 100% schema description coverage, the baseline is 3, but the description adds meaningful context: it clarifies company_id accepts 'either numeric ID or full URN' with examples, explains the algorithm behind similarity matching, and provides workflow context that helps understand parameter usage. However, it doesn't add significant value beyond the well-documented schema for size and response_format 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 the tool's purpose with specific verb ('find') and resource ('companies similar to a given company'), and explicitly distinguishes it from siblings by mentioning the core VC use case and referencing harmonic_lookup_company and harmonic_get_company as complementary tools. It goes beyond the title to explain the algorithm and use case.

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 guidance on when to use this tool versus alternatives through the 'Example workflow' section, which shows harmonic_lookup_company should be used first to find a company, then this tool for similarity, then harmonic_get_company for details. It also mentions this is the 'core use case for VCs' and references sibling tools by name.

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

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

The description adds valuable behavioral context beyond annotations. While annotations cover read-only, open-world, idempotent, and non-destructive traits, the description discloses response size details (~3KB default, ~368KB all fields), field filtering mechanics, and the note about using a batch endpoint internally. This provides practical implementation insights not captured in 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 clear sections (Input, Response sizes, Default fields, When to use, Note), front-loaded with the core purpose. Every sentence adds value—no fluff or repetition. It efficiently communicates essential information in a compact format.

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 (3 parameters, no output schema) and rich annotations, the description is complete. It covers purpose, usage, parameters, behavioral details (response sizes, field filtering), and practical notes. The absence of an output schema is compensated by explaining default fields and response formats, making it sufficient for an agent to use the tool effectively.

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 100% schema description coverage, the baseline is 3. The description adds meaningful semantics: it clarifies company_id accepts both numeric IDs and full URNs with examples, explains include_fields for optimal response size with an example, and mentions default fields returned. However, it doesn't cover the response_format parameter, leaving a minor gap.

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: 'Get company details by ID with field filtering for optimal response size.' It specifies the verb ('Get'), resource ('company details'), and key functionality ('field filtering'), distinguishing it from siblings like harmonic_search_companies (search) or harmonic_get_company_connections (connections).

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 provides usage guidelines under 'When to use:' with three specific scenarios: after harmonic_search_companies, after harmonic_find_similar_companies, or when you have a company ID from another source. This directly addresses when to use this tool versus alternatives, including named sibling tools.

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 provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations: it explains what 'connection_sources' mean (EMAIL, LINKEDIN, CALENDAR with definitions), specifies the return format with a detailed example, and clarifies the tool's purpose for 'warm introductions in VC deal flow.' While it doesn't mention rate limits or auth needs, it provides meaningful behavioral context that annotations don't cover.

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 (What it does, Returns, Connection sources, Use case), front-loads the purpose, and every sentence adds value. It efficiently communicates key information without redundancy, making it easy for an agent to parse and understand.

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 (4 parameters, 100% schema coverage), rich annotations, and no output schema, the description provides excellent completeness. It explains the tool's purpose, usage context, return format with examples, connection source meanings, and practical application. This compensates well for the lack of output schema and gives the agent sufficient context to use the tool effectively.

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 parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain company_id format or pagination behavior). However, it implies the tool uses company_id to find connections, which aligns with schema documentation. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description explicitly states the tool's purpose: 'Find which team members have connections to a company' and 'Returns your team's network connections to people at the target company, showing who knows whom and how they're connected.' This is a specific verb ('find'/'returns') + resource ('team members' connections to a company'), and it clearly distinguishes from siblings like harmonic_get_company (general company info) or harmonic_get_company_employees (employee list without connections).

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 guidance on when to use this tool: 'Before reaching out to a company, find if anyone on your team has a warm intro path.' It also distinguishes from siblings by focusing on connections rather than general company data or employee lists. The 'Use case' section clearly defines the context for 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?

The annotations already provide excellent behavioral hints (readOnlyHint=true, destructiveHint=false, etc.), but the description adds valuable context beyond these. It discloses that 'Documentation had incorrect values' and provides tested filter values, which is crucial operational knowledge. It also describes the return format with an example response showing pagination (hasMore field) and data structure. While it doesn't mention rate limits or authentication needs, it adds significant practical guidance beyond the annotations.

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

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

The description is well-structured with clear sections (Input, Returns, Example Response, Common workflows) and front-loads the core purpose. Most sentences earn their place by providing practical guidance. However, the 'Note' about incorrect documentation values, while valuable, could be more concise, and the example response takes multiple lines that might be excessive for a description. Overall efficient but with minor verbosity.

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 (6 parameters, filtering logic) and the absence of an output schema, the description provides excellent completeness. It explains what the tool returns ('Person URNs that you can use with harmonic_get_person'), shows a detailed example response with pagination indicators, provides workflow examples, and includes important operational notes about tested filter values. This adequately compensates for the lack of output schema and provides comprehensive context for 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?

With 100% schema description coverage, the schema already documents all 6 parameters thoroughly. The description adds some semantic context by explaining that company_id accepts 'Numeric ID or URN' (schema says 'Company ID or URN') and providing usage notes about filter values. However, it doesn't add substantial meaning beyond what's already in the schema descriptions and enum values. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Get employees of a company with filtering options.' This is a specific verb ('Get') + resource ('employees of a company') + scope ('with filtering options'), which distinguishes it from sibling tools like harmonic_get_company (which gets company details) or harmonic_get_person (which gets individual person details). The description effectively communicates the tool's distinct function within the sibling set.

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

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

The description provides clear context for when to use this tool through the 'Common workflows' section, which gives specific examples like getting founders, leadership, or former employees. It also mentions using the returned Person URNs with harmonic_get_person for full details, establishing a workflow relationship. However, it doesn't explicitly state when NOT to use this tool or name direct alternatives among siblings, which prevents a perfect 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 provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about what data is returned (full details including contact info, education, work experience) and clarifies the relationship with harmonic_lookup_person, enhancing behavioral understanding 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?

The description is efficiently structured with clear sections (purpose, input, returns, when to use), uses bullet points for readability, and every sentence adds value without redundancy. It's appropriately sized and front-loaded with the core purpose.

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

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

Given the tool's moderate complexity, comprehensive annotations, and 100% schema coverage, the description provides complete context. It explains the tool's purpose, usage scenarios, parameter semantics, and return data, compensating for the lack of output schema by detailing what data is returned.

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 100% schema description coverage, the schema already documents both parameters well. The description adds meaningful context by providing concrete examples of person_id values ('161780079' and URN format) and clarifying that response_format controls output format, which complements the schema's enum 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 specific action ('Get full person details by ID') and resource ('person'), distinguishing it from sibling tools like harmonic_lookup_person by emphasizing it's for use after obtaining IDs from other operations. The verb 'Get' combined with the resource 'person details' provides precise 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 provides when-to-use guidance in a dedicated section, listing three specific scenarios: after harmonic_get_company_employees, when you have a person ID from another response, and to expand on a person URN from search results. This clearly distinguishes usage from alternatives like harmonic_lookup_person.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it explains the prerequisite (subscription requirement with 404 error if not met), clarifies what 'net new' means with examples, specifies response sizes (~27KB per result), and outlines the workflow with the sibling tool 'harmonic_clear_saved_search_net_new'. No contradictions with annotations are present.

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 (prerequisite, explanation of 'net new', input, response sizes, workflow, use cases), using bold headers for emphasis. Every sentence adds value—no redundant information. It is front-loaded with the core purpose and efficiently conveys necessary details without verbosity.

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 (incremental results with prerequisites and workflow), the description is complete. It covers purpose, usage guidelines, behavioral traits (prerequisite, response sizes, workflow), and contextualizes parameters. Although there is no output schema, the description provides enough context (e.g., response sizes, use cases) for effective agent use. Annotations further enhance completeness by indicating safety and idempotency.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds marginal value by grouping parameters under an 'Input:' section and providing a brief explanation of 'new_results_since' (e.g., 'Optional UTC datetime'), but it doesn't introduce new semantics beyond the schema. However, it compensates by explaining the tool's purpose and workflow, which contextualizes parameter usage effectively.

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 explicitly states the tool's purpose: 'Get only NEW results from a saved search since your last check. This is the incremental/delta endpoint for monitoring deal flow.' It uses specific verbs ('get', 'monitoring') and distinguishes from sibling tools like 'harmonic_get_saved_search_results' by emphasizing the 'net new' incremental nature. The title reinforces this distinction.

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 guidance on when to use this tool: 'This is the incremental/delta endpoint for monitoring deal flow.' It includes a prerequisite ('You must subscribe to the saved search via Harmonic web UI first'), workflow steps, and specific use cases (e.g., 'Daily deal flow monitoring for investors'). It clearly differentiates from regular search results tools by focusing on new matches since subscription.

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, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: the WARNING about large response sizes (~81KB-135KB), that field filtering does NOT work, each result contains full company data (~27KB), and pagination guidance. It doesn't contradict annotations, but provides critical performance and data volume information not captured in structured fields.

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 (WARNING, Input, Returns, Use cases) and front-loads key information. Every sentence adds value, though the detailed JSON example could be considered slightly verbose. However, given the complexity of the return data and lack of output schema, this detail is justified.

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 (4 parameters, large data returns, pagination needs) and absence of an output schema, the description provides excellent completeness. It covers purpose, usage guidance, performance warnings, parameter semantics, detailed return format example, and practical use cases. The annotations provide safety information, while the description fills all other contextual 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?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context: it explains the practical implications of the 'size' parameter (response sizes in KB, default vs max), clarifies that 'search_id' comes from harmonic_list_saved_searches, and provides a detailed example of return data structure. While the schema documents parameters technically, the description adds practical usage 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: 'Get results from a saved search. Returns full company/person data matching the search criteria.' It specifies the verb ('Get'), resource ('results from a saved search'), and distinguishes it from siblings like harmonic_list_saved_searches (which lists searches) and harmonic_search_companies (which performs new searches).

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

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

The description provides explicit guidance on when to use this tool: 'Use pagination (cursor) for more results rather than large sizes.' It also implicitly distinguishes it from siblings by specifying it works with saved searches (search_id from harmonic_list_saved_searches) rather than performing new searches. The 'Use cases' section further clarifies practical applications.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context about what 'saved searches' are ('enable monitoring deal flow and tracking companies over time'), their types (COMPANIES_LIST, PERSONS), and that they contain 'specific filter criteria', which goes beyond the annotations.

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

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

The description is well-structured with clear sections (What it does, Returns, Search types, Next steps, Use cases), front-loading the core purpose. Every sentence adds value without redundancy, efficiently covering purpose, output format, domain context, and usage 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?

Given the tool's simplicity (1 optional parameter, no output schema but detailed return example provided), rich annotations, and clear sibling differentiation, the description is complete. It explains what saved searches are, their types, return structure, and next steps, leaving no gaps for the agent to understand and invoke this 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?

With 100% schema description coverage for the single parameter (response_format), the schema already fully documents its purpose, enum values, and default. The description adds no additional parameter information, so it meets the baseline of 3 where the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Get all saved searches') and resource ('accessible to your Harmonic account'), distinguishing it from siblings like harmonic_get_saved_search_results which retrieves actual results. It explicitly notes these are also called 'Saved Views' in the UI, providing precise domain terminology.

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 guidance on when to use this tool ('List all team deal flow monitors', 'Find a specific saved search by name', 'Check when a search was last updated') and directs to the alternative tool harmonic_get_saved_search_results for retrieving matching companies/persons. It clearly separates metadata listing from result retrieval.

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

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

The description adds valuable behavioral context beyond annotations: it explicitly states 'This is a READ operation (does not create data)' (reinforcing readOnlyHint), explains the HTTP 404 behavior with background enrichment, and provides rich details about return data structure. While annotations cover safety (readOnlyHint, destructiveHint) and idempotency, the description adds practical implementation details about response format and error handling.

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 (What it does, Supported identifiers, Returns, Example, HTTP 404 Note), each earning its place. It's comprehensive yet efficient, with no redundant information. The front-loaded statement clearly establishes the tool's purpose before diving into details.

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

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

Given the tool's complexity (10 parameters, no output schema), the description provides excellent completeness: it explains what the tool does, how to use parameters, what data returns, includes a detailed example response, and covers error behavior. The annotations provide safety context, and the description fills all remaining gaps without needing an output schema.

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 100% schema description coverage, the baseline is 3. The description adds significant value by organizing parameters into 'Supported identifiers' with clear examples and the 'use ONE' constraint, plus explaining the response_format parameter's purpose. It provides semantic grouping and usage guidance that goes beyond the schema's individual parameter 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 clearly states the specific verb ('look up', 'finds and enriches') and resource ('company profile') with explicit scope ('by domain, website URL, or social media URL'). It distinguishes from siblings like harmonic_search_companies by focusing on lookup by identifiers rather than search queries, and from harmonic_get_company by being identifier-based rather than ID-based.

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

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

The description provides clear context for when to use this tool ('by domain, website URL, or social media URL') and mentions 'use ONE' identifier, which helps avoid misuse. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the context implies it's for identifier-based lookup versus search-based approaches.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it clarifies this is a 'READ operation (does not create data)', explains the HTTP 404 behavior (may trigger background enrichment with retry advice), and details the enrichment process and return data structure, enhancing the agent's understanding.

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

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

The description is well-structured with clear sections (What it does, Input, Returns, HTTP 404 Note, Use cases), making it easy to parse. It is appropriately sized with no redundant information, though the detailed JSON example in 'Returns' could be slightly verbose; every sentence adds value, such as the enrichment and retry advice.

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 (enrichment with potential background processes), rich annotations, and lack of output schema, the description is highly complete. It covers purpose, usage, behavioral traits (like 404 handling), parameter details, and example output, providing all necessary context for an agent to invoke the tool correctly without needing an output schema.

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

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

Schema description coverage is 100%, with both parameters (linkedin_url and response_format) well-documented in the schema. The description adds minimal value beyond the schema: it provides an example URL format for linkedin_url and lists return fields, but does not explain parameter interactions or usage nuances. Baseline 3 is appropriate given the schema's comprehensive coverage.

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 specific action ('Look up a person by their LinkedIn URL') and resource ('person's profile'), distinguishing it from sibling tools like harmonic_get_person or harmonic_search_typeahead. It explicitly mentions enrichment and the type of data returned (work history, education, contact info, social links), providing a comprehensive understanding of its function.

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 includes a 'Use cases' section with specific scenarios (research before meetings, contact info for outreach, verifying roles), which provides clear context for when to use this tool. However, it does not explicitly state when NOT to use it or name alternatives (e.g., harmonic_get_person for non-LinkedIn-based lookups), missing full sibling differentiation.

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, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it explains the AI-powered natural language understanding, pagination behavior with cursors, and the limited return format (URNs requiring harmonic_get_company for details). No contradiction with annotations exists.

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

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

The description is well-structured with clear sections (What it does, Example queries, Returns, Next Steps) and efficiently conveys information. However, the JSON return example is somewhat redundant since there's no output schema, and the 'Returns' section repeats similar information in two formats, slightly reducing conciseness.

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 (natural language search with 5 parameters), rich annotations (covering safety and idempotency), and lack of output schema, the description is highly complete. It explains the tool's purpose, usage, behavioral traits, return format, and integration with other tools, providing all necessary context for an AI agent to use it effectively.

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

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

Schema description coverage is 100%, so the schema already fully documents all 5 parameters. The description adds minimal parameter semantics beyond the schema—it provides example queries that illustrate the 'query' parameter usage but doesn't explain parameter interactions or additional context. This meets the baseline 3 when schema does the heavy lifting.

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

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

The description explicitly states 'Search for companies using natural language queries' with the specific verb 'search' and resource 'companies', clearly distinguishing it from sibling tools like harmonic_lookup_company (which appears to be a direct lookup) and harmonic_find_similar_companies (which likely operates on existing companies). The 'primary entry point for discovering companies' phrase further establishes its distinct role.

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 guidance on when to use this tool ('primary entry point for discovering companies') and what to do next ('Use harmonic_get_company for full company details'). It distinguishes from alternatives by emphasizing natural language queries versus more specific lookup tools in the sibling list, though it doesn't explicitly name 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?

The description adds valuable behavioral context beyond annotations: it explains the ranking system ('Lower ranking_score = better match'), provides example queries showing partial matching behavior, and describes the return format with a JSON example. While annotations cover safety (readOnly, non-destructive), the description adds practical implementation details that help the agent understand how to interpret results.

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 (What it does, Example queries, Returns, When to use, When NOT to use) that make information easy to find. While comprehensive, some sections could be more concise - the JSON example is detailed but necessary for clarity. Overall, most sentences earn their place by adding distinct value.

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 search tool with comprehensive annotations (readOnly, openWorld, idempotent) and 100% schema coverage, the description provides excellent contextual completeness. It explains the tool's behavior, provides concrete examples, shows the return format, and gives clear usage boundaries. The absence of an output schema is compensated by the detailed JSON example in the description.

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 100% schema description coverage, the schema already documents both parameters thoroughly. The description adds marginal value through example queries that illustrate the 'query' parameter usage ('Harmonic', 'stripe.com', 'Str'), but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

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 with specific verbs ('quick autocomplete search', 'returns company matches') and resources ('companies by name or domain'). It explicitly distinguishes from sibling harmonic_search_companies by stating this is for 'fast lookups when you know part of the company name' versus 'complex searches with multiple criteria'.

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 guidance with dedicated 'When to use' and 'When NOT to use' sections. It lists specific use cases (quick lookup, autocomplete suggestions, finding by domain) and explicitly names the alternative tool (harmonic_search_companies) for complex searches, giving clear boundaries for tool selection.

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