Get Company Employees

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.