Jisr MCP by usefulapi

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

Annotations already disclose that this is a non-readonly, open-world, non-idempotent, non-destructive write. The description adds useful behavior beyond the annotations: the batch limit, asynchronous processing, and the requirement to use device-generated punch ids rather than inventing them. It does not cover permissions, partial failures, or duplicate handling, which keeps it below 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?

The description is three tight sentences, front-loaded with 'WRITE' and the core action. Every sentence carries useful information, and the endpoint reference is short without distracting from the operational guidance.

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 asynchronous write tool with no output schema, the description gives the essential operational context: batch size, id constraints, and how to check the result. It still leaves the immediate response shape and error behavior unspecified, so it is strong but not fully 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 reported as 0%, so the description must compensate for parameter meaning. It adds important semantics for the batch limit and the id field, but it does not explain emp_code, terminal_sn, or punch_time formatting beyond what the nested schema already states.

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 names a specific verb and resource: send a batch of raw clock-in/out punches into Jisr attendance. It distinguishes the write operation from the sibling read tool jisr_list_attendance_punches by framing that tool as the way to check results.

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 gives clear usage context: import device-generated punches, at most 100, and verify asynchronously with jisr_list_attendance_punches. It stops short of explicitly stating when not to use this tool or naming any alternative import route.

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=false, destructiveHint=false and idempotentHint=false, so the description's job is to add context — and it does: an invitation email is dispatched to the employee, and the creation cannot be undone through this server. It does not address duplicate-email/code behavior or required permissions, which matter for a 14-required-param mutation.

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 compact sentences, front-loaded with the WRITE marker and the core action, then prerequisites and constraints. The endpoint string is the only arguably expendable element and it costs nothing.

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 17-parameter, 14-required mutation with no output schema, the description covers the essentials: side effect (email invite), irreversibility, prerequisite lookups, and the two-part-name constraint. It omits what the call returns (employee id?) and how duplicates are handled, which leaves a small but real gap.

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 88%, so the schema already documents each field including the 'jisr_list_lookup' provenance for the four id parameters. The description restates that lookup dependency rather than adding new meaning, and says nothing about the optional contract_end_date / outsourcing_company_id interactions. 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?

Opens with an explicit verb and resource ('WRITE: register a new employee in Jisr'), and the parenthetical clarifies the mechanism (invitation by email). It is unmistakably distinct from the read/list siblings and from jisr_create_attendance_punches.

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?

Gives a concrete prerequisite workflow: 'Get department_id, employment_type_id, location_id and nationality_id from jisr_list_lookup first.' It also rules out an expectation ('no delete tool'), which shapes how cautiously the agent should act. It stops short of stating when NOT to use this tool (e.g., employee already exists), so not 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=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the annual-leave-only constraint, the 100-employee ceiling, and the underlying endpoint for provenance. It stops short of describing pagination semantics or what a balance summary contains, but that is a minor omission given the 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?

Three tight sentences: resource scope first, constraint second, endpoint last. Nothing is redundant or buried, and the most important limitation (annual leave only) 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?

For a zero-required-param, read-only list tool with full schema coverage and no output schema, the definition supplies everything needed to call it correctly. The one gap is that 'balance summaries' is not unpacked, so an agent cannot anticipate the returned fields.

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 schema already documents page, limit, and employee_codes thoroughly. The description's 'at most 100' and 'omit for everyone' restate what maxItems and the property descriptions already encode. Baseline 3 is correct when the schema does all the work.

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?

States a specific resource (annual leave balances), unit of return (per employee), and scope (all employees or a subset of employee codes). The endpoint path and the explicit note that only the annual leave type is supported make the domain unambiguous relative to other leave-related 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?

Gives clear conditions: omit employee_codes to get everyone, supply codes for a subset, at most 100. The line 'Only the annual leave type is supported by Jisr' scopes expectations. It never names an alternative call (e.g. accrual transactions) for other leave types, but the surrounding context is clear enough.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds value by listing the profile fields returned, which compensates for the absent output schema, but it says nothing about auth requirements, error behavior for a bad/missing id, or whether the record includes archived employees.

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?

One sentence, front-loaded with the core action and scope before the field enumeration. The trailing raw endpoint path 'GET /openapi/v1/employees/basic_info?id=' is implementation noise that doesn't help an agent select or invoke the tool, and the field list is long, but nothing is truly wasted.

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 single-required-param read tool, this is sufficient: annotations carry the safety profile, the schema fully documents the id, and the field enumeration stands in for the missing output schema. An agent has everything needed to call it correctly and know what comes back.

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% and the single param already has a description and UUID pattern, so the baseline is 3. The description adds provenance ('from jisr_list_employees'), telling the agent where a valid id comes from rather than guessing — a genuine increment over 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 (fetch a profile) and resource (one employee, by id) and enumerates the returned fields, so the agent knows exactly what this retrieves. It implicitly differentiates from jisr_list_employees by naming it as the id source, though it never contrasts with jisr_get_employee_financial_info or jisr_get_employee_monthly_payables, which cover adjacent employee 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?

The parenthetical '(UUID from jisr_list_employees)' implies the call sequence: list first, then fetch a single record. That's useful routing, but there's no explicit when-to-use/when-not guidance or distinction against the other get_employee_* siblings that also accept an employee id.

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, destructiveHint=false, openWorldHint=true, so safety is covered; the description adds genuinely non-derivable context: the data is sensitive payroll information and the API key must carry the 'Get Employee Financial Info' permission. It also pins the concrete endpoint, which helps with auth/scope expectations. It stops short of noting rate limits or what happens on missing permission.

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 short clauses with the payload described first, then the sensitivity/permission caveat, then the endpoint. Front-loaded and waste-free, though the trailing 'GET /openapi/v1/employees/financial_info?id=.' with an empty query value reads slightly awkwardly.

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 one required parameter, no output schema, and annotations covering the safety profile, the description covers the essentials: what is returned (salary components, IBAN), the access prerequisite, and the transport detail. A brief note on error behavior when the permission is missing would make it fully 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% and the single id parameter is already documented as a UUID with a pattern, so the schema carries the burden. The description only echoes 'by id' and appends '?id=' to the path, adding no format or constraint detail beyond the schema. Baseline 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?

States a specific verb and resource: fetch one employee's financial details by id, and enumerates the payload ('salary components and bank account (IBAN)'). The 'One employee's ... by id' framing separates it from jisr_list_employees and the broader jisr_get_employee without needing to name them.

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?

Usage is implied by the content ('financial details', 'salary components', 'bank account') rather than stated: an agent can infer it should call this instead of jisr_get_employee or jisr_get_employee_monthly_payables when payroll/bank data is needed. No explicit when-to-use, when-not, or named alternative is given.

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 destructiveHint=false. The description adds meaningful context beyond annotations: whitelist gating, sensitivity of payroll data, and the payroll components returned. It does not cover auth mechanics or rate limits, but that is a minor gap for this read-only endpoint.

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 four tight sentences and front-loads the key return content. The whitelist and sensitivity notes are operationally useful, and the endpoint sentence, while not essential, is not 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?

For a 2-parameter read-only GET with no output schema, the description gives a useful summary of returned payroll components and the important whitelist restriction. It omits explicit sibling routing and a detailed response shape, but the schema and annotations cover the core invocation and safety 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%, with employee_id documented as a UUID and pay_period_start documented as yyyy-mm-01. The description only indirectly reinforces 'one employee' and 'for a month'; it adds no parameter syntax or constraints beyond what the schema already provides.

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 identifies the resource and scope: one employee's payables for a month, including net salary, earnings, additions, and deductions. It is more specific than a tautology, but it does not explicitly distinguish this tool from siblings like jisr_get_employee_financial_info or jisr_list_payroll_transactions.

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 gives a hard availability condition — only whitelisted organizations — and flags the data as sensitive payroll data. However, it does not explain when to choose this over sibling payroll/financial tools or when not to use it.

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 establish this as a safe read (readOnlyHint=true, destructiveHint=false), and the description adds real value beyond them: it flags the data as 'Sensitive payroll data' and states the confirmed-pay-period precondition. It stops short of describing pagination behavior or volume limits, but the safety profile and sensitivity caveat are covered.

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 short sentences with the resource and scope front-loaded and zero filler; the trailing GET path is the only arguably low-value token. Slightly telegraphic phrasing, but nothing is wasted.

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 usefully sketches the return shape ('amount, vacation days'), and it covers the key prerequisite (confirmed pay period) and sensitivity for a payroll-adjacent read. An agent could call this correctly without further reading, though pagination expectations are left entirely to the 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%, so accrual_type, pay_period, paygroup_id, employee_ids, page and rpp are all documented in the schema itself. The description only restates the accrual_type values (already an enum) and the confirmed-period constraint, adding no new meaning for filtering or pagination params. Baseline 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?

States a specific verb+resource ('Accruals per employee for a confirmed pay period') and enumerates the accrual types it covers, plus the fields returned. It is clearly distinct from jisr_list_payroll_transactions by name, but the description never explicitly contrasts the two.

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 'for a confirmed pay period' implicitly gates usage on a pay period being confirmed, which is useful context, but there is no explicit when-to-use/when-not guidance or pointer to alternatives like jisr_list_payroll_transactions or jisr_get_annual_leave_balances.

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, and destructiveHint, so safety is covered. The description adds value beyond that by disclosing the default window behavior (last hour) and the exact record fields returned (id, punch_time, employee_code, terminal_sn, clocking_id), which matters because there is no output schema. Pagination behavior is left entirely to the schema rather than described.

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 tightly written sentences, front-loaded with the core purpose before the scope and returned fields. The trailing endpoint reference is the only mildly redundant element, and it is short enough not to distract.

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 five parameters, one of them required, and no output schema, the description does the important extra work of enumerating the punch fields an agent will receive and stating the default time window. What remains uncovered — pagination semantics and whether results are ordered — is minor and handled by the 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%, so the schema already explains from/to/page/limit/status including defaults and bounds, which sets the baseline at 3. The description reinforces that status selects between successfully processed and failed punches, but adds no syntax, format, or interaction detail beyond what the schema already provides.

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 gives a specific verb and resource — "List raw clock-in/out punches that were received from punch devices" — with the scope (a time window) and the success/failure filter stated up front. It implicitly separates itself from a summary-style sibling by emphasizing "raw" punches, but never names an alternative, so the differentiation is inferential rather than explicit.

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?

Usage is implied by the domain framing: fetch raw punch records within a window when you need device-level data, with the last-hour default stated. There is no explicit when-to-use guidance relative to jisr_create_attendance_punches or jisr_list_attendance_summary, and no stated prerequisites or exclusions, leaving the agent to infer the boundary.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the current-month default, but that is partially duplicated by the schema's 'from' default, and it says nothing about permission requirements, result caps, or whether inactive employees are included by default.

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 returned metrics are front-loaded, then filters, then the endpoint, with essentially no filler. The trailing raw endpoint path is marginally useful for debugging but is the only sentence that doesn't guide invocation.

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 carries the burden of describing return values, and it does so by enumerating the summary fields per employee. Combined with a fully documented schema and read-only annotations, this is close to complete; only edge-case behavior (e.g., interaction of filters, employees with no records) is unaddressed.

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 every parameter is already documented with formats, bounds and defaults. The description restates the date range and filter semantics but adds no meaning beyond the schema — for example, it doesn't clarify behavior when both employee_id and status are supplied.

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 names a specific verb (list) and resource (attendance summary), and enumerates exactly what the summary contains (working hours, lateness, overtime, absences). It implicitly distinguishes itself from jisr_list_attendance_punches by being a per-employee aggregate rather than punch records, but never names that sibling, so the differentiation is inferential rather than explicit.

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 supplies the default period (current month) and the available filters (single employee vs. active/inactive), which is useful calling context. However, it gives no guidance on when to choose this aggregate over jisr_list_attendance_punches or how the two relate, so the agent must infer the choice from the word 'summary'.

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 establish that this is a read-only, non-destructive, open-world listing operation, so the description does not need to restate safety. It adds useful context about the audit data shape and the underlying GET endpoint, but it does not disclose pagination behavior, default time-range handling, ordering, or access requirements. With annotations covering the safety profile, this is a moderate contribution.

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 purpose before listing filters and the endpoint. Every sentence contributes, though the raw endpoint path is somewhat technical and less useful for tool selection. It is efficient and 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?

Given a read-only listing tool with seven optional parameters, full schema coverage, and no output schema, the description gives a sufficient picture of what is returned and how to filter it. It does not describe pagination expectations or default time-range behavior, but those are largely covered by the schema. The definition is complete enough for an agent to invoke it 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 all seven parameters are already documented in the input schema, including date-time formats, page/per_page limits, and example event values. The description reinforces the filter dimensions but does not add syntax or meaning beyond what the schema provides. A baseline score of 3 is appropriate when the schema carries the parameter 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 states a specific resource, the organization's audit trail, and explains the data dimensions: who did what and when, with module/feature/action/actor/success. It is clearly distinguishable from siblings because no other listed tool deals with audit events. However, it does not explicitly name or contrast with any alternative tool, so it falls short of the highest clarity tier.

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 usage by stating the filterable dimensions (module, event name, event type, time range), which suggests when the tool is appropriate. It does not say when not to use it, mention any prerequisites, or point to alternatives. This is adequate but leaves the agent to infer the intended 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavior beyond that: a default filter that silently hides inactive employees, and permission-gated expansion of the response with salary, IBAN and accounting fields flagged as sensitive HR data — an important disclosure an agent would otherwise miss.

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, front-loaded with the action and the default scope, then the payload, then the filter families and the permission caveat, ending with the endpoint. The field enumeration is long but justified because there is no output schema to document the return shape.

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 ten optional parameters, no output schema and permission-dependent fields, the description covers exactly the gaps an agent would hit: default status scoping, which date dimensions can be filtered, what comes back, and that extra sensitive fields appear only under specific API-key permissions. Pagination is fully handled by the 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 100% so the baseline is 3, but the description adds meaning the schema does not: that filtering defaults to active employees and that the library of date parameters is grouped into creation, joining, termination and deletion ranges. It does not add syntax or interaction rules (e.g., whether ranges combine with AND, or page/rpp interplay), so it sits just 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?

A specific verb (list) plus resource (organization's employees) with an explicitly enumerated return payload (code, names, job title, department, business unit, employment type, line manager, joining date, status). The default scope (active only) is stated up front, which cleanly separates it from the singular jisr_get_employee and from the financial-info sibling.

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 conditions for filtering: 'active by default', plus date-range filtering on creation, joining, termination and deletion. It also implicitly routes financial-field consumers by noting the permission dependency, but it never explicitly names jisr_get_employee or jisr_get_employee_financial_info as the alternative for single-record or finance-only lookups.

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 destructiveHint=false, so the safety profile is covered. The description adds real value by listing the returned fields and giving the API endpoint path, which the annotations do not provide. It doesn't discuss pagination behavior or ordering, keeping it short of 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?

Two compact sentences with zero filler: the purpose and return fields come first, the follow-up action second, the endpoint last. Every clause carries 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?

With no output schema, listing the returned fields is the key compensating detail, and it's present. Annotations cover safety and pagination is covered by the schema, so an agent has what it needs; only ordering/volume of results is unaddressed.

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% — rpp and page are fully documented in the schema, including the next_page chaining hint. The description adds nothing about parameters, so baseline 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?

States a specific verb and resource ('List the payroll (GL) transaction types') and enumerates the returned fields (id, category, English/Arabic name, status). The category examples ('allowances, loan types...') make the resource concrete and distinguish it from list siblings like jisr_list_accrual_transactions.

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?

Explicitly tells the agent what to do next: 'Use the ids to filter jisr_list_payroll_transactions', naming the relevant sibling and the downstream use case. No when-not-to-use guidance, but the lookup-tool role is unambiguous.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: it names the HTTP verb/path and describes what comes back (ids plus bilingual names), which matters since there is no output schema. It does not mention rate limits or caching behavior.

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 tightly written sentences plus the endpoint, front-loaded with the action and the enumerated options. No filler or redundancy.

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 no output schema, the description covers what to fetch, what it returns, and why an agent would call it. Pagination is handled by the schema. Minor gap: the response envelope shape is not described, though the cardinality and fields are.

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 and an enum on `table`, the schema already documents all three parameters including pagination guidance ('Pass the previous reply's next_page'). The description adds no additional parameter-level detail, so the baseline of 3 is correct.

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 ('List') plus resource ('lookup tables'), with the valid tables enumerated and the returned fields (ids, English/Arabic names) stated. It is clearly distinguishable from siblings such as jisr_list_employees or jisr_list_paygroups, which return different resources.

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?

'Use the ids when creating an employee' gives a concrete downstream use case, tying it to jisr_create_employee. There are no explicit exclusions or comparisons to alternatives, but the six enumerated tables make the scope unambiguous.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by disclosing the returned fields and the underlying GET endpoint, but says nothing about result volume, pagination iteration, or whether the list is ever empty — minor gaps given 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?

Two sentences, front-loaded with the resource and return shape, then the downstream reason. The trailing raw endpoint path is mildly redundant with the tool's purpose but is short and harmless.

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, and the description compensates by naming the returned fields (id and name). With only two optional paging parameters that the schema documents fully, an agent has everything needed to call it correctly; only response-size or ordering behavior is left unstated.

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 both parameters (rpp, page) are fully documented in the schema, including the next_page paging pattern. The description adds no parameter detail, so the baseline 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?

States a specific verb and resource (list pay groups) and names the return fields (id and name), which no sibling list tool does. It also situates the tool in the workflow by saying the id is required for payroll and accrual queries, so an agent can distinguish it from jisr_list_payroll_transactions or jisr_list_accrual_transactions.

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?

Gives clear positive guidance: call this when you need a pay group id to feed payroll or accrual queries. It stops short of naming the alternative tools or stating when not to call it, but the intended entry-point role is unambiguous.

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 establish readOnly/openWorld/non-destructive, so the description's main value-add is the 'Sensitive payroll data' warning and the per-type preconditions that determine whether a call is valid at all. It does not mention pagination behavior or the fact that results may be paged via next_page, though the schema params hint at it.

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?

Dense and front-loaded: the resource, the conditional parameter rules, the optional filters, and the data sensitivity warning are all delivered in a few short clauses with zero repetition of schema text. Nothing could be removed without losing routing or validity 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 a 9-param, single-required-param list tool with no output schema, the description covers the difficult part (type-dependent required parameters) and names related lookup tools. Missing only a note on pagination/next_page continuation and possible edge cases where types conflict.

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 parameter-level text is already documented; the description nonetheless adds genuine meaning by binding parameters to the type enum (which pair is required under which type), which the schema cannot express. Value is added beyond baseline without being complete on cross-parameter interactions.

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?

States a specific verb and resource ("Payroll transactions per employee for one settlement type") and immediately scopes it by the settlement type enum values. It is clearly distinguishable from siblings like jisr_list_gl_transaction_types or jisr_get_employee_monthly_payables, which it does not overlap with.

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?

Gives explicit conditional guidance: 'payrun' needs pay_period and paygroup_id, while the other three types need a from/to range, and it points to jisr_list_gl_transaction_types for transaction type ids. It stops short of saying when to prefer a sibling tool (e.g., financial info vs payroll transactions) or what to do when both date and period could apply.

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?

Goes beyond the annotations by disclosing a redaction policy: authentication data, custom header values, and the endpoint's path and query are hidden because they can hold secrets. That is genuinely useful behavioral context an agent cannot infer from readOnlyHint/destructiveHint. It stops short of describing ordering, result limits, or empty-result behavior.

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 short sentences, front-loaded with what is returned, followed by the redaction caveat and the read-only guarantee. Every sentence carries distinct information and nothing is repeated from the title.

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 compensates by naming the returned fields, documenting what is masked, asserting read-only semantics, and citing the underlying endpoint. An agent has everything needed to call this and interpret the result 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly avoids inventing filters or paging arguments that the schema does not have.

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?

States a specific verb and resource ('List the webhooks registered for the organization') and enumerates the fields returned (name, endpoint host, method, status). No sibling tool deals with webhooks, so the scope is unambiguous at a glance.

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?

Explicitly scopes the tool as read-only and states 'this server does not create or change webhooks', which tells the agent there is no mutation alternative to look for. It doesn't compare against other list tools, but for a zero-param listing tool with no near-sibling this is clear guidance.

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