SmartHR MCP by usefulapi

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

The 'WRITE:' prefix and 'Returns the created department' are useful, but the former largely restates readOnlyHint=false and the latter is the only substantive addition given no output schema. Annotations already flag destructiveHint=true and idempotentHint=false, yet the description never explains the consequences: what a failed call leaves behind, whether duplicate names are rejected, or that retrying can create duplicates.

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 zero waste; the write nature and the core operation are front-loaded, and the nesting hint follows immediately.

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

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

With no output schema, the description compensates by naming the return value, and all five parameters are documented in the schema. The only gap is behavioral detail around the non-idempotent, destructive-create semantics, which the description leaves to the annotations.

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

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

Schema coverage is 100% with per-field descriptions, so the schema carries the semantics and baseline 3 applies. The description only reinforces parent_id nesting, which the schema already documents.

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 a department (部署)') plus the nesting mechanism and the return value. It is clearly distinguishable from smarthr_update_department by the verb, 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?

'Give the parent department id to nest it' implies the hierarchical case, but there is no explicit when-to-use vs smarthr_update_department, no note about when company_id becomes mandatory, and no prerequisites such as required 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 flag destructiveHint=true and idempotentHint=false; the description reinforces this with a 'WRITE:' marker and adds genuinely new context by disclosing that the returned record omits pension number, income and documents. It does not explain why the call is destructive, what permissions are needed, or what happens on a duplicate submission, which are the remaining behavioral gaps.

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, no filler, and the operation class ('WRITE:') plus resource are front-loaded. The prerequisite and return caveat follow in priority order.

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

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

For a 9-required-parameter mutation with a nested object and no output schema, the description covers purpose, prerequisite, and return shape adequately. It leaves out duplicate-handling behavior and permission requirements, which matters for a non-idempotent, destructive write, but the core calling information is present.

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% across all 15 parameters, including enums and the nested address object, so the schema does the heavy lifting. The only parameter guidance in the description (relation_id comes from smarthr_list_dependent_relations) merely restates what the schema already says, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb+resource ('Register a dependent for an employee') and prefixes 'WRITE:' to signal the operation class, which cleanly separates it from read siblings like smarthr_list_dependents and smarthr_get_employee. It even states the return shape, so an agent knows exactly what the call does without opening the 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: 'Needs the relation id from smarthr_list_dependent_relations', which routes the agent to the correct sibling before calling. It does not state when NOT to use it (e.g. if the dependent already exists, or pointing to smarthr_list_dependents to check first), so it stops short of full when/when-not 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?

The description adds substantial behavior beyond the annotations: no notification is sent to the employee, only supplied fields are set, tenant plan limits can produce plan_limit_exceeded, and the created employee is returned as a compact record. These are non-obvious side effects and error conditions that materially help invocation.

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

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

The description is four efficient sentences, starts with the operation type, and immediately covers the key distinction from the invite sibling. There is 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?

Given the high parameter count and fully documented schema, the description covers the most important behavioral context: side effects, plan-limit errors, the invite follow-up, and the return shape. 'Compact record' is slightly vague without an output schema, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so all 23 parameters are already well documented in the schema. The description adds only a general note that unspecified fields remain unset, which is useful but does not add parameter-specific meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Register a new employee (従業員) in SmartHR.' It also distinguishes this creation step from the sibling invite step, so an agent can tell what this tool does without opening the 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?

It clearly explains that this tool only registers the employee and that smarthr_invite_employee should be used afterwards to invite them. It does not explicitly contrast with smarthr_update_employee or state broader prerequisites, but the primary usage boundary 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?

readOnlyHint already covers the safety profile, so the bar is lower; the description still earns credit by disclosing the response contents — the department's parent and children — which is real behavioral information not in any structured field. It omits edge behavior such as what happens with an unknown id or whether child expansion is bounded, keeping it short of a 5.

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

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

A single clause, front-loaded with the verb and resource, with the return shape appended. Nothing to trim 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 one-parameter read tool with annotations covering safety and no output schema, the description supplies enough: what it returns and how to identify the record. Minor gaps remain around missing-id behavior and whether the children list is complete or truncated.

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 the schema already documents it at 100% coverage, including the provenance hint ('from smarthr_list_departments'). The description's 'by id' adds nothing the schema does not already supply, 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 ('Get one department by id') and even names the returned shape (parent and children), plus the Japanese term 部署. The singular 'by id' framing distinguishes it cleanly from smarthr_list_departments without needing the 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?

The 'by id' phrasing implies this is the detail-fetch counterpart to the list tool, but no alternative is named and no when-not guidance or prerequisite 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 only declare readOnlyHint=true; the description adds real behavioral context beyond that: the default response is a compact record, sensitive data is never returned, and bank/insurance/tax/salary/ID-document data is unavailable. It does not say what happens when the id is not found, which is the main 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?

Three short sentences, front-loaded with the verb and resource, then the return-shape expectation, then the data restriction. Nothing is wasted or 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?

With no output schema, the description does the necessary work of setting return-shape expectations (compact by default, expand via `fields`) and ruling out sensitive data. Error behavior for a missing id is the only meaningful omission for a read-only two-parameter 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?

Schema coverage is 100%, so both `id` and `fields` are fully documented in the schema, including the enum and the never-available categories. The description's 'compact record' framing and field examples largely restate the schema description, so it sits at the baseline rather than adding much new meaning.

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: 'Get one employee by id', which is clearly a single-record fetch and implicitly contrasts with the list siblings. It does not explicitly name smarthr_list_employees as the alternative, so differentiation is only implied by 'one ... by id'.

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

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

It tells the agent to use `fields` when address, phone, birth date, custom fields or contract dates are needed, which is useful in-call guidance. However, there is no explicit when-to-use-this-vs-alternatives statement (e.g. versus smarthr_list_employees or smarthr_list_users), leaving the routing to inference.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses the external side effect (an email is sent to the employee), the re-invocation/re-send semantics, the address-update behavior, and the hard failure mode for already-accepted employees. The user-confirmation requirement is extra operational guidance not in the annotations.

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

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

Three tight sentences: the write/email warning is front-loaded, then the mechanism, then the re-invocation and failure rules, ending with the confirmation instruction. 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?

With only 3 parameters, full schema coverage, no output schema, and annotations covering safety, the description supplies everything an agent needs: side effects, preconditions, re-send semantics, and the confirmation requirement.

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 id, inviter_user_id, and crew_input_form_id are already documented in the schema. The description only restates the email requirement already present in the id parameter's description, adding no syntax or format detail. 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 ('Invite an employee to SmartHR') and explains the mechanism (an email with a login-creation and data-entry form). This clearly distinguishes it from smarthr_create_employee, which creates the record rather than inviting the person.

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 concrete conditions: employee must have an email, re-calling re-sends the invitation and updates the address, and already-accepted employees cannot be re-invited. It also mandates confirming with the user first. It never names a sibling alternative explicitly, 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?

readOnlyHint=true already declares the safety profile, so the description's burden is light. It adds the useful fact that insurance registration data comes back, but says nothing about pagination behavior, result ordering, or volume limits that a listing tool would benefit from.

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 compact sentence with the resource front-loaded and no filler. It is a sentence fragment, but every element (resource, localized name, returned fields) 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, zero-required-parameter list tool with a fully described schema and no output schema, the description is adequate but thin. It never clarifies the returned shape beyond three field names or how this differs from the closely named list_companies 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 coverage is 100%, so page, per_page, and embed are fully documented in the schema, giving a baseline of 3. The description's mention of 'company' and insurance data hints at what the embed enum yields but does not explain the embed options 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 ('List') and resource ('business establishments (事業所)') and enumerates the returned fields (name, social/labor insurance registration, company). This distinguishes it reasonably from smarthr_list_companies, though it never explicitly contrasts the two.

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

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

There is no statement of when to use this tool versus smarthr_list_companies or smarthr_list_employees, and no mention of pagination workflow or when to use embed. The only guidance is implicit in the tool name.

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?

readOnlyHint already declares this is a safe read. The description adds useful value by enumerating the fields returned (name, code, corporate number, address, phone), which matters because there is no output schema. It says nothing about pagination behavior or result ordering, which the schema only partially covers.

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 with no filler; the resource comes first and the returned fields follow as a compact list. Nothing can be trimmed without losing 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 simple read-only list tool with fully documented parameters, the description covers scope and returned fields, which is the main gap left by the absent output schema. Only missing piece is any hint about pagination or 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 100%, and both parameters (page, per_page) are fully documented in the schema including defaults and the 'use next_page' hint. The description adds no parameter information, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the companies') and adds tenant scoping plus the Japanese term 会社, which disambiguates the business meaning. It does not distinguish itself from the closest sibling smarthr_list_business_establishments, so it falls short of 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?

There is no statement of when to use this versus alternatives — notably smarthr_list_business_establishments, which an agent could easily confuse with this tool. Usage is only implied by the tool's name and the word 'List'.

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, so the safety profile is covered and the description is not obligated to restate it. The description does add value by disclosing that hierarchy data (parent, children) is included in the response, but says nothing about pagination behavior, result ordering, or whether all departments are returned by default.

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

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

A single sentence with no filler, front-loading the resource and then the returned fields. Every clause carries information an agent can use.

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 a fully documented schema and readOnlyHint annotations, this is nearly complete: it identifies the resource and its key returned fields. The remaining gap is that it never mentions pagination or result volume, which matters because the schema exposes page/per_page.

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 four parameters (code, page, per_page, sort) fully documented in the schema, so the baseline is 3. The description adds no parameter-specific meaning beyond naming "code" as part of the output, which is not the same as explaining the exact-match filter input.

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 departments") and even enumerates what comes back (hierarchy, code, company), so the agent knows the shape of the result. It does not differentiate itself from the sibling smarthr_get_department or explain why one would list rather than fetch a single department, 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?

There is no when-to-use guidance, no mention of the smarthr_get_department alternative, and no note that the code filter is an exact match versus a broader browse. Usage is only implied by the verb "List", leaving the agent to infer the selection context.

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

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

readOnlyHint=true already declares the safe read-only profile, so the description only needs to add context. It does disclose the return content (relation type names plus ids), which is useful given there is no output schema, but says nothing about pagination behavior or result size limits beyond what the schema field descriptions already state.

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 tightly packed sentence with the purpose, examples and the downstream consumer front-loaded; no wasted words. It is perhaps overly compressed, since the sibling disambiguation is left implicit.

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 two-parameter read-only lookup with a fully described schema, the description covers what the tool returns and why an agent would call it. Nothing further is required to invoke it correctly.

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

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

Schema description coverage is 100% and both paging parameters are fully documented in the schema, including the next_page hint. The description adds no parameter-level meaning, 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: listing dependent relation types (with Japanese term 続柄 and concrete examples) plus the ids returned. An agent can tell this is a lookup/enumeration tool, though it never explicitly distinguishes itself from the similarly named sibling smarthr_list_dependents.

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?

"needed by smarthr_create_dependent" gives a concrete when-to-use condition and names the consuming tool. It stops short of stating when not to use it or that smarthr_list_dependents is a different, unrelated listing.

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?

readOnlyHint already establishes safety, and the description adds real value beyond annotations by declaring the returned field set and, notably, that pension numbers, income and documents are excluded — useful privacy/scope context for a sensitive HR domain. Pagination behavior is left to the schema.

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 purpose and scope, then the exclusion clause. No filler and nothing an agent must read twice.

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 a fully documented schema and a readOnly annotation, the description covers the remaining gap — what is and isn't in the response — which matters since there is no output schema. Only pagination/result-shape specifics are left implicit via the schema.

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

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

Schema description coverage is 100%, with page/per_page/employee_id all documented in the schema itself (including the 'from smarthr_list_employees' hint). The description adds no parameter-level detail beyond that, 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?

Specific verb (List) and resource (dependents) with explicit scope: 'registered for one employee', plus the exact fields returned. It doesn't explicitly name the closest sibling (smarthr_list_dependent_relations, which lists relation types rather than a person's dependents), so an agent must infer that distinction.

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 'registered for one employee' and the employee_id requirement, but there is no explicit when-to-use/when-not or reference to alternatives like smarthr_list_dependent_relations or smarthr_create_dependent. The exclusions listed concern returned fields, not tool selection.

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

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

readOnlyHint=true already declares the safety profile, so the description's added value is the return shape (name, type, dropdown choices) and tenant scoping. It does not mention pagination behavior or the effect of the embed parameter, though the schema covers those.

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, front-loaded with the verb and resource, followed by the one usage hint that matters. Nothing redundant.

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 does describe the returned fields, which is the key need for a read-only listing tool. Minor remaining gap: it does not mention paging or the grouped-vs-flat effect of embed, though the parameter schema documents both.

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 page, embed and per_page are already fully documented in the schema. The description adds nothing about them, which is the baseline 3 case where structured data does the heavy lifting.

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 a precisely scoped resource: 'List the definitions of the tenant's custom employee fields,' and even enumerates what a definition contains (name, type, dropdown choices). This cleanly distinguishes it from sibling list tools such as smarthr_list_employees, which return records rather than schema definitions.

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 them to read the values in custom_fields' gives a concrete when-to-use condition tied to interpreting employee data. It stops short of naming an alternative or stating exclusions, but the context for calling it 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the scoping fact that only invitation-eligible forms are returned, which is real behavioral information, but says nothing about ordering, result size, or what a form object contains (no output schema exists to 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?

A single front-loaded sentence with zero waste. It is efficient but also very thin, leaving the ambiguous invitation qualifier unexplained rather than trimming anything unnecessary.

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

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

For a simple read-only paginated list, annotations and schema carry most of the burden, but the description leaves the link to smarthr_invite_employee implicit and, with no output schema, gives no hint about the returned form shape or identifiers an agent would need downstream.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema, including the next_page hint. The description contributes no additional parameter meaning, 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 (List) and resource (employee information collection forms), and includes the Japanese term for disambiguation. The qualifier 'that an invitation can use' narrows the set but is itself slightly ambiguous; it does however separate this from sibling list tools like smarthr_list_employee_custom_fields.

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 through the phrase 'that an invitation can use', which hints at a workflow with smarthr_invite_employee but never states when to call this versus other list tools or what an agent should do with the results. 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 only declare readOnlyHint=true, and the description adds genuinely useful behavior: results are compact by default, the `fields` parameter expands them, and sensitive data (bank accounts, insurance numbers, residence cards, salary, ID images) is never returned regardless of request. It stops short of describing pagination or result-size behavior.

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

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

Three sentences, front-loaded with what the tool does and immediately followed by the return-shape and sensitivity notes. The middle filter enumeration is long and duplicates the schema, but nothing is padded or redundant at the sentence level.

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 16-parameter read-only list tool with no output schema, the description covers scope, filterable dimensions, default output shape, expansion via `fields`, and the security boundary. Minor gaps remain around pagination behavior and result volume, both partially covered by the schema's page/per_page fields.

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

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

Schema coverage is 100%, so the schema already documents all 16 parameters including the fields enum, defaults, and the sensitive-data exclusion. The description's filter list and 'use `fields` for more' largely restate those fields rather than adding syntax or semantics; 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 concrete verb (List) and resource (employees 従業員) scoped to the SmartHR tenant, and enumerates the filter axes (free-text, status, emp_code, type, department, position, date ranges). It does not distinguish itself from the adjacent smarthr_list_users or smarthr_get_employee, so sibling differentiation is left to 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?

Usage is only implied: you call it when you want to enumerate employees, and the single explicit routing hint is the internal one 'use `fields` for more'. There is no statement about when to prefer smarthr_get_employee for a single record or how this differs from smarthr_list_users.

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, so the safety profile is covered and the description only needs to add context. It adds the useful detail that returned IDs are meant to feed filters and write operations, but says nothing about ordering, whether all/system-default types are included, or auth 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?

A single sentence, front-loaded with the verb and resource, followed by examples and the downstream purpose. Nothing is redundant or padded.

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 two-parameter read-only list with full schema coverage and no output schema, the description covers what the tool returns (types plus ids) and why. A brief note on whether the list is complete or paginated-by-default would make it fully self-sufficient, but nothing essential is missing.

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

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

Schema description coverage is 100% and both pagination parameters are fully documented in the schema, including the 'use next_page from the previous reply' hint. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (employment types, 雇用形態) with concrete examples of the values returned, so an agent can immediately tell it apart from siblings like list_departments or list_positions. No explicit sibling routing is given, but the resource is unique enough that differentiation is unambiguous.

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 'with their ids for filtering and writes' implies the intended workflow (fetch IDs, then use them as filters or in create/update calls), which is genuine usage context. However, it never states when not to use it, whether the list is exhaustive or paginated across all types, or what to do if the needed type is missing.

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, so the safety profile is covered by structured data. The description adds the useful detail that rank accompanies each grade, but says nothing about result volume, pagination behavior, or ordering — pagination is handled entirely by the schema.

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 with zero filler. It is efficient rather than padded, though its brevity borders on under-specification.

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

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

For a simple read-only paginated list tool with fully documented optional parameters and no output schema, this is just adequate. It does not describe what a 'grade' represents in the SmartHR domain or what fields besides rank are returned, leaving a small but real gap.

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

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

Schema description coverage is 100% for both optional parameters (page, per_page), including defaults and the 'use next_page from the previous reply' hint. The description adds no parameter meaning 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?

The description names a specific verb ('List') and resource ('grades', with the Japanese term 等級 to disambiguate the concept) and notes that rank is included. It is clearly distinguishable from siblings such as smarthr_list_positions or smarthr_list_employment_types, though it does not explicitly contrast 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?

There is no guidance on when to use this tool versus a sibling, nor any stated prerequisites or exclusions. Usage is only implied by the tool name and a one-line purpose statement.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, so the description carries a lower burden, but it still adds nothing beyond the name apart from the Japanese term. It doesn't mention pagination behavior, default ordering, or what a record contains, all of which are left to the schema to 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?

One short sentence with the resource stated up front and zero padding. It is not under-specified in the way a bare tool name would be, but there is almost nothing to 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?

For a trivial two-param read tool this is close to adequate, but with no output schema, the description should say at least what a job category record looks like or how to page through results. Neither is present, so the agent is guessing at the return shape.

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?

Both parameters are fully documented in the schema (page is 1-based with a hint to use next_page from the previous reply, per_page defaults to 50, range 1-100). The description adds no parameter detail at all, 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?

"List job categories" is a clear verb+resource pair, and the Japanese gloss (職種) pins down which resource is meant. It doesn't need to differentiate itself from siblings like smarthr_list_departments or smarthr_list_employment_types, since the resource name alone does that.

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 of when to call this, when not to, or what to do instead. The agent has to infer that this is the lookup used to resolve a job-category ID before filtering employees or creating records; nothing in the text says so.

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, so the safety profile is covered. The description adds real value beyond that by specifying which fields are returned ('expected birth, leave start/end and scheduled return dates') and explicitly stating that bank, insurance and memo data are excluded, which prevents the agent from over-claiming results.

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, zero filler: the first front-loads what the tool returns and for what scope, the second disambiguates excluded fields. Nothing here is redundant or padded.

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 paginated read-only list with no output schema, the description covers returned fields, excluded data, and scope, and pagination is handled by the schema. A brief note on ordering or empty-result behavior would make it fully complete, but nothing an agent needs to call it 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 page, per_page and employee_id are fully documented in the schema. The description only reinforces that the call is scoped to a single employee; it adds no syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the maternity and childcare leave records'), names the scope (one employee), and enumerates the returned fields. No sibling covers the same resource, so no sibling differentiation is needed, but the description doesn't spell out how it relates to other employee sub-resource listers.

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: the phrase 'of one employee' signals this is a per-employee lookup requiring employee_id, but there is no explicit when-to-use or prerequisite statement. No alternatives are named, which is acceptable given no sibling overlaps, but no positive guidance is given either.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower. It adds that records carry a rank and code, which is useful context about the returned shape, but says nothing about ordering, pagination scope, or result volume beyond what the schema already declares.

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 with zero filler. It states the resource, the aliases (job titles / 役職), and the field contents without padding.

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, optional-parameter list tool with full schema coverage and a readOnly annotation, the description covers the essentials. It is still thin on what distinguishes a 'position' from a grade or job category in this domain model, which is what an agent would need to pick correctly among the sibling list endpoints.

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% — page, sort, and per_page each carry their own constraints and examples (including the '-updated_at' sort syntax and next_page usage). The description adds nothing beyond that, 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 positions / job titles 役職) and even names the fields returned (rank and code), which is more than a tautology. However, it does not distinguish this from closely-named siblings like smarthr_list_grades and smarthr_list_job_categories, which an agent could easily confuse for the same concept.

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 indication of when to use this tool versus alternatives, no prerequisites, and no exclusions. Given the sibling set contains several similarly-purposed list endpoints (grades, job categories, employment types), the absence of any routing guidance is a real gap.

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

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

The readOnlyHint annotation already establishes this is a safe read operation. The description adds value by enumerating returned fields and invitation statuses (created, opened, accepted, answered), which is important behavioral context in the absence of an output schema.

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, both front-loaded and purposeful. The first defines the resource and returned data; the second gives the concrete usage scenario. No wasted wording.

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 full schema documentation and no output schema, the description supplies the important return-field context and a specific use case. Nothing critical for correct invocation appears 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 page, per_page, sort, and embed are fully documented in the schema. The description adds no parameter-specific syntax or constraints beyond that, fitting the baseline 3.

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 SmartHR users (login accounts)') and immediately distinguishes users from employees by noting the login-account nature, fields like administrator flag and invitation status, and linked employee. An agent can tell this apart from smarthr_list_employees without opening either 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 a concrete use case: find the administrator id for smarthr_invite_employee. It does not explicitly exclude alternatives such as smarthr_list_employees, but the intended usage context is clear and actionable.

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, so safety is covered; the description still adds meaningful context beyond that: secret tokens and the query string of the target URL are redacted from results. That redaction note is exactly the kind of thing an agent cannot infer from structured fields. It does not discuss pagination or result ordering, keeping it short of a 5.

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

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

Two compact clauses, front-loaded with the action and resource, followed by the security caveat. Every sentence carries information an agent needs; nothing is redundant with the title or annotations.

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 paginated list tool with no output schema, the description covers what the tool does, what it returns, and what is withheld, while pagination is handled in the schema. It stops short of describing the response envelope or empty-list behavior, which is a minor gap.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema, including defaults and the next_page hint. The description adds no parameter-level detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List the configured webhooks") and enumerates the salient returned fields (target URL, employee and dependent events). No sibling tool covers webhooks, so the resource name alone distinguishes it from the various smarthr_list_* tools for employees, departments, and dependents.

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 resource: an agent should call this when it needs to inspect webhook configuration. However, there is no explicit when-to-use framing, no prerequisites, and no mention of alternatives or exclusions. Adequate but with a clear gap.

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=true, and destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: it is a partial update (unspecified fields are preserved) and it returns the updated department. It stops short of warning about side effects of reparenting (moving a department with children).

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, front-loaded with the operation type and resource, with zero filler. Every clause (WRITE, partial update, return value) 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 5-parameter mutation with full schema coverage and no output schema, the description covers the essentials: mutation type, partial-update behavior, and a return-value statement. It could be stronger on reparenting side effects and when to prefer create vs update, but nothing an agent needs to invoke it 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% and every parameter has a docstring, including 'Omit to keep the current name' and where the id comes from. The description adds no parameter-level detail 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?

The description states a specific verb and resource ('Rename or move one department'), leads with a WRITE marker, and clarifies single-department scope plus partial-update semantics. An agent can distinguish this from smarthr_create_department and smarthr_update_employee 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?

The parenthetical 'partial update: only the fields you give change' implies the tool is for modifying existing departments rather than creating them, but it never names alternatives or states prerequisites (e.g., fetch id via smarthr_list_departments is only mentioned in the schema, not the description). Usage is implied 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?

Beyond annotations, it discloses important behavior: only provided fields change, department_ids replaces the current department list, positions names may be created, and filled-in names cannot be cleared. It also states the return shape as an updated compact employee record, adding meaningful 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?

The 'WRITE:' prefix is front-loaded and immediately signals mutation. The paragraph is dense but organized around action, typical uses, constraints, and return value, 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 24-parameter mutation tool with full schema coverage and no output schema, the description is complete enough. It explains partial update semantics, critical side effects like department replacement, a platform constraint around clearing names, and what is returned.

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 parameters are fully documented structurally. The description adds valuable semantic detail by explaining partial-update behavior, department_ids replacement semantics, and creation of unknown position names, going beyond the schema's field-level descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Change fields of one existing employee (partial update...).' It clearly distinguishes this update operation from create/get/list siblings by emphasizing partial updates to an existing employee.

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

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

It provides concrete typical uses: setting status to absent or retired with a resignation date, correcting contact fields, moving departments, and changing positions. It does not explicitly state when to avoid this tool versus siblings like smarthr_create_employee, but the usage context is clear.

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