kiwiHR MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description's job is lighter. It adds real value by describing the observable consequence of activation (reappears in active lists, regains access) and the underlying GraphQL mutation, though it says nothing about permissions required or behavior when the user is already active.

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 the operation class front-loaded and zero filler. Every clause carries information an agent needs.

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-parameter mutation with annotations covering the safety and idempotency profile and no output schema, the description supplies the effect and mutation name needed to call it confidently. Only auth/permission expectations and already-active handling are 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?

Only one parameter and schema coverage is 100%, so the schema fully documents user_id as the employee id. The description adds no format, source, or lookup guidance beyond that, which is the expected baseline when the schema does 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 verb (re-activate) and resource (deactivated employee), plus the concrete effect (appears in active lists, can use kiwiHR again). The 'WRITE:' prefix and GraphQL mutation name make it immediately distinguishable from read siblings like kiwihr_get_user and from kiwihr_deactivate_user.

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 're-activate a deactivated employee' establishes the precondition clearly, implying this is the inverse of kiwihr_deactivate_user. It stops short of explicitly naming that sibling or stating what to do if the user is already active, so it falls just below the explicit when/when-not bar.

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?

Adds context beyond annotations: the new journey is created but not published, and the agent must inspect the status in the reply. The 'not idempotent' statement echoes idempotentHint=false, and the GraphQL mutation name is minor, but the publish/status behavior is genuinely useful and not encoded anywhere else.

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?

Front-loads the WRITE marker, then purpose, then idempotency, then the publish caveat in four tight sentences with no filler. Every clause carries distinct 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 non-destructive write with no output schema, the description covers input sourcing, idempotency, and post-call verification. Nothing an agent needs to invoke this 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 every parameter is already documented. The description only reinforces that journey_type_id is required and journey_template_id optional; it adds nothing on custom_date, pre_onboarding_access or personal_email. 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 ('create an onboarding/offboarding journey for an employee') plus the source of inputs (journey type, optional template). This clearly separates it from read-side siblings like kiwihr_get_journey and kiwihr_list_journeys.

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 points the agent to kiwihr_list_journey_types and kiwihr_list_journey_templates to obtain the required ids before calling, which is real routing guidance. No explicit when-not-to-use or alternative-create guidance, so it stops short of a 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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true; the description largely restates the write and non-idempotent traits. It does add genuinely new context ('Creates a new project each call', default status ACTIVE, GraphQL mutation createProject), but says nothing about required permissions, duplicate-name behavior, or the returned object.

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?

Front-loaded 'WRITE:' prefix immediately signals the operation class, and every clause (fields, default, non-idempotency, underlying mutation) carries distinct information with no 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 create tool with full schema coverage and complete annotations, the description covers what an agent needs to invoke it. The main remaining gap is that with no output schema, it does not say what a successful call returns (e.g. the new project's id) so the agent can chain to kiwihr_get_project.

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 both parameters are already documented, including the ACTIVE enum meaning. The description adds only the default value (ACTIVE) beyond the schema, which keeps it at the baseline rather than above it.

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 plus resource ('create a time-tracking project') with the two supported fields and an explicit default. It is distinguishable from siblings like kiwihr_update_project and kiwihr_get_project by the write-a-new-record verb, though no sibling is named as an 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?

Usage is implied by the 'WRITE: create' framing and the non-idempotent note, so an agent can infer this is for creating rather than updating. However, nothing states when to prefer kiwihr_update_project or how to check whether a project already exists (e.g. via kiwihr_list_projects).

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 readOnly=false, idempotent=false, destructive=false, so the bar is lower; the description reinforces non-idempotency with the concrete consequence that duplicate calls create duplicate entries. It also discloses the return ('updated day') and that project_id comes from kiwihr_list_projects, though it does not cover auth/permission requirements.

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?

Front-loaded with 'WRITE:' and packs scope, type semantics, defaults, idempotency and return into a few dense lines. Slightly compact to the point of being terse, but no sentence is 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 an 8-parameter mutation with no output schema, the description covers the write nature, the enum branches, the optional fields, the non-idempotent consequence, and what the call returns. An agent has what it needs to invoke 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 coverage is 100%, so baseline would be 3. The description goes beyond the schema by explaining the cross-parameter relationship: MANUAL requires start_at/end_at as HH:mm:ss or a part_of_day, while BREAK is a break, and it repeats the user_id omission default in context.

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 ('add a time entry to the timesheet of one employee on one day') plus the WRITE marker and the underlying GraphQL mutation name. It distinguishes itself from kiwihr_update_timesheet_entry and kiwihr_delete_timesheet_entry by noting it 'Creates a new entry each call'.

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: type MANUAL vs BREAK, start_at/end_at vs part_of_day, and that an omitted user_id targets the admin user the key acts as. It never names the update or delete siblings as the alternative path for modifying an existing entry, so it stops short of full when-not coverage.

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 well beyond annotations by disclosing that no invitation e-mail is triggered per call and that payroll/bank fields are out of scope — consequential facts not encoded anywhere else. The non-idempotency restates idempotentHint=false and it says nothing about permissions or validation failures, so it is not fully transparent.

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?

A single dense paragraph, front-loaded with the WRITE marker and the required-field contract. Every clause (idempotency, no invitation, excluded data) carries information an agent would otherwise have to guess.

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?

No output schema exists, yet the description does not say what comes back (presumably the created employee id) or how to retrieve it afterwards. Everything an agent needs to make the call correctly is present, so the gap is limited to return-value handling.

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 60%; the description compensates by mapping required fields (first name, last name, work e-mail) and naming the optional set (start date, manager, teams, position, location, phones). It omits the gender parameter entirely and adds no format or cross-reference 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?

States a precise verb+resource ("add a new employee record") and immediately enumerates required vs optional fields, so the agent knows exactly what the tool produces. It is clearly distinguishable from siblings like kiwihr_update_user, kiwihr_activate_user and kiwihr_create_journey.

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 real selection context: not idempotent, no invitation sent, payroll/bank data cannot be set — so an agent knows this is the HR-record creation step only. It stops short of explicitly routing to an alternative (e.g. "use kiwihr_update_user to modify an existing employee" or "invite separately with ...").

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 flag destructiveHint=true and idempotentHint=true, but the description adds the concrete consequence an agent needs: the employee loses kiwiHR access and disappears from active lists, and the change is reversible via kiwihr_activate_user. It also exposes the underlying GraphQL mutation. It does not state permission requirements or side effects on related records (timesheets, journeys), which is the only remaining gap.

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?

Front-loaded with 'WRITE, ACCESS-CHANGING' so risk level is visible before anything else, then two tight sentences with zero filler. Every clause (effects, reversibility, mutation name) 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 one-parameter mutation with no output schema and full annotation coverage, the description adequately explains impact and reversibility. Missing only edge-case behavior such as what happens when the user_id is already inactive or not found, which an agent might want to know before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single required 'user_id' with min/max length constraints, so the schema carries parameter meaning. The description adds nothing about the identifier (e.g., that it must reference an active user), 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 ('deactivate an active employee') and immediately distinguishes it from the sibling 'kiwihr_activate_user' by naming the reverse operation. The scope qualifier 'active' plus the stated effects (loses access, drops out of active lists) leave no ambiguity about what the call does.

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 clear usage context ('typically after they leave') and names the explicit alternative for undoing it ('Reversible with kiwihr_activate_user'). It does not spell out when NOT to use this (e.g., versus kiwihr_update_user for a status change or versus a hard delete), so it stops short of the 5-level when/when-not pair.

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 destructiveHint=true and readOnlyHint=false, and the description reinforces this with irreversibility language and the GraphQL mutation name. It also discloses the return value ('Returns true when deleted'), which matters because there is no output schema. It does not cover failure modes (e.g., deleting an approved/locked entry) or permission requirements.

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?

Front-loads the risk classification ('WRITE, DESTRUCTIVE'), then the action, the id source, the irreversibility, and the return value in four short clauses. No sentence is 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 one-parameter destructive call with no output schema, it covers action, id provenance, irreversibility, and return value. Missing only edge-case behavior such as what happens if the id is unknown or the entry is already approved, which would help an agent recover from errors.

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% with a single required entry_id, so the schema already defines type and constraints. The description adds meaning beyond the schema by stating how to obtain a valid id, which the schema does not say.

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 ('permanently delete one timesheet entry by id'), scoped to a single entry so it is clearly distinct from list/update siblings. It even names the sibling to use for retrieving the id, so an agent can route without opening a schema.

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 an explicit prerequisite workflow ('get it from kiwihr_get_timesheet') and an explicit hazard ('This cannot be undone'). It does not explicitly contrast with kiwihr_update_timesheet_entry for the case where the user actually wants to amend rather than remove, which is the one remaining inference left to the agent.

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=true, destructiveHint=false, openWorldHint=true), so the description is not carrying that burden. It adds useful substance — units in seconds, per-project tracked time breakdown, and the underlying GraphQL query — but says nothing about pagination, permissions, or empty-range 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?

A single front-loaded sentence that establishes resource, scope, and query source before enumerating returned fields. The field enumeration is dense but earns its place given there is no output 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?

With no output schema, enumerating the returned metrics (expected, tracked, balance, overtime, meal vouchers, per-project time) is the right compensating move, and annotations cover safety. The main omission is routing guidance versus the list-level sibling.

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 all three params required and documented (user_id, date_from/date_to with YYYY-MM-DD patterns), so the schema already does the heavy lifting. The description adds only the concept of a date range and the output units, not parameter syntax or constraints 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?

States a specific verb+resource ('Attendance statement') with explicit scope: ONE employee over a date range, plus the GraphQL query name. The capitalized 'ONE' implicitly contrasts with the plural sibling kiwihr_list_attendance_statements, but the sibling is never named, so differentiation relies on inference.

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 when-to-use or when-not guidance. Despite a closely related sibling (kiwihr_list_attendance_statements) existing, the description never tells the agent which to pick; only the single-employee scope hints at the split.

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 value beyond that by disclosing the shape of the payload (journey plus steps) and, importantly, that include_personal surfaces a private e-mail address, flagging privacy-sensitive data an agent should treat carefully. It does not state any permission or scoping requirements, which keeps it from 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 sentences, front-loaded with the primary return shape, then the optional-field caveat. The trailing "GraphQL query journey" is the only near-waste, and even that gives an implementer a useful handle. Zero bloat overall.

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 present, the description carries the return-value burden and does so by naming the journey, its steps and their fields, plus the conditional personal e-mail. Combined with annotations covering safety, an agent has enough to call it correctly; only error behavior for an unknown id is left implicit.

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 both journey_id and include_personal documented in the schema, so the baseline is 3. The description's restatement of include_personal adds only the slight emphasis that the e-mail is "private" and "stored on the journey" – useful framing, but not meaning the schema omits.

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 statement ("One journey by id") and enumerates the returned step fields (name, description, fixed start and due dates), so an agent can tell it apart from kiwihr_list_journeys without opening the schema. It stops short of naming the sibling it is not, which is the only thing separating a 4 from a 5.

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 required journey_id: call this when you already have an id and need full detail. There is no explicit when-to-use, no when-not-to-use, and no signposting to kiwihr_list_journeys or kiwihr_list_journeys_templates as the way to obtain that 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it never says what happens for an unknown or malformed id, nor how errors surface. 'GraphQL query project' is an implementation detail rather than behavioral context.

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?

Very short and front-loaded, which is good, but it is written as two terse fragments and the second one ('GraphQL query project') restates the operation and the transport without earning its place. Nothing is bloated, but the content per sentence is thin.

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 one-parameter read with no output schema, the description does mention the returned fields (name, status), which compensates a little. It still omits not-found behavior and whether additional fields are available, leaving the agent with only a minimum viable picture of a simple tool.

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 a single parameter at 100% schema description coverage, the schema (type string, 1-64 chars) already carries the semantics. The description only restates 'by id' and adds no format, source, or lookup guidance beyond it, 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 resource and scope: a single time-tracking project fetched by id, with the fields it returns (name, status). The word 'One' implicitly contrasts with the sibling kiwihr_list_projects, so an agent can tell single-fetch from list without opening the schema, though the sibling is never named.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as kiwihr_list_projects (search/unknown id) or kiwihr_update_project. The only hint is 'by id', which merely implies the caller must already have an identifier.

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 behavioral context by describing the aggregation granularity (per employee, per time off rule) and that requested as well as taken absences are included. It does not clarify whether pending/rejected requests are counted, which is material for an 'usage' metric.

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; the core definition leads, followed by the use case and filter cross-reference. The trailing 'GraphQL query timeOffRequestUsageStatements' is implementation detail that earns only marginal space.

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 10 parameters, no output schema and required date/type inputs, the description does the necessary work of sketching the returned structure and pointing at the filter conventions. The remaining gap is the treatment of non-approved requests, which an absence report consumer would want to know.

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 already 90%, so the baseline is 3; the description adds value by noting the optional employee filters behave 'as in kiwihr_list_users' (covering team_id/location_id/is_active semantics) and by tying time_off_type_ids to kiwihr_list_time_off_types. It adds no detail on limit/offset/sorting, but the schema already documents those.

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 ('who took/requested how much time off') and even defines the return shape: per-employee request count and used days per time off rule. It implicitly separates from kiwihr_list_time_off_balances by framing the output as usage in a date range, but it never names the alternative explicitly.

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 usage trigger with an example ('Use it for absence reports ("who was off in March?")'), which clearly tells an agent when to reach for this tool. It stops short of stating when not to use it or pointing to the balances/attendance siblings as alternatives.

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, non-destructive, and open-world, so the description does not need to restate safety. It adds useful behavior beyond annotations: times are in seconds, omitted user_id resolves to the admin user the key acts as, and the result includes all entries with ids required for later updates or deletes.

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-loaded: the core scope appears immediately, followed by the key default behavior and units. Every sentence adds useful information with no 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?

With no output schema, the description usefully explains that the result includes all entries and their ids, and that times are in seconds. It is nearly complete for a small read tool, though it could mention what happens when no timesheet exists or whether the response is empty.

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 both the date format and user_id omission behavior. The description reinforces that user_id omission means the admin user, but adds little parameter detail beyond what the schema 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 states a specific resource and precise scope: the timesheet of ONE employee for ONE day, including all entries and their ids. This clearly differentiates it from list-oriented siblings such as kiwihr_list_timesheets by emphasizing single-employee, single-day retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The scope and the note that entry ids are needed to update or delete an entry give clear implied usage context. It does not explicitly say when to use this versus kiwihr_list_timesheets, but the single-employee/single-day constraint provides strong routing guidance.

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 (readOnly, non-destructive), but the description adds genuinely non-obvious behavior: personal data is excluded by default, gated behind include_personal, and payroll/bank/tax/insurance are never returned regardless. That privacy scoping is real behavioral context an agent cannot get from structured fields, though failure modes for bad ids are unmentioned.

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 scope and the default-vs-personal distinction are front-loaded and every clause about field content earns its place. The trailing "GraphQL query user." is an implementation leak with little decision value and is the only real waste.

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 field-group inventory carries the full burden of describing what comes back, and it does so at two levels (default vs include_personal) plus an explicit exclusion list. Nothing an agent needs to call this 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 coverage is 100%, so baseline is 3, but the description expands include_personal far beyond the schema's abbreviated note by listing the exact personal data classes it unlocks. This goes past restatement and helps an agent judge whether to set the flag.

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?

"One employee by id" states a specific verb and resource and immediately scopes it to single-record retrieval, distinguishing it from list_users. The enumeration of returned field groups makes the tool's identity concrete rather than tautological.

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 singular "one employee by id" implies you need an id and that list_users is the alternative for enumeration, but no sibling is named and no when-not-to-use condition is given. Usage is inferable rather than 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the meaningful behavioral detail that the result set is company-wide by default (all employees, optionally including deactivated ones), which matters for volume. It says nothing about pagination, row caps, or cost of a full-company date range query.

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 dense sentences front-load the core capability and then the optional filters, with no filler. The trailing 'GraphQL query attendanceStatements' is implementation metadata of limited value to an agent but takes only a few words.

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 well by enumerating the metric families returned (expected vs tracked time, time off, holidays, balance, overtime, per-project tracked time). The main remaining gap is result-set size and pagination behavior for a required date-range query over all employees.

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 86%, so the schema already documents date_from/date_to, project_id, has_uncategorized_time and include_inactive_users. The description restates the filter semantics rather than adding constraints, and the two enum parameters (sort_by, sort_direction) receive no mention in either place beyond the enum 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?

States a specific verb and resource ('Attendance summaries of ALL employees over a date range') and enumerates the returned metrics, which distinguishes it from the singular kiwihr_get_attendance_statement by its 'ALL employees' scope. The sibling distinction is only implied by capitalizing ALL rather than named explicitly.

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 explains what the optional filters do ('only employees with time tracked on a project, or with uncategorized time; inactive employees can be included'), which implies when those filters apply. It never states when to prefer this over kiwihr_get_attendance_statement for a single employee, nor any prerequisites or limits.

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 genuinely non-derivable context: payroll and bank sections appear by name only and their values are never returned by any tool — a data-availability constraint an agent would otherwise waste calls discovering.

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 core purpose and the returned fields front-loaded, and no filler. The trailing 'GraphQL query customFields' is implementation metadata of marginal use to an agent selecting the tool, but it is only three words.

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 return-value burden and does so by enumerating the fields returned plus the payroll/bank exclusion. Pagination and sorting are fully covered by the schema, so nothing an agent needs to call this 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 coverage is 75% and the schema already documents limit, offset (including pageInfo.next), and sort_direction; only sort_by's enum lacks a description. The description adds nothing about sorting or pagination, so the baseline 3 applies — the schema does the work here.

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 plus resource ('List the company's custom employee profile fields') and enumerates the returned attributes, which no sibling tool covers. An agent can distinguish it from list_users, list_positions, or list_teams without opening a schema.

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 tool name and the field list, and there is no direct sibling alternative for custom fields, so no explicit when-to-use routing is strictly needed. However, the description never says when an agent should reach for this versus list_users when it needs profile metadata, nor does it state prerequisites such as admin scope.

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 genuine value by disclosing the returned fields (id, name, status enum values, assignee, type, custom date). It says nothing about pagination or result ordering, but the schema's offset/limit notes cover paging.

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: what it returns, how to filter, and the underlying API. Nothing redundant and the core purpose 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?

With no output schema, listing the returned fields is exactly the right compensation, and paging/precision details live in the schema. Only the absence of routing guidance versus sibling journey tools keeps it short of full completeness.

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 filter parameter is already documented with its semantics. The description restates the filter dimensions and adds the useful mapping hint that journey type filters come from kiwihr_list_journey_types, but does not add syntax or format detail 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?

States a specific verb and resource ('List onboarding/offboarding journeys') and enumerates the fields returned, so the agent knows exactly what entity and shape to expect. It does not explicitly distinguish itself from kiwihr_get_journey or kiwihr_list_journey_templates, though the list-vs-get naming makes the split reasonably clear.

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?

'Filter by status, assignee, type or team' implies when the filters are useful, but there is no explicit guidance on when to call this versus kiwihr_get_journey for a single journey or kiwihr_list_journey_types for the type catalog. Usage is inferable but not stated.

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 without description help. The description adds only the backing implementation detail ('GraphQL query journeyTemplates'), with no mention of rate limits, auth scope, or result ordering beyond the field 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?

Three compact fragments, the resource definition front-loaded ahead of the follow-up usage hint and the backing query. Nothing redundant; 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?

For a read-only list tool with no output schema, the description enumerates the returned fields and points at the consuming tool, and the schema fully covers pagination. Only minor gaps remain, such as ordering and whether pageInfo is returned in the reply.

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 limit, offset and journey_type_id each documented including defaults and the pageInfo.next hint. The description adds no additional filtering or format semantics, 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+resource ('List journey templates') and enumerates the returned fields (id, name, description, type), which lets an agent distinguish it from kiwihr_get_journey. It does not explicitly contrast with kiwihr_list_journeys or kiwihr_list_journey_types, so the sibling split is only implied by the resource name.

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 downstream hint 'Use a template id with kiwihr_create_journey' gives a clear purpose for the result, which is useful workflow context. However, there is no statement of when to prefer this over kiwihr_list_journey_types or kiwihr_list_journeys, and no exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful return-field context (id, name, key, archived date) that annotations do not provide, but it does not describe pagination behavior or ordering, and the GraphQL query note is an implementation detail.

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 a single front-loaded sentence that is easy to parse. The trailing 'GraphQL query journeyTypes' notes internal implementation and adds little value for an agent deciding whether to call the tool.

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 usefully enumerates the returned fields and clarifies what journey types are. It is nearly complete, missing only an explicit contrast with sibling list tools.

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 both limit and offset are fully documented in the schema. The description adds no parameter meaning beyond that, making the baseline 3 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 names a specific verb and resource ('List journey types') and gives examples that clarify what a journey type is (pre-onboarding, onboarding, offboarding). It also lists the fields returned. However, it never explicitly distinguishes this from sibling tools like kiwihr_list_journeys or kiwihr_list_journey_templates, so an agent must infer the boundary.

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 statement about when to use this tool versus alternatives such as list_journeys or list_journey_templates. The purpose is implied by the examples, but no conditions, prerequisites, or exclusions are provided.

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 only "GraphQL query locations," which is implementation trivia rather than behavioral context; no mention of result volume, page limits, or data freshness beyond what the schema's pagination params imply.

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, front-loaded sentences with no filler. The trailing "GraphQL query locations" earns little, but the overall definition is tight and scannable.

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 names the returned fields (id, name) and the consumer of those ids. Pagination is handled by the schema's limit/offset/pageInfo wording, so an agent has enough to call this correctly, though it says nothing about total result volume.

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 75% and documents limit, offset and sort_direction, with enums constraining both sort parameters. The description only hints at output fields, adding nothing about sorting or paging semantics, so 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?

States a specific verb and resource ("List office locations") and even names the returned fields (id, name). It is unambiguous against the many other kiwihr list_* siblings by virtue of the 'locations' resource, though it never explicitly distinguishes itself from list_teams or list_positions.

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 to filter employees" gives concrete downstream context that tells an agent why to call this tool. It offers no exclusions or named alternatives, so it falls short of a 5, but the usage intent 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=true, openWorldHint=true, and destructiveHint=false. The description adds useful context that the values are current balances in seconds scoped per employee, but it omits return structure, pagination behavior, and any auth or rate-limit context.

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 short sentences are front-loaded with the result and unit. The GraphQL query name is implementation detail but compact and not harmful.

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, annotations cover safety and the schema covers pagination and sorting. However, with no output schema, the description only minimally describes the return shape and does not clarify period semantics or response structure.

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 75%, with limit, offset, and sort_direction documented, while sort_by has only an enum. The description adds no parameter-level meaning beyond the schema, so the 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 states a specific resource and unit: current overtime balance in seconds per employee. It is clear what is returned, but it does not explicitly distinguish this from sibling tools such as kiwihr_list_time_off_balances or attendance statements.

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 only identifies the backing GraphQL query and gives no guidance on when to use this tool versus alternatives. An agent must infer the use case from the name and cannot tell from the description whether to choose this over time-off balance or attendance 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the returned fields and that the backend is a GraphQL query, but says nothing about pagination behavior or result size, which the schema covers only partially.

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 fragments, front-loaded with the resource and return shape. 'GraphQL query positions' is arguably an implementation detail that earns little, but nothing bloats the definition.

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, zero-required-parameter listing tool with annotations covering safety and a schema covering paging and sorting, the description gives enough to call it correctly. Return values are summarized as id/name, which is sufficient given there's no 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 coverage is 75% with limit, offset and sort_direction documented inline; only sort_by lacks a description, and its enum makes it self-evident. The description adds no parameter guidance beyond the schema, 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 job positions') and names the returned fields (id, name). It is distinguishable from the surrounding siblings (projects, teams, journeys), though it doesn't explicitly contrast itself with any of 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?

'Use the ids to filter employees' hints at a downstream use case but gives no explicit when-to-use rule, prerequisites, or alternative tools for looking up position data. Usage is implied rather than prescribed.

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 operation. The description adds the returned project fields and mentions that it is a GraphQL query, but it does not add further behavioral context such as pagination behavior, authorization requirements, or rate limits.

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 short and front-loads the purpose and returned fields. The second sentence, 'GraphQL query projects,' is largely an implementation detail and does not contribute much, but the overall definition remains efficient.

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 provides the essential returned fields and the schema covers pagination and sorting details. It is adequate, though it could mention pagination or the single-project alternative more explicitly.

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 80%, so the schema already documents most parameters and provides the baseline of 3. The description mentions the status values ACTIVE or INACTIVE, but this duplicates the enum already present in the schema and does not add meaning beyond it.

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: 'List time-tracking projects'. It also names the returned fields (id, name, status) and distinguishes itself implicitly from the singular get_project sibling. It stops short of explicitly differentiating from other project-related siblings like get_project or create_project.

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 says what the tool lists but provides no when-to-use guidance, exclusions, or alternatives. It does not tell the agent when to list projects versus retrieving a single project with get_project, nor does it explain when status filtering or pagination should be used.

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 shape of the returned record (id, name, kind) and the GROUP/DEPARTMENT distinction, which is genuinely useful, but says nothing about pagination, result volume, or scoping that the schema's pageInfo note does not already handle.

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 the action and result shape, with the practical follow-up use immediately after. "GraphQL query teams." is largely redundant with the name and is the one sentence that does not fully earn 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 zero-required-parameter read-only list tool with annotated safety hints and pagination documented in the schema, the description supplies what is missing: the returned fields and the kind enumeration. Only the return envelope (page shape) is left implicit, which is minor.

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 75% with defaults and enum constraints documented, including the pageInfo.next hint for offset. The description contributes nothing about limit/offset/sort parameters, so the baseline 3 is appropriate; only `sort_by` lacks a schema description and could have used a line here.

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 teams and departments") and even enumerates the returned fields plus the two possible `kind` values, which no sibling list tool claims. It is clearly distinct from kiwihr_list_locations, kiwihr_list_positions and kiwihr_list_users, though it never explicitly contrasts itself with 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?

"Use the ids to filter employees" gives the downstream purpose, which implies when to reach for this tool (you need team/department ids for employee filtering). However, it names no alternative tool and states no when-not conditions, so selection guidance is only implied.

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 read-only, non-destructive, open-world profile, but the description adds substantive traits beyond them: no per-employee filter, no paging, and results must be read per user, which materially affects invocation strategy. It also names the underlying GraphQL query (timeOffBalances), useful for debugging. It doesn't discuss result volume or ordering guarantees, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the tool returns and followed by filtering and API constraints; no filler. Slightly dense enumeration but 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, the description compensates by itemizing the returned fields, and the no-paging/no-per-employee-filter caveat closes the biggest behavioral gap. What's missing is minor: sorting behavior and rough result-size expectations.

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 83%, so the schema already documents nearly every parameter with meaning, formats and cross-references (e.g. time_off_type_id from kiwihr_list_time_off_types). The description only restates the filter categories and says nothing about the sort_by/sort_direction parameters, adding little 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 uses a specific verb and resource ('Time off balances of all employees') and enumerates the returned fields (allowance, accrued, used, requested, planned, available, carry-over, periods), so an agent knows exactly what comes back. It does not explicitly differentiate itself from close siblings like kiwihr_get_time_off_usage or kiwihr_list_overtime_balances, which keeps it from a 5.

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?

'Filter by time off type, active state and usage period' plus 'The API has no per-employee filter or paging for this query; read the result per user' gives concrete, actionable usage context, including an important constraint that shapes how the agent should call it. There is no explicit when-to-use-versus-sibling routing, so it falls short of a 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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds value by enumerating the fields returned, which matters because no output schema exists. It discloses the underlying GraphQL query but says nothing about result volume, rate limits, or default page size beyond what the schema states.

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 tight sentences with the resource definition front-loaded and the integration hint second. The trailing 'GraphQL query timeOffTypes' is an implementation detail of marginal value to an agent, the only slightly wasteful element.

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-parameter read-only list tool with annotations covering safety and a schema covering pagination, the description supplies the one thing missing: what fields come back and how the ids feed other tools. Only the undocumented sort_by enum is left uncovered.

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 75% with documented limit, offset and sort_direction, so the schema does the heavy lifting. The description adds no parameter guidance at all and does not compensate for sort_by, which is an undescribed enum in 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 (List) and resource (time off/absence types), gives concrete examples ('vacation or sick leave'), and enumerates the returned fields (id, name, colour, visibility). It also distinguishes itself from the adjacent time-off resources by naming kiwihr_list_time_off_balances and kiwihr_get_time_off_usage as consumers of these ids.

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 with the result: use the ids with kiwihr_get_time_off_usage and kiwihr_list_time_off_balances. This makes the tool's role as a prerequisite lookup clear, though it doesn't state any when-not-to-use condition or prerequisite permissions.

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 safety is covered. The description adds meaningful behavior beyond that: values are in SECONDS, break-rule violations are surfaced, and omitting user_id falls back to the API key's admin user.

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?

A single dense sentence that front-loads scope (one employee, date range) before the field enumeration; nothing is redundant. The long parenthetical field list is information-dense but slightly harder to scan than a short bulleted structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the returned fields, and pagination is handled by the schema's limit/offset descriptions. It lacks any note on permissions or on how the range boundaries are treated, which would round it out fully.

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% — limit, offset, date_from, date_to and user_id are all documented in the schema, including the default-admin fallback. The description adds no parameter detail beyond what the schema already provides, 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+resource ('Daily timesheets of one employee ... in a date range') and enumerates the returned data (expected/tracked/time off/holiday/break in seconds, approval flag, entries, break-rule violations), so the agent knows exactly what this retrieves. It does not explicitly distinguish itself from the singular kiwihr_get_timesheet sibling, which keeps it from a 5.

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 only implied: fetch daily timesheets for one employee over a date range. There is no explicit statement of when to prefer this over kiwihr_get_timesheet (single-day) or kiwihr_list_attendance_statements, and no exclusions or prerequisites are 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 establish readOnly/non-destructive/openWorld, and the description adds genuinely non-obvious context: sensitive payroll, bank, tax and insurance data are never returned, and the underlying call is a GraphQL users query. It does not discuss pagination behavior, though the schema's offset/limit descriptions and pageInfo.next note already cover that.

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: identity and return fields first, filters second, data-exclusion caveat last. No filler and each 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?

For a 13-parameter list tool with no output schema, the description covers both selection criteria and the returned field set plus a key data-scope limitation. Only pagination/sorting behavior is left unmentioned, and that is documented in the schema itself.

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 one of the 13 parameters is already explained, including cross-references like team_id (from kiwihr_list_teams). The description only restates the filterable fields, adding no syntax or semantics beyond the schema, 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?

Names a specific verb (list/search) and resource (employees / 'users') and enumerates the returned fields and filter dimensions, so the agent knows exactly what it gets back. It does not explicitly distinguish itself from kiwihr_get_user, so sibling routing relies on inference from 'list'.

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?

Says to filter by active state, team, location, position, e-mail or name, which implies the usage pattern, but gives no explicit when-to-use/when-not or named alternative such as kiwihr_get_user for a single record. Usage is implied rather than 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?

Annotations already declare write/destructive/idempotent, but the description adds real consequence detail beyond them: INACTIVE projects can no longer be used for time tracking, and unspecified fields are left untouched. That downstream side effect is exactly the risk context an agent needs before mutating.

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 compact sentences, front-loaded with the WRITE marker and the operation split, followed by the side effect and the partial-update rule. No filler and nothing buried.

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 3-parameter mutation with full schema coverage, safety annotations, and no output schema, almost everything needed to invoke it correctly is present. Only the response shape and a pointer to sibling read tools are absent, both minor.

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 a 3 is the floor; the description earns above baseline by explaining the observable effect of the status enum value (INACTIVE blocks time tracking), which the schema's "New status." does not convey. The project_id and name params need no further gloss 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?

States a specific verb class ("WRITE: rename ... or switch") and resource (project), and enumerates the only two mutate-able fields. This clearly separates it from kiwihr_create_project, kiwihr_get_project, and kiwihr_list_projects without needing to open a schema.

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 for use — renaming or toggling ACTIVE/INACTIVE — plus the partial-update rule ("Only the fields you pass are changed"), which is what an agent most often gets wrong on update tools. No explicit alternatives or when-not-to-use are named, so it stops short of a 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 write, idempotent, destructive and open-world; the description adds genuinely new behavior: partial-update semantics ('only the fields you pass are changed'), a concrete return value ('returns the updated day'), and the underlying GraphQL mutation name. It restates idempotency rather than explaining it, so a small deduction.

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 short paragraph, front-loaded with the operation type, then the id prerequisite, then field semantics, then return value. No sentence is 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?

Covers everything an agent needs to call it correctly: how to get the required id, that unpassed fields are untouched, the result shape, and the underlying API operation. No output schema exists, and the description supplies the return value it would otherwise lack.

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% – formats, enum values, and max lengths for all six parameters are already documented. The description's 'only the fields you pass are changed' adds mild meaning about optionality, but otherwise repeats the field list without new constraints.

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?

Starts with 'WRITE: change an existing timesheet entry' – a specific verb plus resource – and enumerates the mutable fields (times, part of day, project, note), which cleanly separates it from kiwihr_create_timesheet_entry and kiwihr_delete_timesheet_entry among the 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?

Explicitly routes the agent to kiwihr_get_timesheet to obtain the entry_id, which is the main prerequisite. It does not spell out when to prefer this over create/delete siblings, but that is largely self-evident from the verb.

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=true, idempotentHint=true and openWorldHint=true, so the safety profile is carried. The description adds real value beyond them: partial-update semantics, the fact that team_ids and work_phones replace the entire list rather than append, and an explicit scope exclusion for private/payroll/bank fields. It does not mention permission requirements or what the response contains, which keeps it below 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the WRITE marker so the mutating nature is the first thing read. Every clause carries information: field list, partial-update rule, list-replacement caveat, exclusion boundary, and the underlying GraphQL mutation name.

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 10-parameter mutation with no output schema, the description covers the important behavioral questions: what changes, what is left alone, which fields are off-limits, and how list fields behave. The remaining gap is discoverability of the ID-valued parameters, which an agent must infer from the sibling list tools.

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 only 30% across 10 parameters, so the description does meaningful work by naming the updatable fields and clarifying list-replacement for team_ids and work_phones beyond the schema's own "Replaces the list of..." notes. However it leaves the *_id parameters unexplained: nothing says location_id/position_id/manager_id/team_ids must come from kiwihr_list_locations, kiwihr_list_positions, kiwihr_list_users or kiwihr_list_teams, nor does it cover the first_name/last_name split or the date format.

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 mutation marker ("WRITE: change an employee's work profile") and enumerates the exact mutable surface: name, start date, about-me, work phones, position, team(s), location, manager. That lets an agent separate it from kiwihr_create_user, kiwihr_deactivate_user and kiwihr_update_timesheet_entry without reading any schema.

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?

"Only the fields you pass are changed" states the partial-update contract clearly, and "Private, payroll and bank data cannot be changed with this tool" sets a firm boundary on when this tool will not work. It stops short of naming the alternative for private/payroll/bank edits or pointing to sibling tools, so it is a strong 4 rather than a 5.

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