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

The description adds useful behavior beyond annotations: it states that leave management write permissions are required and that the tool returns a confirmation with the generated request ID. Annotations already indicate a non-read, non-idempotent mutation, so the description supplements rather than contradicts them.

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-organized with a clear one-line purpose followed by structured Args and a closing permissions note. It is somewhat long and duplicates schema content, but for a 10-parameter tool it remains scannable and front-loaded with the core action.

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?

The description covers the core workflow: required parameters, optional parameters with defaults, output format, return value, and permission requirements. There is no output schema, so the note about returning a confirmation with request ID is valuable. It does not discuss error cases or approval behavior, but those are not essential for invoking the 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?

Schema description coverage is 100%, and the description largely restates the same parameter meanings, defaults, and formats found in the schema. It adds minimal extra semantic value, though it does present defaults and session values in a readable way. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Submit a new leave request for an employee in Keka.' This goes beyond the tool name and clearly distinguishes the create action from sibling list/get tools. It also names the relevant parameter source, keka_list_leave_types, reinforcing the tool's specific 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 makes the use case explicit ('Submit a new leave request') and points to the correct sibling for finding leave type IDs. It does not explicitly state when not to use this tool versus related list/get leave tools, but the create-versus-read distinction is clear from the description and sibling 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?

Annotations already declare this as read-only, idempotent, and non-destructive, so the bar for behavioral disclosure is lower. The description adds valuable behavioral details beyond the annotations: the API's 90-day range limit, default to the last 30 days, pagination parameters, and output format selection. No contradiction exists between the description and 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 an opening purpose, API limit note, bullet-style Args list, Returns summary, and Examples. It is longer than the minimum but each section earns its place; slight redundancy exists in repeating the 90-day limit in both prose and the Args list.

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 tool with no output schema, the description compensates by summarizing the return structure and key fields. It covers defaults, constraints, parameter usage, and examples, giving an agent everything needed to invoke the tool correctly and interpret results.

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 baseline is 3, but the description adds meaning beyond the schema by explaining how to combine parameters (e.g., date ranges and employee IDs) and illustrating with concrete examples. It also mentions the default date window and response_format options, enriching the agent's understanding.

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 states a specific verb ('Retrieve') and resource ('attandance records for employees from Keka'), and further clarifies the returned data (clock-in, clock-out, total hours, shift, status). This clearly distinguishes it from sibling tools that list leave types, employees, or pay groups.

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 usage context with examples, such as viewing attendance for a team this month or checking a specific employee's presence on a given day. It also notes the default 30-day window and maximum 90-day range, which guides correct invocation. It does not explicitly name alternative tools or exclusion criteria, so it stops short of 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by specifying the output format option and summarizing the returned employee profile contents.

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 concise and well-structured with a clear first sentence, an Args section, and a Returns section. It repeats some schema information, but the important operational hint and return summary are front-loaded and every section 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 2-parameter read tool with no output schema, the description is complete: it explains the purpose, the required parameter source, the optional format, and the contents of the returned employee profile. Safety is already covered by annotations.

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%, so the baseline is 3, but the description adds value by explaining that employeeId can be discovered via keka_list_employees and by clarifying the response_format default and its human/machine readability. This goes beyond the schema's property definitions.

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 opening sentence uses a specific verb ('Retrieve') with a clear resource ('full details for a single employee') and the key identifier (Keka employee ID). This clearly distinguishes it from the sibling list tools and other getters like get_leave_balances and get_attendance.

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 tells the agent to use keka_list_employees to find the required employeeId, providing a concrete prerequisite. It does not explicitly state when not to use this tool, but the single-employee scope makes the intended context clear among the siblings.

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 mark the tool readOnly, idempotent, and non-destructive, so the description is not burdened with stating safety. It adds useful behavioral context by specifying that omitting employeeIds returns all employees and that the output is a per-employee, per-leave-type breakdown of opening, earned, taken, pending, and closing balances.

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 a clear one-line purpose followed by Args and Returns sections, making it easy to scan. The Args section repeats schema information somewhat, but the overall length is justified by the parameter details and the return breakdown.

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?

There is no output schema, so the description's Returns section provides the needed high-level response shape: per-employee and per-leave-type balances. It also documents all four parameters with constraints and defaults, leaving no major gap for an agent to call this read-only 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?

Schema description coverage is 100%, so the baseline is 3 because the schema already documents all parameters and defaults. The description's Args section mostly duplicates the schema, adding only the useful but minor clarification 'omit for all employees.'

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 opens with a clear verb and resource: 'Retrieve leave balances for employees in Keka.' This distinguishes it from sibling tools like list_leave_requests, list_employees, and get_attendance, so an agent can identify its purpose without ambiguity.

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 implies when to use the tool by focusing on leave balances, and it notes the optional all-employees behavior via employeeIds. However, it does not explicitly state when to prefer this tool over a sibling, nor does it provide exclusions such as 'use keka_list_leave_requests for request details instead.'

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the exact return payload (name, email, phone, interview stage, application date, source, status) and mentions pagination and format controls, giving the agent a clear picture of behavior 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 purpose line is front-loaded, followed by a tight Args list and a brief Returns list. There is no filler; every sentence provides operational value, and the structure is easy to scan.

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?

With full schema documentation and annotations, the description fills the only missing gap—return values—by enumerating the candidate fields returned. It also supplies pagination defaults, output formats, and the source of jobId, making the tool callable without external lookups.

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 types, defaults, ranges, and the enum, making the baseline 3. The description adds one valuable semantic detail: jobId should come from keka_list_jobs, which helps an agent acquire a valid value rather than guessing.

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 states a specific verb ('Retrieve') and resource ('candidates for a specific job opening in Keka Hire'), which clearly differentiates it from sibling list tools that target leave types, pay bands, employees, etc. The title and description align, and the scope is immediately understandable.

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 frames the tool as job-scoped and explicitly points to keka_list_jobs as the way to obtain a valid jobId, which is useful selection and prerequisite guidance. It does not explicitly list exclusions or alternative tools, but the context is clear enough for correct selection among the sibling list 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the return shape (IDs, names, parent department, department lead) and by making pagination visible through the pageNumber/pageSize parameters, which annotations do not convey.

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 compact and well-structured: a one-line purpose, a brief Args list, and a Returns line. It is front-loaded with the core action and every sentence serves a clear function without fluff or repetition beyond the schema.

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 read-only list tool with three optional, fully described parameters, the description is complete. There is no output schema, so the Returns line usefully describes the result shape. Combined with the annotations, an agent has all necessary information to call the 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?

Schema description coverage is 100%, so the input schema fully documents pageNumber, pageSize, and response_format including defaults, bounds, and enum choices. The description's Args section mostly repeats this information without adding deeper meaning, so the baseline score of 3 is appropriate.

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 opens with the specific verb 'Retrieve' and the resource 'all departments defined in Keka HRM', which clearly states what the tool does. It is easily distinguishable from sibling tools like keka_list_employees or keka_list_leave_types because it explicitly names the department entity.

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 gives a clear context: use this tool when you need the list of departments defined in Keka HRM. It does not explicitly name alternatives or exclusions, but no sibling tool overlaps with department listing, so the context is sufficient for an agent to route correctly.

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 cover read-only/idempotent/non-destructive safety. The description goes beyond them by disclosing pagination behavior (page size max 200, start at 1), response_format choice, and the fields returned in the list.

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 longer than average but well structured: one-sentence summary, concise Args block, Returns line, and three examples. It is not bloated, though it does repeat some schema information.

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 an 8-parameter list tool with no output schema, this is complete: it covers all parameters, defaults, enums, return fields, pagination, and common use cases. An agent can select and invoke it correctly without opening the schema, which is unusually thorough.

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 baseline is 3. The description adds value by grouping parameters, restating defaults in context, enumerating the employmentStatus options, and giving three concrete usage examples that map intents to parameter values.

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 first line uses a specific verb ('Retrieve') with a clear resource ('paginated list of employees from Keka HRM') and the filter list makes its scope obvious. This clearly differentiates it from sibling list tools (leave types, pay groups, departments) and from keka_get_employee.

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 gives clear context by specifying this is for paginated employee listing and provides three concrete examples mapping scenarios to parameter values. It does not explicitly contrast with keka_get_employee or state when-not-to-use, but the intended usage is clear enough to select among siblings.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds scope and return shape but does not disclose additional behavioral details like pagination iteration, rate limits, or auth requirements. This is acceptable given the strong annotation coverage.

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 main purpose is front-loaded and the description is compact. However, the Args section duplicates the parameter details already present in the schema, so it is not perfectly efficient, though it remains well-structured.

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 list tool with three optional parameters, rich annotations, and no output schema, the description is complete. It covers purpose, scope, pagination semantics, and return fields (IDs, names, types), which is especially valuable given the absence of 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 each parameter already having a clear description, default, and constraints. The description repeats this information without adding any new meaning, so the baseline of 3 applies.

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 'Retrieve' and clearly identifies the resource as 'groups' with the clarification '(teams/divisions)'. This distinguishes it from sibling list tools for departments, job titles, pay groups, and other HR entities.

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 makes the use case clear: retrieving all groups. However, it does not explicitly state when to choose this tool over sibling list tools, nor does it mention any exclusions or alternatives. Usage is implied rather than directly guided.

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, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond that: it states the data comes from Keka Hire's Recruitment module, that the result set is unfiltered ('all job openings'), and it enumerates the exact returned fields and allowed output formats. This is meaningful behavioral context for a read-only list tool.

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 a clear first sentence followed by a compact Args block, a Returns line, and a routing hint. It is slightly redundant with the schema, but every section earns its place and the most important scoping sentence is front-loaded.

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?

Although there is no output schema, the description explicitly lists the returned fields (ID, title, department, location, status, number of openings, posted date, closing date, hiring manager), all parameter defaults, the output format choices, and a pointer to the relevant sibling tool. For a simple read-only list operation, nothing essential is missing.

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 schema description coverage is 100%, so the schema already documents pageSize, response_format, and default values. The description's Args section mostly restates the same information (defaults, max 200, markdown/json), with no additional semantic explanation. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 opens with a specific verb and resource: 'Retrieve all job openings from Keka Hire (Recruitment module).' This clearly identifies what the tool does and distinguishes it from sibling tools like keka_list_leave_types or keka_list_departments. The scope 'all job openings' is explicit and matches the title.

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 gives direct usage guidance: use this tool to retrieve all job openings, and closes with 'Use keka_list_candidates to see candidates for a specific job.' This names an alternative and the condition for choosing it, making the decision between siblings explicit.

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, openWorldHint=true, and idempotentHint=true, so the safety profile is established. The description adds useful behavioral context by stating the return value (list of job titles with IDs and names) and documenting pagination behavior through pageNumber and pageSize. No contradiction with 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 concise and well-organized with a clear opening sentence followed by Args and Returns sections. Every part is useful, though the Args section duplicates schema information and could be shortened without losing meaning.

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 list tool with three optional parameters and rich annotations, the description provides enough to call the tool correctly: it explains pagination, output format, and expected return content. The main missing context is how this relates to the sibling 'keka_list_jobs' tool, but overall it is complete.

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 three parameters. The description's Args section largely repeats the schema information (page number, page size, response format) without adding meaning beyond what is already structured. Baseline of 3 is appropriate.

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 operation ('Retrieve all job titles configured in Keka HRM') with a specific verb and resource. However, it does not differentiate from the sibling tool 'keka_list_jobs', which could be confused with listing job titles, so it misses some sibling differentiation.

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?

There is no explicit guidance on when to use this tool versus alternatives such as keka_list_jobs or other list_* siblings. The description implies 'use this to get job titles' but provides no exclusions or comparison to related 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return-field context and filter behavior, but it does not disclose operational details like API latency, rate limits, or pagination behavior beyond the schema's defaults. This is acceptable given the strong annotation coverage, but not exceptional.

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 an opening summary, Args list, Returns line, and Examples section. The Args list duplicates schema information, which is slightly redundant, but it is not overly long and the examples earn their place by clarifying real usage.

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 filtered list tool with no output schema, the description is complete: it names the returned fields, explains the main filters, gives defaults for pagination and response format, and provides concrete examples. Combined with the rich input schema and annotations, the agent has what it needs to call the 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?

Schema description coverage is 100%, so the baseline is 3. The description's Args section largely restates the schema's parameter descriptions (e.g., comma-separated employee IDs, ISO 8601 dates, pageSize max 200) without adding deeper semantics. It does offer usage examples that clarify intent, but not enough to push above baseline.

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 opens with a specific verb and resource: 'Retrieve leave requests from Keka' with optional filters. It clearly identifies the resource as Keka leave requests, which distinguishes it from sibling tools like keka_list_leave_types and keka_get_leave_balances.

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 use-case examples ('View pending leaves for a team', 'See who is on leave this month') that tell the agent how to apply filters. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for correct 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the description does not need to restate that. It adds useful behavioral context by describing the return fields (ID, name, code, paid status) and noting pagination parameters, which goes beyond the annotations without contradicting them.

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 a clear purpose statement, an Args section, and a Returns section. It is reasonably concise and front-loaded, though the Args block mostly duplicates schema information and could be trimmed without losing unique 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 simple read-only list tool with no output schema, the description is complete: it states what is returned, lists the relevant parameters, and explains how the result should be used (IDs for creating leave requests). Nothing essential for calling the tool correctly is missing.

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 three parameters fully. The description largely restates the same defaults and enum options without adding new meaning, such as how pagination should be consumed or when one response_format is preferable.

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 opens with a specific verb and resource: 'Retrieve all leave types configured in Keka', and gives concrete examples (Annual Leave, Sick Leave, Casual Leave). This clearly distinguishes it from sibling list tools like keka_list_leave_requests or keka_list_departments.

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 gives clear context that this tool is for retrieving leave types and explicitly connects its output to a downstream action: 'Use the returned IDs when creating leave requests with keka_create_leave_request.' It does not mention when to avoid this tool or contrast it with alternative sibling list tools, so it stops short of a full 5.

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, idempotentHint, and non-destructive behavior, so the description need not repeat safety traits. It adds value by describing the return payload (ID, name, min/max salary, currency) and explaining the domain concept of pay bands, which goes beyond the structured metadata.

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 purpose is front-loaded, the domain explanation is a single useful sentence, and the Args/Returns sections are clearly organized. The parameter list duplicates schema content, but this is acceptable as a quick-reference and does not bloat the description.

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 read-only list tool with three optional parameters and no output schema, the description adequately covers inputs, defaults, and the shape of returned data. It could be more complete by mentioning pagination semantics or contrasting with related salary tools, but nothing essential for invocation is missing.

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?

Input schema coverage is 100%, so the schema already documents all three parameters with types, defaults, and ranges. The description repeats the parameter list but adds no new semantic insight beyond what the schema provides, such as format intent or pagination behavior.

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 opens with a specific verb and resource: 'Retrieve all salary pay bands configured in Keka.' It further clarifies that pay bands are 'compensation ranges for job levels or grades,' which distinguishes this from sibling tools like keka_list_salaries or keka_list_pay_groups.

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?

No guidance is given about when to prefer this tool over siblings such as keka_list_salaries or keka_list_pay_groups. The description implies a general listing use case but provides no exclusions or alternative routing, leaving the agent to infer appropriateness.

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 cover read-only, idempotent, and non-destructive behavior. The description adds return-shape details and the relationship to salary listings, but does not disclose deeper behavioral traits such as pagination limits or data freshness beyond what the schema already provides.

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 and front-loaded, with a clear purpose, Args section, Returns line, and downstream usage note. The Args block repeats schema information, causing minor redundancy, but the overall size is reasonable and no filler is present.

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 list tool with no output schema, the description is sufficiently complete: it explains what is returned, lists the relevant parameters, and connects the IDs to keka_list_salaries. Annotations cover the safety profile, and no critical missing context is apparent.

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%, so the baseline is 3. The description restates the parameter meanings but adds no new semantic details beyond the schema; the 'pay groups define payroll cycles' context helps slightly but does not deepen parameter understanding.

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 clearly states the action ('Retrieve') and resource ('all payroll groups configured in Keka'). It distinguishes the tool from siblings by domain concept ('pay groups define payroll cycles'), though it doesn't explicitly name a sibling alternative.

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 gives clear context: pay groups are used to filter salary listings, and it explicitly points to keka_list_salaries for downstream use. It lacks explicit when-not-to-use guidance against siblings like keka_list_pay_bands, so it stops short of a full 5.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the returned field set (ID, name, email, phone, status, creation date) and the downstream usage with keka_list_psa_projects, which is useful 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 compact and front-loads the core purpose, followed by parameters, return fields, and a next-step hint. The Args block partly duplicates the schema, but it serves as a quick reference and does not bloat the description.

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 list tool with three optional parameters, the description is complete: purpose, parameters, return fields, and downstream usage are all covered. The annotations handle safety, and the schema handles parameter details.

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 fully documents pageNumber, pageSize, and response_format. The description repeats defaults and types but does not add semantic meaning beyond 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 states a specific verb and resource: 'Retrieve all clients from Keka's Professional Services Automation (PSA) module.' It clearly distinguishes this from general employee list tools by naming the PSA module and explicitly cross-referencing keka_list_psa_projects.

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 gives clear context: use this to get PSA clients, then use returned IDs with keka_list_psa_projects. It does not explicitly state when not to use this tool or list alternative client-related tools, but the intended workflow is clear.

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, idempotentHint, and destructiveHint false, so the bar for additional disclosure is lower. The description adds useful behavioral context by describing the return payload fields (ID, name, client, status, dates, budget, currency, project manager) and output format options, going beyond the structured 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 docstring-style Args/Returns layout is scannable and the opening sentence clearly states the tool's purpose. It repeats some parameter information already in the schema, but the structure remains compact and easy to parse.

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 paginated list tool, the description combined with the full schema and annotations covers everything needed to call it correctly. The description fills the gap left by the missing output schema by listing the returned fields and noting the default response format.

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 baseline is 3. The description restates pageNumber, pageSize, and response_format with defaults matching the schema, but does not add substantial extra meaning such as ordering behavior, date formats, or currency details.

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 'Retrieve' and clearly identifies the resource as 'projects from Keka's Professional Services Automation (PSA) module'. This distinguishes the tool from siblings like keka_list_psa_clients by naming 'projects' as the entity type, leaving no ambiguity about what is returned.

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 states what the tool does but provides no guidance on when to use it versus alternatives such as keka_list_psa_clients or other list tools. There is no mention of context, prerequisites, or situations where this tool should or should not be chosen.

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 and idempotentHint=true, so the description is not burdened with proving safety. It adds valuable behavioral context beyond annotations: the tool returns sensitive compensation data, the API key must have payroll read access, and the response includes CTC, pay group, currency, and effective date. No contradiction with 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: purpose first, then a high-visibility warning, then a compact Args list, then return fields. It is not overly verbose for a 6-parameter tool, and each section is easy to parse. Some duplication with the schema exists, but it remains a concise executable summary.

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?

With no output schema, the description adequately covers return content by naming CTC, pay group, currency, and effective date. It also covers permission requirements, filtering options, pagination, and response format. It could be slightly more explicit about behavior when no filters are provided, but the optional parameters and defaults make the intended behavior clear.

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 already documents all 6 parameters with descriptions, defaults, enums, and limits, giving 100% schema description coverage. The description's Args section largely restates the schema rather than adding new meaning. The only added context is the sensitivity warning, which is not parameter-specific. Baseline 3 is appropriate.

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 opens with a specific verb-resource pairing: 'Retrieve salary information for employees from Keka payroll.' It identifies the exact resource (salary information) and distinguishes it from sibling list tools covering leave types, pay groups, employees, departments, etc. The return fields (CTC, pay group, currency, effective date) further clarify the tool's unique 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?

It provides clear context for when to use the tool: whenever salary/compensation data is needed, and it warns that payroll read access is required. It also references keka_list_pay_groups for obtaining pay group IDs, which is an explicit pointer to a sibling. It does not state explicit when-not-to-use cases, but the resource distinction is clear enough.

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