Harmonic MCP Server

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.