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

With no annotations provided, the description carries the full disclosure burden. It clarifies the temporal behavior (one-time vs recurring) and prerequisites, but omits safety details like whether this creates permanent payroll records, potential validation failures, or idempotency characteristics.

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?

Two sentences with zero waste: the first establishes purpose with examples, the second provides actionable prerequisite guidance. Information is front-loaded and every word serves the agent's selection decision.

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 11 parameters, no output schema, and no annotations, the description meets minimum viability for tool selection but leaves gaps. It adequately covers the core earning addition logic but provides no semantics for cost center fields and does not describe success behaviors or return values.

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 73%, establishing a baseline of 3. The description adds significant value by providing concrete examples for 'earningCode' (BONUS, COMM, OT) and framing the date parameters as 'one-time or recurring.' However, it fails to address the three costCenter parameters which lack schema 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 action ('Add') and resource ('earning') with specific examples (bonus, commission, stipend, overtime). It distinguishes from sibling 'add_employee' by specifying the target is an earning added 'to an employee' rather than the employee record itself.

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 prerequisite guidance by referencing 'get_company_codes' to obtain valid earning codes before invocation. While it doesn't explicitly state when NOT to use the tool, it effectively guides the agent toward necessary preparatory steps.

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?

No annotations provided, so description carries full burden. Discloses important security behavior (SSN encrypted, not stored in conversation) and return value ('Returns the new employee ID'). Does not mention error scenarios or reversibility.

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?

Four sentences with zero waste. Front-loaded with purpose ('Add a new employee'), followed by scope, security-critical SSN handling, and return value. Every sentence 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 23 parameters and mutation nature, description adequately covers essential security context (SSN encryption) and output (employee ID). Missing explicit required vs optional guidance and error handling, but sufficient for correct invocation given 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 coverage is low (43%), so description must compensate. Provides high-level categories ('personal info, job details, and compensation') mapping to parameter groups and highlights SSN specifically. However, does not detail the majority of undocumented parameters (firstName, lastName, address1, etc.).

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?

Description uses specific verbs ('Add', 'Creates') with clear resource ('employee'). Explicitly mentions 'onboarding' and 'new' to distinguish from sibling update_employee, and 'Creates' distinguishes from get/search siblings.

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 ('onboarding') indicating when to use for new hires. Includes critical usage instruction about SSN handling ('pass it directly'). Could improve by explicitly contrasting with update_employee for existing records.

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?

With no annotations provided, the description carries the full burden. It successfully discloses what data is returned (headcount, departments, job titles, reporting relationships), but does not mention safety characteristics (read-only nature), authentication requirements, or performance/caching behavior. Adequate but not comprehensive behavioral disclosure.

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?

Excellent single-sentence structure that front-loads the action ('Get a high-level workforce summary') and efficiently lists the specific data components available. Zero redundancy or filler content.

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 excellently compensates by detailing the exact structure and fields returned (headcount, status breakdown, department names, job titles, reporting relationships). For a simple single-parameter tool, this provides complete contextual information.

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% for the single companyId parameter, which includes default behavior (env var). The description adds no explicit parameter guidance, but with complete schema documentation, no additional parameter semantics are required. Baseline score appropriate 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 uses specific verb 'Get' and clearly defines the resource as a 'high-level workforce summary' with explicit details (headcount, department breakdowns, reporting relationships). It clearly distinguishes from siblings like get_employee (individual records) and search_employees (filtered search) by emphasizing aggregate company-wide data.

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?

While it does not explicitly name alternative tools, the description provides clear context that this is for aggregate company-level data ('high-level workforce summary', 'total headcount'), implicitly guiding the agent to use individual employee tools (get_employee, search_employees) for non-aggregate needs. Clear context without explicit exclusions.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context that 'Account and routing numbers are redacted' and lists what fields are visible (type, status, name). However, it omits other critical behavioral traits: error handling (what happens if employeeId is invalid), whether this is idempotent, or rate limiting concerns.

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?

Two sentences, zero waste. The first sentence front-loads the purpose; the second sentence efficiently communicates data privacy/redaction behavior. Every word 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?

For a simple read-only tool with 2 flat parameters and no output schema, the description is nearly complete. It explains what the tool retrieves and clarifies the redaction behavior. Minor gap: doesn't explicitly state the return cardinality (single vs. multiple accounts) or format, though 'accounts' plural implies a collection.

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% (both companyId and employeeId have descriptions). The description itself does not mention parameters, but with the schema fully documented, the baseline is 3. The description neither adds parameter semantics nor contradicts 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 explicitly states 'Get direct deposit accounts for an employee' — clear verb (Get), specific resource (direct deposit accounts), and scope (employee). It clearly distinguishes from siblings like get_employee (general info), get_pay_statements (pay history), and add_earnings (write operation).

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 no explicit guidance on when to use this tool versus alternatives like get_employee, nor does it mention prerequisites (e.g., needing valid employeeId). It relies entirely on the tool name to imply appropriate usage context.

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?

With no annotations provided, the description carries the full burden. It effectively discloses the return payload scope ('Returns everything: personal info...') and critical data security behavior ('SSN, FEIN, and bank info are redacted'). It misses explicit read-only/safety declarations or error handling, but covers the key behavioral traits for HR data access.

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 front-loaded with the core action in the first sentence, followed by a colon-delimited list of returned fields and a final security note. Every sentence earns its place with zero redundancy or 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?

Given the lack of output schema, the description appropriately compensates by detailing the comprehensive return payload and redaction rules. It adequately covers the tool's behavior for a simple two-parameter read operation, though it could note error cases (e.g., invalid ID).

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%, providing detailed parameter documentation including the environment variable default for companyId. The description adds minimal parameter-specific semantics beyond the schema, focusing instead on return values, which warrants the baseline score for high-coverage schemas.

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') with a clear resource ('full details for an employee') and identifier method ('by ID'). It effectively distinguishes from siblings like 'search_employees' (which implies filtering without ID) and 'update_employee' (write vs 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?

The phrase 'by ID' implies you must have the employee identifier, suggesting contrast with 'search_employees'. However, there is no explicit guidance like 'Use search_employees if you do not have the ID' or clarification on when to use 'get_direct_deposit' versus this comprehensive endpoint.

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?

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.

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

No annotations provided, so description carries full burden. Compensates by disclosing return structure (basic info: name, title, department, status, supervisor) despite lacking output schema. Does not explicitly state read-only/safety properties or pagination behavior, preventing a 5.

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?

Three sentences with zero waste: purpose (sentence 1), return value (sentence 2), workflow guidance (sentence 3). Perfectly front-loaded with the most critical selection criteria first.

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?

Comprehensive given constraints. Lacks output schema but description compensates by listing returned fields. Establishes clear relationship to sibling 'get_employee'. All 3 parameters fully documented in schema with description covering the semantic intent of the search.

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%, establishing baseline 3. Description lists searchable fields (name, title, email, employee ID) which aligns with but does not substantially augment the schema's parameter descriptions. No additional syntax or format guidance provided.

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?

Specific verb (Search) + resource (employee directory) + scope (by name, job title, email, or employee ID). Explicitly distinguishes from sibling 'get_employee' by describing this as directory search versus full record retrieval.

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 workflow guidance: 'Use this first to find someone's employee ID, then use get_employee for full details.' Clearly establishes the two-step pattern and when to prefer this tool over the sibling retrieval 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?

No annotations provided, so description carries full disclosure burden. It successfully notes the effective date requirement but fails to disclose mutation characteristics: idempotency, error behavior when employee missing, whether partial updates are supported, or what the response indicates.

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?

Optimal structure: single opening sentence establishes purpose, followed by categorized field list, ending with critical constraint. No redundant words despite high parameter complexity. Every sentence 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 high schema coverage (100%) and complex nested structure, the description provides sufficient context by mapping schema fields to business concepts (cost center, supervisor, benefit class). Missing return value documentation is acceptable without output schema; only minor gap is lack of error scenario mention.

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, baseline is 3. The description adds value by categorizing the nested 'updates' fields into logical groups (personal, job, compensation) and emphasizing the effective date constraint that applies across multiple nested objects, aiding comprehension of the complex schema structure.

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 specific verb 'Update' with resource 'employee's information' and comprehensively lists updatable field categories (personal info, job details, compensation, status, benefits). The verb clearly distinguishes this from sibling 'add_employee' (create vs update semantics).

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 critical constraint that 'All changes require an effective date where applicable,' which guides temporal usage. However, lacks explicit when-not-to-use guidance (e.g., distinguishing from 'add_employee' for new hires) or prerequisite mentions (e.g., employee must exist).

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