get_pay_statements

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

With no annotations provided, the description carries the full burden. It effectively discloses the return payload structure—specifying both summary fields (gross/net pay, hours) and line-item details (taxes, deductions, earnings)—which compensates for the missing output_schema. However, it does not explicitly confirm this is read-only/safe or describe error cases (e.g., invalid year).

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 consists of three efficiently structured sentences: purpose (sentence 1), return value details (sentence 2), and optional filtering capability (sentence 3). There is no redundant or wasted text; every clause adds specific value about functionality or return structure.

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 absence of an output schema, the description adequately compensates by detailing the return structure (summary vs. line-item data). With 100% schema coverage for inputs and clear required parameter indication, the definition is complete for invocation, though it could benefit from mentioning data availability constraints or error scenarios.

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 input schema has 100% description coverage, documenting all four parameters including the optional nature of checkDate and companyId default behavior. The description reinforces the year-based retrieval and optional date filtering, but does not add semantic meaning beyond what the schema already provides, warranting the baseline score.

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 uses a specific verb ('Get') and resource ('pay statement data') and clearly scopes it to 'by year'. It effectively distinguishes from siblings like get_direct_deposit (which retrieves setup/configuration, not pay statements) and get_employee (profile data) by specifying it returns payroll details including 'gross pay, net pay, hours' and line-item 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 mentions the optional checkDate filter ('Optionally filter to a specific check date'), implying when to use that parameter. However, it lacks explicit guidance on when to choose this over get_direct_deposit or prerequisites like requiring an existing employeeId from get_employee/search_employees.

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