intelliHR MCP by usefulapi

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

Annotations already declare the write/mutating profile, but the description adds what annotations cannot: that the employment record is modified, that intelliHR workflows may fire as a side effect, and that the record is left in an un-finalised state until the person returns. That lifecycle detail is genuinely non-obvious. It still doesn't cover failure modes or whether duplicate leave on the same job is rejected.

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

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

Four tight sentences, front-loaded with the 'WRITE:' signal, then scope, then side effects, then the prerequisite lookup and endpoint. Nothing is repeated and nothing is wasted.

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

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

For a non-idempotent write with no output schema, the description covers the operation, the side effects, the prerequisite reference lookup, and the follow-up finalisation step. Remaining gaps are minor: no indication of what identifier the call returns or how to subsequently finalise the leave.

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 83%, so the schema already carries most parameter meaning. The description contributes one useful pointer, that leave_type_id values come from list_reference_data extended_leave_types, but says nothing about fte semantics during leave or the id-vs-name precedence beyond what the schema already states.

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

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

Opens with an explicit 'WRITE: record extended leave' and names the concrete leave categories (parental, long service, unpaid) plus the target resource ('an existing job'). No sibling tool does anything similar, and the POST endpoint removes any ambiguity about the operation.

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

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

Gives real routing guidance by pointing to 'list_reference_data kind extended_leave_types' to resolve leave types before calling, and implies the leave must attach to an existing job (so get_job/list_jobs precedes it). It does not state exclusions, e.g. how this differs from other leave or person-update flows, 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 non-read-only, non-destructive, non-idempotent and open-world, so the safety bar is partly met. The description adds genuinely non-obvious side-effect disclosure — no welcome email is sent, no user account or job is provisioned — plus the underlying POST /people call. Auth requirements and rate limits are absent, keeping it below a 5.

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

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

Four short sentences, front-loaded with a WRITE marker and the required field, then scope limits, then the duplicate-check advice, then the endpoint. Nothing is padded or repeated.

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 creation tool with no output schema, the description omits what comes back — notably the new person's identifier, which the caller needs in order to attach a job or account afterwards. Side-effect disclosure is strong, but the return contract and the optional-field semantics leave real gaps.

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 45% across 11 parameters, so the description is expected to compensate, yet it only restates that last_name is required — which the schema already enforces via the required array. None of the optional fields (email_is_personal, employee_number, title vs. preferred_name) get clarification.

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 new person record in intelliHR') and immediately bounds the scope: person only, no job, no user account, no welcome email. That boundary is exactly what separates it from intellihr_update_person and the job-creation flows, so an agent can pick it without opening 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?

Gives a concrete pre-call step ('Check with list_people first to avoid duplicates') and clarifies that jobs and user accounts are created separately. It never names the specific sibling to use for those follow-ups, so routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint path and the set of related fields returned; with no output schema, that return-shape detail is useful, but nothing is said about behavior when the id does not exist or about permissions.

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 front-loaded sentence giving the record scope and returned fields, followed by the endpoint. No filler; 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 one-parameter read with no output schema, enumerating the returned fields plus the endpoint is close to complete. Left ambiguous is whether that field list is exhaustive and how missing or unauthorized ids behave.

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 0% for the single required job_id, so the description must compensate. "By id" only restates the parameter name and does not explain what kind of identifier it is (the UUID form lives only in the schema's regex pattern) or whether other identifier forms are accepted.

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 retrieval verb and resource ("One job by id") and enumerates the associated data returned (person, position title, location, business unit, supervisor, pay grade, remuneration, dates). This clearly separates it from intellihr_list_jobs, though no sibling is 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?

Usage is only implied: "One job by id" suggests a single-record lookup once an id is known, versus the list siblings. There is no explicit when-to-use guidance, no preconditions about where a job_id comes from, and no named alternative for other lookup needs.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful content scope (returns scheduled/upcoming changes and end date) but says nothing about response shape, pagination, or behavior when a job has no timeline entries.

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 fragments, front-loaded with the substantive content description followed by the endpoint mapping. No filler, though the fragment style is slightly clipped for an agent needing behavioral detail.

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 single-parameter endpoint with no output schema, the description covers the domain concept but not the return structure — an agent cannot tell what fields a 'timeline' entry contains or how many entries to expect. That gap matters more because no output schema exists to fill it.

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

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

The single required parameter has no schema description (0% coverage), so the description carries the burden. Embedding 'GET /jobs/{jobId}/timeline' signals that job_id identifies a job, but adds nothing about its UUID format or origin beyond what the schema's pattern already encodes.

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 resource (a job's timeline) and enumerates what it contains (scheduled changes, end date), plus the underlying endpoint GET /jobs/{jobId}/timeline. It implicitly separates itself from intellihr_get_job by focusing on upcoming/scheduled changes, but never names that sibling 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?

No guidance on when to reach for this versus intellihr_get_job (current state) or intellihr_list_jobs. The only hint is the phrase 'upcoming changes,' from which an agent must infer the use case; no exclusions or alternatives are 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 cover safety (readOnlyHint=true, destructiveHint=false), so credit goes to what's added: the explicit guarantee that 'health information is never returned' — a genuinely useful data-scope disclosure an agent cannot get from structured fields — plus the full breadth of the returned record and the underlying HTTP endpoint.

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

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

Two compact sentences: the return surface is front-loaded in the first, and the exclusion plus endpoint trail behind it. The long field list earns its length because there is no output schema documenting those fields.

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 field enumeration is essential and present, and the health-data exclusion sets a clear expectation. Remaining gaps are minor: no note on behavior for an unknown/archived id or on permission requirements.

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 0%, so the schema carries only the UUID pattern with no prose. The description compensates partially by saying 'by id' and showing GET /people/{id}, clarifying that a single person identifier is expected, but it adds no format hint or guidance on where to obtain the id.

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 with explicit cardinality: 'One person's full record by id.' The enumeration of returned sections (names, DOB, jobs, work rights, custom fields) plus the GET /people/{id} endpoint makes it unambiguous and clearly distinct from intellihr_list_people and intellihr_get_job.

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?

'By id' implies the precondition (you must already have a person id, so you need list_people first if not), but the description never names intellihr_list_people as the lookup alternative or intellihr_update_person as the mutation counterpart. Usage is inferable rather than 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the parenthetical clarification that business entities are legal employers and notes the underlying GET endpoint, but does not add behavioral details such as pagination behavior or response contents.

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

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

The description is two short, front-loaded statements with no filler. It gives the resource meaning immediately and appends the endpoint, keeping the definition easy to scan.

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

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

This is a simple read-only list tool with two fully documented parameters and annotations that cover its safety profile. The description does not explain return values, but given the low complexity and fully specified input schema, an agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100%, so both page and limit are fully documented in the schema. The description adds no parameter-specific meaning beyond what the schema already provides, which is acceptable at the baseline for full schema coverage.

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

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

The description clearly identifies the resource as the organisation's business entities and clarifies them as legal employers. It is specific enough to distinguish the resource from generic people or jobs, but it does not explicitly differentiate this tool from nearby siblings such as list_business_units or list_locations.

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

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

The description provides no guidance on when to use this tool, when not to use it, or which sibling list tool to choose instead. The endpoint reference implies a straightforward list operation, but the agent must infer all usage context from the name and schema.

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 only the GET endpoint and filter dimensions. It says nothing about pagination behavior, result size or ordering that would help an agent drive repeated calls.

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

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

Three short clauses, purpose front-loaded, nothing padded. The telegraphic fragments are efficient though slightly clipped; no information is wasted.

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

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

A simple four-parameter list tool with full schema docs and read-only annotations needs little more; the endpoint and filter list round it out. Only the absence of any pagination or result-shape hint keeps it below a 5, given there is 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 description coverage is 100% and each parameter is self-documenting, so the baseline of 3 applies. The description repeats that name and identifier act as filters but adds no matching semantics (partial vs exact, case sensitivity) beyond what the schema states.

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

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

Names the concrete resource and disambiguates the term by glossing business units as 'departments, teams', then states the filterable fields and underlying endpoint. It is clear what the tool returns a list of, though it never distinguishes itself from the closely-named sibling intellihr_list_business_entities.

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

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

There is no statement of when to reach for this tool versus alternatives such as intellihr_list_business_entities, and no prerequisite or scoping context beyond the filter fields. A caller has to infer the appropriate use from the name alone.

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 that this is a definition/metadata listing (not custom field values) and cites the GET endpoint, which is genuinely useful context. It does not mention pagination behavior, whether archived/deleted definitions appear, or how fresh the data is.

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 meaning of the resource; nothing is padded. The trailing 'GET /custom-field-definitions' is slightly redundant for an agent but is a legitimate grounding hint.

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?

This is a zero-required-parameter read tool with full schema coverage and annotations that already carry the safety profile, so the description need not explain return values. What it does provide — that the payload is field definitions with meaning and type across person/job/location scopes — 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% — page and limit are fully documented in the input schema. The description adds nothing about parameter semantics, so the baseline of 3 applies.

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

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

The description names the specific resource — custom field definitions — and explains what the resource is ('what each field on a person, job or location means and its type'). That distinguishes metadata/definitions from the list-style siblings such as intellihr_list_people or intellihr_list_reference_data, though it doesn't explicitly name a sibling to contrast with.

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

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

There is no when-to-use guidance and no excluded alternatives — nothing says to call this before reading or writing person data, or how it relates to other list tools. The parenthetical hints at a discovery use case but the agent must infer it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context the annotations do not: the snapshot semantics ('as at today'), the field set returned, and the four status categories. It stops short of return format, pagination behavior 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?

Two front-loaded sentences: the resource and its returned fields come first, filtering second. The field enumeration is long but each item earns its place by telling the agent what comes back in the absence of an 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?

For a 16-parameter read tool with no output schema, the definition compensates well by describing the returned attributes and the status taxonomy. The remaining gap is interaction between filters (mutual exclusivity, AND semantics) and sort/pagination defaults, which the schema only partially covers.

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 81%, so the schema already documents most inputs and the baseline is 3. The 'Filter by …' clause adds meaning by flagging which parameters act as filters, but it names only six and omits email, employee_number, job_id, updated_within_days, employment_condition_id and newest_first, leaving the impression that the listed set is exhaustive.

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 and defines the resource in domain terms ('roles people hold, past, current and future'), plus enumerates the fields returned and the backing endpoint (GET /jobs). It implicitly separates itself from intellihr_get_job (single record) and intellihr_list_people, though it never names those siblings 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?

'Filter by person, job title, status … upcoming/recent end dates' implies the retrieval use cases, but there is no explicit when-to-use vs intellihr_get_job / intellihr_list_people, and no guidance on combining filters or when a filtered list is preferable to a direct lookup.

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 elsewhere. The description adds value by naming the returned fields, but says nothing about pagination behavior or result volume, which matters for an open-world list endpoint.

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

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

A single front-loaded sentence enumerating the payload fields, followed by the endpoint. No filler, though the endpoint token is marginal redundancy for an agent that already knows the tool 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 simple two-parameter read tool with no output schema, the field enumeration effectively substitutes for a return-value description. The only gap is absent guidance on pagination iteration, which the schema's next_page note partially covers.

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, limit) are documented with defaults and ranges in the schema. The description adds no additional meaning about paging or filtering, 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?

Names the resource (locations/sites) and enumerates the fields returned (parent location, code, address, enabled flag, representatives), and 'GET /locations' makes the read operation explicit. It is distinguishable from siblings like list_business_entities or list_people, though it never states the discriminating verb 'list' in prose.

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 call this versus the many other list_* siblings, no prerequisites, and no exclusions. An agent must infer from the name alone that this returns all locations without filtering.

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 the useful behavioral detail that results can be projected to a point in time, but says nothing about pagination behavior, result size, or whether rates vary per currency.

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 with the payload stated first and the temporal option second; nothing is padded. The trailing 'GET /pay-grades' is mildly redundant with the tool's semantics but is cheap and aids endpoint-oriented agents.

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 must convey the return shape, and it only goes as far as 'pay grades and their rates' — no indication of fields, nesting, or pagination envelope (page/limit hints live only in the schema). Adequate for a simple read, but not fully self-sufficient.

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 each parameter (page, limit, as_at) is fully documented in the schema, including next_page chaining and RFC3339/yyyy-mm-dd formats. The description's mention of 'as at a date' merely echoes the as_at field, 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?

The description names the resource and its payload ('the pay grades and their rates') and pins the endpoint (GET /pay-grades), so an agent knows exactly what it retrieves. It lacks an explicit verb ('list') in the prose, relying on the name/title, and does not distinguish itself from siblings such as list_reference_data beyond 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?

'Optionally as at a date' implies the historical-lookup use case, which is the only usage context offered. There is no statement of when to prefer this over siblings (e.g. list_reference_data or list_jobs) and no exclusions or prerequisites.

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 new behavioral context: results are a point-in-time snapshot ('as at today'), health information is never returned (a data-privacy constraint an agent could not infer), and the underlying endpoint is GET /people.

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?

Purpose and return contents are front-loaded in the first clause, followed by filters, then a short privacy constraint. It is dense but every element earns its place; the long enumeration of returned fields is slightly heavy but justified 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 nine optional parameters and no output schema, the description usefully compensates by spelling out the returned fields and the snapshot semantics. Pagination mechanics live in the schema (next_page), so the main remaining gap is nothing an agent needs before calling; it is close to complete.

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

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

Schema coverage is 100%, so all nine parameters (including pagination, sorting and the on_extended_leave boolean) are already self-documented with semantics. The description only restates the filter set at a high level without adding syntax or format 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?

Names a specific verb and resource ('List the people (employees) in intelliHR'), then enumerates exactly what comes back: name, employee number, email, phone, addresses, emergency contact, employment status, jobs summary and custom fields. It is clearly distinguishable from the sibling intellihr_get_person (single record) and intellihr_list_users.

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

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

The description gives clear context for when this is the right call: bulk enumeration with optional filtering by name, email, employee number, job id, recency or extended leave. It does not explicitly name alternatives (e.g. use intellihr_get_person for a single record), so no exclusion guidance is present.

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 still adds real value by disclosing that document contents are not retrieved and by naming the exact metadata fields returned, which no structured field provides. It does not mention paging behavior, but the schema covers 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 terse fragments, front-loaded with the resource and its returned fields, then the scope limit, then the endpoint. No sentence is 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?

With no output schema, the description usefully enumerates the returned fields and states the content limitation, and paging is fully specified in the schema. The only shortfall is that person_id's meaning/format is left entirely to the schema pattern.

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 67%: page and limit are documented in the schema, while person_id carries no description. The description's GET path '/people/{personId}/documents' partially compensates by showing person_id is a path identifier, but adds no format or constraint detail beyond the schema pattern, so the baseline 3 holds.

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 resource (documents on a person's record) and enumerates the returned fields (file name, type, size, upload status, download link), which lets an agent distinguish it from list_person_skills, list_person_tasks and the other person sub-lists. The explicit 'Contents are not read' further pins down what this tool is not.

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: 'Contents are not read' signals this metadata listing is not the way to fetch a file's contents, but there is no statement of when to prefer it over get_person or the other person sub-list tools, and no prerequisites given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the response includes level and review details, and 'The whole list comes back at once' explicitly rules out pagination — a real operational detail an agent would otherwise have to discover. The endpoint reference also hints at the underlying contract.

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

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

Three short sentences, front-loaded with what is returned, then the full-list trait, then the endpoint. Little waste; the phrase 'as intelliHR returns them' is the only slightly hand-wavy part, though it usefully signals the payload mirrors the raw API shape.

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

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

For a one-parameter read tool with no output schema, the description covers what is returned (skills with level and review details), that there is no pagination, and the underlying endpoint. Combined with annotations covering safety and mutations, nothing essential for a correct call 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 0%, so the description must carry the single parameter's meaning. The endpoint path 'GET /people/{personId}/skills' implicitly maps person_id to the person whose skills are listed, but it doesn't explain the UUID format constraint stated in the pattern, nor error behavior for an unknown person. Marginal compensation for a single-parameter tool.

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 specifies a clear verb+resource: 'The skills assigned to a person', and scopes it with 'assigned to a person', which implicitly separates it from the org-wide intellihr_list_skills sibling. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than stated.

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 person_id and the per-person scoping, but the description never states when to choose this over intellihr_list_skills or intellihr_list_qualifications, nor any prerequisites (does the person need to exist? are skills only from review cycles?). Adequate but leaves 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only that it is a GET on /people/{personId}/tasks; it does not mention pagination flow, ordering, or result shape, so added behavioral value is modest.

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 the task kinds and tab options, followed by the endpoint path. No filler, though the raw path is of marginal use to an agent.

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 annotation coverage and a schema that handles paging, the description supplies enough to call it correctly. It stops short of describing ordering or what a task entry contains, which no output schema covers.

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%, so the schema already documents tab, page and limit including the DUE default. The description repeats the tab values without adding selection meaning, and says nothing about person_id beyond the endpoint template. 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 resource (tasks) plus the concrete task kinds it covers (forms, reviews, check-ins, onboarding steps) and the endpoint, which distinguishes it from siblings like intellihr_list_person_documents or intellihr_list_person_skills. It never explicitly contrasts with those siblings, but the resource 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 tab enumeration with the DUE default implies how to narrow the query, but there is no explicit guidance on when to choose this tool over related person-list tools or when a given tab applies. Usage is inferable rather than 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 safety is covered. The description adds only the endpoint (GET /position-titles); it does not state result-set shape, whether results are paginated (the schema hints at next_page), or ordering, so it adds little behavioral context beyond the annotations.

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

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

Three short sentences, front-loaded with what the tool returns, no filler. It is arguably under-specified rather than padded, so length is not the problem.

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 and no output schema, the description is minimally sufficient: an agent knows what it lists and how to filter. It stops short of describing the return fields or pagination expectations, which would be needed for confident multi-page retrieval.

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/limit and the substring semantics of name are already documented. "Filter by name" restates rather than extends the schema, giving no extra detail on matching behavior beyond what the property description 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 specific verb and resource: position titles defined in intelliHR, with a clarifying synonym ("job names") and the underlying endpoint. It is distinguishable from the sibling list_people/list_locations style tools, though the "job names" gloss risks blurring it with intellihr_list_jobs and intellihr_get_job, which are not addressed.

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 nothing about when to pick this over intellihr_list_jobs or intellihr_list_reference_data, nor any prerequisites. Usage is only implied by the verb "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, destructiveHint=false and openWorldHint=true, so the safety profile is carried by structured data. The description adds the domain meaning of records (status and dates attached to people), but says nothing about pagination behavior, result volume, or permissions despite the schema hinting at a next_page pattern.

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

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

Three short clauses, front-loaded with what the resource is, then filters, then endpoint. No filler sentences and 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?

For a five-parameter list tool with no output schema, the description covers purpose and filter intent but leaves out pagination guidance and what a qualification record contains beyond 'status and dates'. Adequate, not complete.

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

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

Schema coverage is 60%: page and limit are well documented, but employee_number and qualification_library_item_id have no schema descriptions. The description's 'filter by person, employee number or library item' does give semantic meaning to those two undocumented filters, but adds no format, multiplicity (single vs comma-separated) or matching-behavior detail.

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 (qualification records: licences, certificates) with the data it carries (status, dates) and the endpoint. The parenthetical examples implicitly separate it from siblings like intellihr_list_person_skills and intellihr_list_trainings, though it never names those alternatives 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?

'Filter by person, employee number or library item' gives implied usage context, but there is no when-to-use/when-not-to-use framing and no pointer to a sibling for related data (e.g. person skills vs qualifications).

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 that results are reference entities carrying ids and names. It does not state result volume or that paging must be followed via next_page, which the schema handles for page/limit but not for the overall retrieval loop.

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 verb and the resource, and the purpose sentence follows immediately. The 15-item enumeration is long and duplicates the schema enum, but it doubles as the primary selection aid, so the cost is largely justified.

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 single-enum lookup with no output schema, the description covers what the tool returns (ids and names) and why an agent would call it. Missing only the pagination contract and any note on how these lists relate to the entity-specific list siblings.

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

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

The description re-enumerates the kind values already present in the schema enum, adding little beyond confirming they are reference-list names. page and limit semantics live entirely in the schema (67% coverage), and the description adds no guidance on how these lists are typically sized or paged.

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 ('Look up') plus resource ('intelliHR's reference lists') with a full enumeration of the kinds available, which lets an agent recognize it as the generic reference-data lookup. It does not disambiguate from conceptually overlapping siblings such as intellihr_list_skills, intellihr_list_qualifications or intellihr_list_position_titles, so a 4 rather than 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?

'Use it to find the ids and names other tools need' gives a clear, concrete usage context: resolve identifiers before calling create/update tools. There is no when-not guidance and no pointer for choosing between this tool and the entity-specific list siblings that may return the same data.

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 fully covered upstream. The description adds only the endpoint path and no behavioral detail such as result ordering, whether all skills are returned by default, or the cost of a broad unfiltered call.

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?

Extremely short with zero filler and the resource stated first. It is a sentence fragment rather than a complete clause ('The skills catalogue...'), which slightly weakens the lead but wastes no 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?

A simple, fully-documented, read-only list tool needs less prose, and the schema carries pagination and filter semantics well. Still missing is any statement of default behavior (all skills vs. filtered) and the catalogue-vs-person-skills distinction, which an agent needs in this 22-tool sibling set.

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%, including the useful pointer to list_reference_data kind skill_disciplines for obtaining discipline_id. The description's mention of business-critical and discipline filters is consistent with the schema but adds no meaning 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?

The phrase 'The skills catalogue' with the two optional filters identifies the resource and its scope, and 'GET /skills' pins the endpoint. It never distinguishes itself from the sibling intellihr_list_person_skills, which is the most likely confusion an agent will have (catalogue vs. an individual's skills).

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?

'Optionally only business-critical skills or one discipline' restates the schema parameters rather than stating when to use this tool. There is no guidance on how it differs from list_person_skills or list_reference_data, so the agent must infer the routing decision.

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 by disclosing that both completed and booked trainings are returned and by naming the underlying endpoint, but it does not say whether unfiltered calls return the whole tenant or how large result sets behave.

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 plus an endpoint reference, front-loaded with what the resource is before listing filters. Every clause carries information an agent would otherwise have to infer.

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 8 optional params, no output schema and no nesting, the description supplies the filter vocabulary and the record semantics that the schema leaves out. It stops short of describing the shape of a returned training record or default sort, which matters slightly given there is 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 only 63%, with type_name, provider_name and employee_number undocumented in the schema; the description compensates by enumerating exactly those filter dimensions in plain language. It omits any hint about newest_first or the page/limit conventions, but those are covered by schema descriptions.

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

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

States a specific resource (training records) and scope (completed or booked by people) plus the fields returned (provider, type, dates). It is clearly a list operation, distinguishable from siblings like list_qualifications or list_skills by name and subject, though it never explicitly contrasts 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?

The sentence 'Filter by training name, provider, type, employee number or email' implies the practical usage contexts, but there is no explicit when-to-use vs when-not, no mention of what happens if no filters are supplied, and no named alternative tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the endpoint and the shape of the returned objects, but says nothing about page-size ceilings, result ordering, or how next_page tokenization behaves beyond what the schema's next_page hint already implies.

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 the resource first and the endpoint last; nothing is wasted. It is arguably a touch terse for an agent that must pick between it and list_people, but structurally sound.

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, so enumerating the returned fields is the right compensating move, and pagination semantics are fully handled by the schema. The only real gap is the missing disambiguation from intellihr_list_people.

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, limit) carry full descriptions including defaults and the 'pass the previous reply's next_page' instruction. The description adds no parameter meaning of its own, 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 the concrete resource ('user accounts that can sign in to intelliHR') and enumerates the returned fields (username, enabled flag, permission groups, linked person), plus the underlying endpoint GET /users. It implicitly separates itself from intellihr_list_people by scoping to sign-in accounts, but never says so outright.

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 'accounts that can sign in' framing implies the use case (auth/permission administration), but there is no explicit when-to-use or when-not-to-use statement, and no pointer to intellihr_list_people for the human-record case, which is the most likely sibling confusion.

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 that this is a destructive, idempotent, open-world write. The description adds important behavior beyond annotations: it is a PATCH-style partial update where only supplied fields change, and it lists fields this tool does not touch. It does not explain overwrite semantics for the nested emergency_contact object or auth/error behavior, but the core mutation behavior is disclosed.

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 two compact sentences with the write intent, field scope, exclusions, and endpoint all front-loaded. Every sentence adds useful information without repetition.

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 destructive write with no output schema, the description covers the essential scope: it identifies the updatable fields, partial-update behavior, and excluded areas. It could be more complete by explaining emergency-contact replacement semantics and what the response contains, but 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 only 30%, so the description must compensate. It does list the main updatable fields—names, date of birth, gender, employee number, title, and emergency contact—and clarifies that only passed fields change, but it does not add detail for enum values, date format, or emergency-contact subfields beyond what the schema itself 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 verb and resource: 'WRITE: change fields on an existing person,' then enumerates the updatable fields and explicitly excludes contact details, addresses, and jobs. This clearly distinguishes it from create/get/list sibling tools and even names the underlying endpoint.

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 defines when to use the tool—updating the listed fields on an existing person—and when not to use it by excluding contact details, addresses, and jobs. It does not name the sibling tools to use for those excluded operations, so it stops short of full alternative routing.

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