CharlieHR MCP by usefulapi

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

Annotations already declare this as a non-readonly, destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by stating that the note is created immediately and becomes visible according to the note type's permissions. It does not explicitly reconcile the destructiveHint or explain duplicate behavior on 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?

The description is compact and front-loaded with the WRITE marker and the core action. Every sentence contributes either the action, the visibility effect, the prerequisite lookup, or the endpoint, with no wasted text.

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 three-parameter write tool with no output schema but rich annotations, the description covers what the tool does, the immediate effect, visibility constraints, and where to get the required note type id. It is complete enough to call correctly, though it could say more about duplicate creation or the destructive-hint implication.

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 already 100%, so the baseline is 3. The description still adds meaning by explaining that the note type id should come from charliehr_list_team_member_note_types and by giving an example of a note value such as an employee number.

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

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

The description gives a specific verb and resource: add a custom note value for one note type to a team member in Charlie. It names the relevant object and distinguishes this write operation from the sibling read/list tools such as charliehr_list_team_member_notes and charliehr_list_team_member_note_types.

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 directs the agent to use charliehr_list_team_member_note_types to obtain the required note type id, which is useful prerequisite guidance. However, it does not explicitly state when not to use this tool or compare it against a sibling alternative for reading or managing existing notes.

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 safety is covered. The description adds the useful scoping fact that the record is determined by the API key rather than by any parameter, but says nothing about error behavior when the key is unscoped or about response shape beyond the field list.

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

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

Two short sentences, front-loaded with what is returned. The trailing 'GET /company' restates the tool name and adds little beyond HTTP semantics, but it costs almost nothing.

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

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

No output schema exists, so the description must carry the return contract, and it does by listing the four fields. For a parameterless singleton read this is close to sufficient; only edge cases like authentication failure or absent company are unmentioned.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description usefully clarifies that the company is derived from the API key, explaining why no identifier parameter exists.

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 specific resource (the company tied to the API keys) and enumerates the returned fields (id, name, subdomain, logo), which distinguishes it from the many team/office/leave siblings. The verb is implicit rather than stated, but the intent 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?

States which company is returned ('the API keys belong to') but gives no guidance on when to call this versus any sibling, no prerequisites, and no exclusions. An agent must infer that this is the only company-level 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. The description adds the HTTP endpoint and single-record scope, but does not disclose error behavior (e.g., what happens for a missing id) or permission requirements.

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

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

The description is two short, front-loaded fragments with no wasted words. The endpoint path is somewhat redundant with the tool name but still useful for mapping to API documentation.

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 get-by-id tool with rich annotations and a fully described parameter, the description covers the core action. However, with no output schema, it could say more about the returned leave request fields or error cases, which would help an agent interpret results.

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

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

Schema coverage is 100%, so the single parameter is fully documented in the schema with an example format. The description adds no parameter-level detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

The description states a specific retrieval: 'One leave request by id,' which clearly identifies the resource and scope. It implicitly distinguishes from list siblings by emphasizing a single record by id, though it does not name 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?

Usage is implied by 'by id' – the agent can infer this is for fetching a known leave request. However, there is no explicit guidance on when to use this versus list_leave_requests or how to obtain an id, leaving alternatives unaddressed.

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 REST endpoint mapping (GET /leave_types/{id}) and no extra behavior such as error handling for unknown ids or what fields are returned.

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 fragments with no wasted words, but the second ('GET /leave_types/{id}') largely restates the first, so the content is minimal rather than efficiently packed with useful 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-by-id tool with a fully documented single parameter and clear read-only annotations, the definition is minimally sufficient. Without an output schema, however, it could have said what a leave type record contains to help the agent interpret results.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Charlie leave type id, e.g. leave_type_XXX.' The description's 'by id' 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 with scope: 'One leave type by id', which implicitly contrasts with the singular/plural pattern of the sibling list_leave_types. It distinguishes itself from the list operation but does not name any 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?

There is no guidance on when to use this versus charliehr_list_leave_types or other get_* tools. The only hint is 'by id', leaving the agent to infer that this requires a known leave_type_id.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond the raw HTTP path — no note on what happens with an unknown id (null vs error), no visibility/permission scope, no rate-limit context.

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

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

Two telegraphic fragments, front-loaded and free of padding. It is efficient but so clipped that it reads like an internal endpoint note rather than agent-facing guidance.

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

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

A single-parameter read tool is inherently simple, and the parameter is fully documented. However, with no output schema the description should have said what the response contains (office fields, or behavior on a missing id) — that gap is real but modest for such a simple lookup.

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

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

Schema description coverage is 100% and the office_id property already documents the office_XXXX format and points to charliehr_list_offices. The description adds no further 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?

"One office by id" names a specific verb (get) and singular resource, and the endpoint GET /offices/{id} reinforces a direct single-record lookup. It implicitly contrasts with the sibling list_offices but never names it, so the differentiation is only inferable.

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 alternatives, no mention of charliehr_list_offices, and no prerequisites or error conditions. The only usage signal is the word "id," which just restates the required parameter.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description contributes beyond that by disclosing what comes back — the team record plus its member ids — which is the most useful behavioral detail for a read tool with no output schema. It stops short of noting pagination, auth, or errors, which are not especially relevant here.

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 fragments: return contents first, endpoint second. Zero filler and fully front-loaded.

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

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

One required param, no output schema, so the description must carry the return shape — it does so for the member-ids aspect, which is the non-obvious part. It does not enumerate the team's own fields (name, office, etc.), a minor gap for a tool with 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 the single team_id parameter already documents format (team_XXXX), length bounds, and where to get ids. The description only repeats 'by id', adding no syntax or edge-case 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?

States a specific resource (one team), the lookup key (by id), and the payload shape (ids of its team members), plus the underlying endpoint GET /teams/{id}. It implicitly contrasts with charliehr_list_teams but never names that sibling, so differentiation is left partly 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?

'One team by id' implies the retrieval case, and the schema param description routes the agent to charliehr_list_teams to obtain ids. However, the description itself gives no explicit when-to-use/when-not or alternative (e.g., list_teams vs get_team_member), leaving usage guidance only implied.

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

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

Annotations already cover safety (readOnly, non-destructive), and the description goes well beyond them: it enumerates which sensitive fields ARE returned (DOB, gender, marital status, personal email/phone, home address, notes) and explicitly lists fields that are never returned (National Insurance numbers, payroll id, starter declaration, student-loan flags). This is exactly the disclosure an agent needs before handling personal data.

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

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

Three compact sentences, front-loaded with the core action and scope, then field disclosure. The field enumeration is long but each clause carries real information; no filler or repetition of annotation data.

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

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

There is no output schema, so the description must convey what comes back — and it does in detail, including the inclusion/exclusion boundary for sensitive data. For a one-parameter read tool, nothing material an agent needs 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?

Single parameter with 100% schema description coverage, so the schema already defines the format (team_member_XXX) and points to the listing tool. The description adds no new syntax or constraint beyond restating 'by id', 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 ('One team member by id with the full profile') plus the underlying endpoint GET /team_members/{id}. It is clearly distinguishable from list-style siblings by the 'by id' scoping, though it never names charliehr_list_team_members as the alternative for browsing/searching.

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: fetch a single member when you already have the id (the schema even points to charliehr_list_team_members for obtaining it). There is no explicit when-to-use/when-not guidance or statement about what to do if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing what the response contains — allowance, used, remaining, in both days and hours, plus the period — which is genuinely useful given there is no output schema. It stops short of stating permission requirements or whether the figures are computed live.

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 that front-loads the resource and then enumerates the returned fields, with the endpoint path trailing as optional routing detail. No filler, though the raw 'GET /team_members/{id}/leave_allowance' string is of marginal value to an agent that already selects tools by 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 one-parameter read tool with full annotation coverage and no output schema, the description supplies the key missing piece: what the response measures. An agent can call this correctly with the given information; only the absence of any guidance about the related bulk/adjustment tools keeps it from being fully complete.

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

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

Schema description coverage is 100% for the single team_member_id parameter, so the schema fully documents it. The description's phrase 'one team member' merely restates the parameter's cardinality without adding format, source, or lookup semantics beyond the schema's 'Charlie team member id.' 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 + resource: retrieves the 'current holiday allowance of one team member' and even enumerates the constituent figures (allowance, used, remaining, in days and hours). The singular scope implicitly distinguishes it from the plural sibling list_leave_allowances, though that 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?

Usage is only implied: 'current' signals a point-in-time snapshot (no history) and 'one team member' signals a per-member lookup versus the bulk list_leave_allowances. There is no explicit when-to-use statement, no mention of alternatives such as list_allowance_adjustments for adjustment history, and no 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, openWorldHint=true, and destructiveHint=false, and the description does not contradict them. But beyond stating the GET path, it adds no behavioral context such as auth requirements, error behavior, or what happens for invalid ids.

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 front-loaded and very short, with no wasted prose. The GET path is somewhat redundant but still compact and readable.

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 one-parameter read tool, the description is minimally sufficient, and annotations cover safety. However, with no output schema, it does not explain what is returned or any notable retrieval behavior.

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

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

The schema has 100% description coverage and documents the single required parameter with an example format. The description only restates 'by id' and adds no further 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 identifies a specific resource ('note type') and scope ('by id'), which distinguishes it from the sibling list tool 'charliehr_list_team_member_note_types'. It does not explicitly name alternatives, but the single-resource retrieval is clear.

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

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

Usage is implied: fetch one note type when the id is known. However, there is no explicit guidance on when to use this versus the list endpoint or what prerequisites are required.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's added value is the resolution semantics: custom overrides take precedence over the default assignment, and the date defaults to today. That resolution rule is genuinely useful behavioral context an agent could not infer from 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?

Three compact clauses, front-loaded with the resource and resolution rule, then the default, then the endpoint. No filler sentences.

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 two-parameter read tool with full schema coverage and clear annotations, the definition covers what the agent needs to call it correctly, including the precedence rule. The only gap is what comes back (no output schema, and the description does not characterize the returned location value), which is a minor omission.

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 are documented in-schema (including 'default today' for date). The description's 'Defaults to today' merely repeats the schema, adding no new meaning; baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb+resource: retrieves where one team member works on a given date, plus the underlying endpoint GET /team_members/{id}/working_location. The 'one team member' scoping implicitly separates it from charliehr_list_working_locations, but no sibling is named explicitly, so it falls short of full differentiation.

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

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

Usage is implied by the phrasing (single member, single date, defaults to today), and the override rule hints at why one would call this rather than reading a raw assignment. However, there is no explicit when-to-use or when-not-to-use guidance and no named alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: it enumerates return contents (full_day/morning/afternoon, weekly hours, from/to dates, company defaults and custom overrides) and states the response is not paginated. It omits auth/error behavior, so it is not a 5.

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

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

A single dense sentence conveys scope, return fields, defaults/overrides, pagination status, and endpoint with no filler. The information is front-loaded around the resource and return shape.

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

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

For a single-parameter read tool with annotations covering safety and no output schema, the description supplies the important missing context: what the returned working-week segments contain, that company defaults and overrides are included, and that the response is not paginated. Nothing material for correct invocation is absent.

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?

There is only one parameter, team_member_id, and schema description coverage is 100%, so the schema already defines it as a Charlie team member id. The description adds 'one team member' but no extra format, constraints, or lookup guidance beyond the schema, so the baseline 3 applies.

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

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

The description precisely identifies the resource: working-week segments for one team member, including day-level full/half-day flags, weekly hours, from/to dates, company defaults, and custom overrides. It is clearly distinct from sibling retrieval tools such as get_team_member or get_team_member_working_location, though it does not explicitly name those alternatives.

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 by the resource name and endpoint; there is no explicit when-to-use, when-not-to-use, or named alternative guidance. 'Not paginated' is a useful operational note but does not help choose among sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is carried. The description adds genuinely new information by enumerating the record fields returned (description, days/hours, carryover flag, creator, period), which matters because no output schema exists.

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 scope and returned fields, plus a terse endpoint for reference. Nothing is wasted, though the raw GET path adds marginal value for an agent that already has the 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?

With no output schema, the field enumeration substitutes well for a return description, and pagination is covered by the schema. It stops short of stating ordering or default behavior of the list, but nothing essential to calling 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 the baseline is 3: page, per_page and team_member_id are all documented in the schema, including pagination semantics. The description adds only the team-member scoping framing, not new parameter 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?

Specific verb+resource: lists all holiday allowance adjustments for a single team member across every leave period, with the endpoint given. The per-team-member scope implicitly separates it from charliehr_list_leave_allowances and charliehr_get_team_member_leave_allowance, though those siblings are not 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?

The scoping ('of one team member across every leave period') implies when this is the right call, but there is no explicit when-to-use/when-not or named alternative. An agent must infer that the company-wide list tools are the alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds value beyond that by listing the record fields returned (name, start/end date, duration, deductible) and the endpoint, which matters since there is no output schema. 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 short sentences plus the endpoint, front-loaded with the returned fields and then the optional filter. Little waste, though the trailing 'GET /company_holidays' adds marginal value for 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?

A read-only, all-optional-parameter list tool with no output schema: the description fills the main gap by enumerating return fields, and the schema carries the parameter and pagination details. Nothing critical 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 coverage is 100% – page, per_page, start_date and end_date are all fully documented, including the paired start/end constraint. The description only restates the date-window filter, adding no syntax or semantics 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?

Specific verb+resource ('The company's holidays') with the returned fields enumerated and the optional date-window scoping stated. It does not explicitly distinguish itself from nearby list tools like charliehr_list_restricted_dates, but the resource is unambiguous enough that an agent can identify it.

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 those in a date window' implies a filtering use case, but there is no explicit when-to-use guidance, no statement of when-not to use it, and no named alternative (e.g., restricted dates). Usage is only inferable.

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 the read-only, non-destructive, open-world profile. The description adds useful behavioral context by specifying the returned allowance, used and remaining values, days/hours units, and leave period, though it omits pagination/return-envelope details.

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

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

The description is compact and front-loaded: it states the resource, scope, returned fields, and endpoint in one efficient sentence. There is no redundant or filler language.

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 pagination parameters and clarifying annotations, the description gives enough detail about what is returned. It could be more complete by mentioning pagination/next_page behavior or explicitly steering agents away from similar sibling tools.

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

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

Schema description coverage is 100%, and the page/per_page parameters are fully documented in the schema. The description adds no extra meaning about how pagination or defaults work, so the baseline of 3 is appropriate.

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

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

The description clearly states that this lists current holiday allowances for every team member, including the specific returned fields and leave period. The scope 'every team member' helps distinguish it from single-member siblings, but it does not explicitly contrast related alternatives such as non-holiday allowances.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no routing toward alternatives like charliehr_get_team_member_leave_allowance or charliehr_list_non_holiday_leave_allowances. Bulk usage is only implied by the phrase 'every team member'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the field inventory an agent can expect back, but says nothing about pagination limits or result volume beyond what the schema already encodes.

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, zero filler: scope and returned fields first, the optional filter second, and the HTTP route as a trailing identifier. Nothing is repeated from the schema.

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

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

With no output schema, the inline field list (id, team member, approver, status, type, dates, amount, duration, details) usefully compensates. Pagination and date-pairing rules live in the schema and safety hints in annotations, so the definition is nearly complete; only the sibling disambiguation 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, start_date and end_date are already fully documented, including the overlap semantics and the pairing constraint. The description's lone mention of a "date window" adds nothing beyond that; 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 leave requests") plus the scope ("of the whole company") and enumerates the returned fields. The company-wide scope implicitly distinguishes it from charliehr_list_team_member_leave_requests, but the sibling is never named, so an agent must infer the split.

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 those in a date window" signals the one filtering use case, but there is no explicit statement of when to prefer this over charliehr_list_team_member_leave_requests or charliehr_get_leave_request. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs added context. It supplies that by disclosing the 'enabled' filter (disabled types are excluded) and the shape of each returned record (id, name, deductible, default, auto-approved, sensitive).

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 tight fragment-pair with the resource and field list front-loaded and no filler. The telegraphic style borders on under-specification but every element 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 simple paginated read with no output schema, the description covers scope and return fields while the schema covers pagination. Only the relationship to charliehr_get_leave_type remains unaddressed.

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

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

Schema description coverage is 100%, with page and per_page fully documented in the schema, including the next_page chaining hint. The description adds nothing about parameters, 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 the resource (leave types), the scope filter ('enabled'), and the returned fields, plus the underlying endpoint. It does not explicitly distinguish itself from the sibling charliehr_get_leave_type, but the plural/list framing makes the split inferable.

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

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

Usage is only implied: fetch leave types when you need the enabled set. There is no explicit statement of when to use this versus charliehr_get_leave_type for a single type, and no prerequisites or exclusions mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned content ('days taken and limit') and the GET endpoint, but it does not disclose auth requirements, pagination, or other behavioral constraints beyond what the annotations provide.

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 sentences with no wasted wording. The key scope and return content are front-loaded before the endpoint reference.

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 one-parameter read-only listing tool with no output schema, the description sufficiently explains what is returned and includes the endpoint. A minor gap is that it does not clarify how this relates to the other leave allowance tools, but the core invocation context 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%, and the single team_member_id parameter is fully documented in the schema. The description reinforces that the operation applies to one team member, but it adds no extra meaning about the parameter's format or constraints beyond the schema.

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

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

The description clearly identifies the resource and scope: days taken and limits for non-holiday leave types of one team member. It is specific enough to distinguish this from generic leave-listing tools, but it does not explicitly name or contrast with the closest sibling, charliehr_get_team_member_leave_allowance.

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 implies the tool is for listing one team member's non-holiday leave allowances, but it gives no explicit when-to-use guidance, no exclusions, and no alternatives such as charliehr_get_team_member_leave_allowance or charliehr_list_leave_allowances.

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 value beyond that by enumerating the response fields (id, name, head-office flag, address, timezone, phone, email), which matters because no output schema exists. It says nothing about pagination behavior or total counts, but the schema covers paging.

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

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

A single sentence plus the endpoint, with the payload description front-loaded and zero filler. Every clause earns its place.

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

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

For a simple read-only list tool with a fully documented two-parameter schema, the description supplies the one thing structured fields don't: the shape of each returned office record. Only the missing contrast with get_office keeps it from being fully complete.

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

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

Schema description coverage is 100%: page and per_page are fully documented in the schema, including defaults and the 'pass the previous reply's next_page' convention. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the company's offices') and enumerates the fields returned, so the agent knows exactly what this tool yields. It does not explicitly contrast itself with the sibling get_office tool, leaving that differentiation to the name alone.

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: 'List' plus 'GET /offices' signals a collection read, and the presence of a get_office sibling makes the list-vs-single split inferable. There is no explicit statement of when to prefer this over get_office or list_working_locations, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned field set and the optional windowing behavior, but says nothing about result volume, pagination expectations, or whether an empty list is possible.

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 naming the resource and its fields, followed by the optional filter and the endpoint. Nothing is wasted, though the parenthetical example is the only thing that would be lost if trimmed.

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 notes the optional windowing, while all four parameters are fully self-documented in the schema. For a simple read-only list endpoint this is close to sufficient; only the distinction from other leave-listing tools is missing.

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

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

Schema coverage is 100%: page, per_page, start_date and end_date are all documented including the paired-usage constraint. The description only restates the optional date-window filter, adding no syntax or behavior 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?

The description names the specific resource (restricted leave dates), gives a concrete example ('year-end freeze'), and enumerates the returned fields (name, start/end date, duration). The list verb is carried by the title rather than the description text, but the resource is unambiguous against siblings like list_company_holidays.

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 states that results can optionally be narrowed to a date window, but gives no guidance on when an agent should use this instead of charliehr_list_company_holidays or charliehr_list_leave_types, nor any prerequisites. Usage is only implied by the resource 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?

Goes well beyond the annotations (which only declare read-only, non-destructive, open-world) by flagging the data as SENSITIVE, naming the required API key scope, and enumerating the returned fields. It stops short of describing pagination behavior or how much data a call returns.

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

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

One sentence that front-loads the most decision-relevant fact (SENSITIVE), then scope, prerequisites, and endpoint. No filler.

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

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

With no output schema, listing the returned fields is exactly the right compensation, and the auth requirement is disclosed. Only the pagination/return-volume story is missing, and that is partly covered by the schema.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are fully documented in the schema, including the next_page chaining hint. The description adds no parameter meaning of its own, 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 (salary records) with explicit scope: all team members. The phrase 'of all team members' implicitly separates it from the sibling charliehr_list_team_member_salaries, though that contrast is never made explicit.

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

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

Usage is implied by the resource name and the prerequisite 'Needs API keys with access to salary data' is stated, but there is no guidance on when to prefer this over charliehr_list_team_member_salaries or any other sibling, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds only the optional date-window behavior and the HTTP path; it says nothing about pagination semantics, result ordering, or what an empty window returns.

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

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

Two compact sentences with the scope stated first and the endpoint path last as supporting detail. No filler or redundancy.

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

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

For a read-only, single-entity list operation with complete parameter documentation and annotations covering safety, the description is nearly sufficient. The only gap is that it does not indicate whether results are sorted or what paging shape to expect, which matters slightly since 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%, so page/per_page/start_date/end_date semantics and the start/end pairing rule are already fully documented in the schema. The description restates the optional date window but adds no format, default, or ordering detail beyond it.

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

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

States a specific verb+resource ('The leave requests of one team member') and adds the optional date-window scope plus the underlying endpoint. The phrase 'of one team member' implicitly separates it from the company-wide charliehr_list_leave_requests, but it 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?

Usage is only implied: the scoping to a single team member hints that the broader list tool is for cross-company queries, but there is no stated when-to-use/when-not rule or named alternative. An agent must infer the routing from the resource wording 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 and destructiveHint=false, so the safety profile is known. The description adds genuinely new behavioral context: the redaction rule for National Insurance numbers and NI-looking text, which the agent would otherwise have no way to anticipate. It does not describe pagination, but that is covered 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?

One compact sentence plus the endpoint, with the return payload (label and content) front-loaded ahead of the redaction caveat. Nothing is wasted, though the parenthetical redaction clause makes the sentence slightly dense.

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 with full schema coverage and no output schema, the description covers scope, payload shape, and the one surprising behavior (redaction). Return structure details are partially covered by naming label/content; nothing critical 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 team_member_id are already documented. The description only reinforces the single-team-member targeting and adds no format or syntax detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (custom notes with label and content) scoped to one team member, plus the concrete endpoint. It is clearly distinguishable from create_team_member_note and list_team_member_note_types, which concern writing notes and fetching note types respectively.

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 name and by the single-team-member scope, but the description never says when to use this versus list_team_member_note_types or when notes should be read at all. No explicit exclusions or alternatives 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?

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful content detail by noting that visibility permissions are included and gives the underlying endpoint, but it does not describe pagination behavior, response shape, or any auth/rate-limit considerations.

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 very short and front-loads the resource description with helpful examples. The trailing 'GET /team_member_note_types' is largely redundant with the tool name and annotations, but the overall text is efficient and not 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 paginated list tool with no output schema and fully documented parameters, the description gives enough to understand what is returned: custom note types plus visibility permissions. It could optionally mention pagination or response ordering, but the essential context 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?

Both parameters are fully documented in the schema (100% coverage), including defaults and ranges for page and per_page. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate when the schema carries the full burden.

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

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

The description clearly identifies the resource (custom note types) and what is returned alongside them (visibility permissions), with concrete examples like Employee No. and Laptop Serial Number. It distinguishes itself from the singular get_team_member_note_type and from list_team_member_notes by focusing on types rather than note records, though it never explicitly says 'list' or names a sibling.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as get_team_member_note_type or list_team_member_notes. The agent can infer that it retrieves note type definitions, but no conditions, prerequisites, or exclusions 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?

Goes well past the annotations (readOnly, non-destructive, open-world) by disclosing which sensitive PII is exposed — date_of_birth, gender, married status, personal email, phone, home address — and which fields are never returned (National Insurance numbers, payroll id, starter declaration, student-loan flags). That privacy profile is exactly the kind of behavioral context annotations cannot express and directly affects how an agent should handle the output.

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

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

Two dense sentences plus the endpoint: purpose first, then the field inventory including the sensitive and excluded sets. Every clause carries information an agent would otherwise have to infer, and nothing is repeated from the schema 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?

With no output schema, the description carries the full burden of describing the return value, and it does so field by field, including negative space (never-returned fields). Pagination is covered by the schema, so nothing material is missing for a safe, correct call.

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%: page and per_page are fully documented in the schema, including the 1-25 cap and the "pass the previous reply's next_page" instruction. The description adds no further parameter meaning, so the baseline of 3 applies. It also does not warn that a whole-company listing may require many pages at 25 per page.

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 company's team members (employees)") and then enumerates exactly which fields come back, so an agent knows precisely what the payload contains. The plural list framing plus the explicit field inventory distinguishes it from the singular charliehr_get_team_member sibling without needing to open 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?

Usage is implied by the field inventory and the endpoint, but there is no explicit guidance on when to prefer this over charliehr_get_team_member for a single employee, or over charliehr_list_team_member_salaries / charliehr_list_team_member_leave_requests for related data. No exclusions or prerequisites are stated beyond the never-returned field 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 establish readOnlyHint=true and destructiveHint=false, so the description's added value is the 'SENSITIVE' marker flagging that this exposes compensation data, plus the underlying endpoint path for traceability. That is meaningful context beyond the annotations, though it says nothing about pagination defaults or permission requirements.

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

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

Two short sentences, no waste, and the most consequential information (SENSITIVE) is front-loaded before the resource description and endpoint. Everything present earns its place.

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

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

With no output schema, the description compensates by enumerating the salient returned fields, and pagination is fully covered in the schema. It is complete enough to call correctly, with only minor gaps around permissions and result ordering.

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 all three parameters are documented in-schema, including the next_page pagination pattern. The description adds no parameter-level 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?

The description names a specific verb-resource pair (salary history) scoped to 'one team member' and enumerates the returned fields (job title, pay rate, currency, effective date), so an agent can distinguish it from the company-wide list_salaries sibling. It stops short of naming 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?

Usage is only implied: 'one team member' signals single-member lookup vs. the company-wide list_salaries, but there is no explicit when-to-use, when-not, or named alternative. The SENSITIVE flag hints at caution without spelling out any usage condition.

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 one useful behavioral fact — that each team carries its member ids — but does not mention pagination behavior, result volume, or 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?

Two short sentences with no filler: the purpose and the response payload are front-loaded, and the endpoint is a compact trailing 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?

With no output schema, the description does the minimum needed by naming the payload (teams with member ids), and pagination is fully handled by the schema. It stops short of describing other team fields an agent might receive, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with both page and per_page fully documented including defaults, bounds, and the next_page chaining hint. 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+resource ("List the company's teams") and adds the returned content (team member ids) plus the underlying endpoint. It's clear enough to distinguish from charliehr_get_team (single team), though it never explicitly contrasts with charliehr_list_team_members.

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

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

There is no explicit when-to-use, prerequisite, or alternative-routing guidance. The mention of member ids implicitly signals the use case, but nothing tells an agent to prefer charliehr_get_team for a single team or charliehr_list_team_members for members only.

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 read-only, non-destructive and open-world, so safety is covered; the description's real contribution is disclosing that the same call returns two structurally different results (catalog vs. per-member resolution) depending on the date argument, which is not visible from annotations and would otherwise surprise an agent. It does not mention pagination limits or auth/scope requirements, but those are largely covered by the schema and annotations.

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

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

Two front-loaded sentences plus the endpoint path, with zero filler. The alternate-mode behavior is stated immediately after the default behavior, matching the order in which an agent reasons about the call.

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

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

For a zero-required-parameter, three-param read tool with no output schema, the definition covers both result shapes conceptually and points at the endpoint. It could say marginally more about what a location record contains, but nothing needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so page and per_page semantics are already fully documented in the schema; the description only reinforces the date parameter's mode-switching effect, adding the qualifier 'active team member' and the notion of a resolved location. Baseline 3 applies because the schema carries the parameter burden.

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

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

States a specific verb and resource ('List the active working locations (the catalog)') and clarifies that the tool has two modes depending on whether a date is supplied. This is clear enough to act on, though it never names the closest sibling (get_team_member_working_location) or list_offices to mark the boundary between catalog-level and per-member data.

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

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

'With a date, instead returns where each active team member works on that date' gives a concrete rule for selecting between the tool's two behaviors, which is the main usage decision an agent faces. It stops short of saying when to prefer this tool over the sibling get_team_member_working_location for a single person, so there is no explicit exclusion.

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