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

The readOnlyHint annotation already communicates that this is a safe read operation, and the description aligns with that by saying 'Search.' It adds the small detail that it targets Fusion planBalances, but it does not disclose what happens when no filters are provided, whether personNumber or finder is required, or how limit affects pagination.

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

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

The description is a single sentence with no filler and the core action is front-loaded. However, it is so terse that it veers toward under-specification, offering little more than the tool name already implies.

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 search tool with four unannotated parameters and no output schema, the description is not complete enough for an agent to call it correctly. It leaves unanswered how to filter, what the response contains, and which parameters are actually needed.

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% and the description provides no meaning for q, limit, finder, or personNumber. With four undocumented parameters, the description was obligated to compensate but instead says nothing about how to construct a valid search or how the parameters relate.

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 action ('Search') and a resource ('absence plan balances'), and identifies the underlying Fusion planBalances source. It is not a tautology and an agent can tell the general operation, but it does not explicitly distinguish this from siblings like hcm_get_plan_balance or hcm_get_absence_type_balance.

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

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

There is no guidance on when to use this tool versus alternatives such as hcm_get_plan_balance or hcm_search_absence_plans. No prerequisites, filters, or exclusion criteria are mentioned, so the agent must infer usage 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 only declare readOnlyHint=false, so the description adds value by noting that allocation defaults to an approval flow and only becomes a direct write with --write. However, it does not explain how --write is expressed in the JSON request, what happens to existing checklist state, or what permissions are required.

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

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

The description is a single compact sentence with the core action front-loaded and no filler. The parenthetical is slightly cryptic but does not add unnecessary length.

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

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

With a nested body schema, additionalProperties allowed, no output schema, and minimal annotations, the agent is left without the payload requirements, approval/write signaling details, or expected response behavior. The description covers the basic intent but not enough to reliably invoke the tool correctly.

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

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

The input schema already describes body as 'Allocate payload (PersonNumber, ChecklistName, …)' with 100% coverage, and the description adds no further detail about required fields, value formats, or how to signal the write vs. approval mode. This meets the baseline but does not improve parameter understanding.

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?

Description states a specific verb ('Allocate'), a resource ('a checklist'), and a recipient ('to a person'), making the tool's function immediately clear. It is distinct from sibling tools like hcm_get_checklist, hcm_update_task_status, and hcm_force_close_checklist.

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 is given on when to use this tool versus related checklist tools, nor are prerequisites or alternatives mentioned. The parenthetical 'approval unless --write' describes a mode of operation, not a selection criterion.

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

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

Annotations only provide readOnlyHint=false, which already signals this is a write operation. The description adds that it 'executes' the write, implying the write is actually performed upon approval, which is useful. However, it doesn't disclose side effects, reversibility, or whether approval is final. No contradiction with 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?

A single, front-loaded sentence with no filler. Every word earns its place: verb, action, resource, and parameter are all present.

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 tool with no output schema, the description is mostly adequate. It tells the agent what to do and with what. However, it doesn't explain what the response looks like, whether the approval can be undone, or how to obtain approval_id (e.g., via hcm_list_pending_approvals). These are gaps, but the tool is simple enough that the description is minimally viable.

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 compensate. It mentions 'by approval_id' and the schema defines approval_id as a required string. The description adds minimal meaning beyond the schema—it tells you the parameter identifies the pending write to approve, but doesn't explain where to find it or its format. 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?

The description states a specific verb ('Approve and execute') and a specific resource ('a pending write by approval_id'). It clearly distinguishes this from sibling tools like hcm_deny_write and hcm_list_pending_approvals, though it doesn't explicitly name them.

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

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

The description implies usage: call this when you have an approval_id for a pending write and want to approve it. It doesn't explicitly state when not to use it or mention alternatives like hcm_deny_write, but the verb 'approve' and the sibling context make the intended use reasonably clear.

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

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

Beyond the readOnlyHint=false annotation, the description discloses that it persists a checkpoint to file store and that dryRun prevents advancement. This gives the agent meaningful insight into side effects, though it omits potential error or concurrency behavior.

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

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

The description is two tight sentences with no filler. Core behavior and the key side effect are front-loaded, making it 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?

For a mutating consume-style tool with no output schema and low parameter coverage, the description leaves gaps around cursor semantics, limit defaults, collection filtering, and when to prefer this over atom_poll. It captures the essence but not enough for confident 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 33% and the description adds no explanation for limit or collection. The mention of 'after cursor' references a concept not present in the parameters, and the effect of limit and collection scope remains undocumented.

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 action (consume/poll + advance checkpoint) and resource (Atom entries), which differentiates it from list/poll siblings. However, it does not explicitly name an alternative or define where the cursor comes from, leaving minor ambiguity.

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

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

The phrase 'poll + advance checkpoint' implies this tool is used when the caller wants to both read and persist progress, with dryRun as an opt-out. Yet there is no explicit when-to-use versus hcm_atom_poll or hcm_atom_get_checkpoint, nor any exclusion guidance.

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

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

The readOnlyHint annotation already declares this a safe read, and the description adds one genuinely useful behavioral detail beyond it: the operation reads a local store rather than a remote CDC source. It does not disclose what happens when no checkpoint exists, whether the local store is auto-initialized, or how checkpoints relate to consumed entries, but the annotation lowers the bar and the local-store context earns some credit.

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?

At eight words the description is tightly written and front-loads the verb and resource. However, the brevity comes at the expense of the parameter and usage context, so it reads as under-specification rather than effective conciseness — appropriate in size but incomplete in content.

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?

Despite the tool's low structural complexity (one optional parameter, no output schema), essential context is missing: the meaning of `collection`, the semantics of a CDC 'checkpoint,' and how this tool fits with hcm_atom_reset_checkpoint and the poll/consume flow. An agent without prior domain knowledge cannot reliably invoke it correctly from this definition alone.

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 sole parameter `collection` has zero schema description coverage (0%) and is never mentioned in the tool description, so nothing compensates for the schema's silence. The agent cannot determine whether `collection` is a feed name, a checkpoint key, or an optional filter, nor what omitting this non-required parameter yields. This is a blocking gap for correct invocation.

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 ('Get') and resource ('Atom CDC checkpoint(s)') with a location qualifier ('from local store'), so the core operation is understandable. However, the plural '(s)' and the unexpanded 'CDC' leave ambiguity about exactly what is returned, and it does not differentiate this read tool from its many atom siblings like hcm_atom_poll, hcm_atom_consume, or hcm_atom_reset_checkpoint.

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 is given on when to call this tool versus the closely related atom tools — hcm_atom_poll, hcm_atom_consume, hcm_atom_reset_checkpoint, hcm_list_atom_feeds — which the extensive sibling list makes highly relevant. There is no stated use case, prerequisite, or when-not-to-use advice, so an agent must infer the checkpoint's role in the CDC flow.

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?

With readOnlyHint=true already declaring the operation safe, the description adds meaningful behavioral detail beyond the annotation: it explicitly states that the cursor is not advanced and that polling is relative to a stored checkpoint. This addresses the most important behavioral concern for an agent choosing between poll and consume.

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

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

A single, front-loaded sentence that communicates the core behavior and the critical non-mutating guarantee. There is no filler or redundant restatement of 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?

The description conveys the essential polling semantics and the read-only nature, but with no output schema it does not describe the return format or content. Combined with the undocumented limit and collection parameters, the definition is adequate for a basic call but incomplete for confident autonomous 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 33%, with limit and collection left undescribed, and the description does not compensate for these gaps. The 'since' phrase mirrors the schema's own description rather than adding meaning. The agent is left guessing about limit semantics and what 'collection: all' refers to.

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 ('poll'), a precise resource ('Atom feed'), and the key mechanism ('after the stored checkpoint cursor or since'). It also explicitly distinguishes itself from sibling tools by noting it does not advance the cursor, making its purpose unmistakable.

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 clear context: this is a read-style polling operation that does not mutate cursor state. It does not explicitly name alternatives or state when-not-to-use, but the non-advancing-cursor behavior strongly implies the contrast with consuming tools like hcm_atom_consume, so the guidance is clear enough without being fully 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?

The description adds the constraint 'Local store only,' which clarifies that the reset does not affect remote sources—a useful behavioral detail beyond the readOnlyHint=false annotation. However, it does not disclose potential side effects, such as whether clearing the checkpoint causes reprocessing of all entries or if it is irreversible. Given the annotation only marks it as a write operation, the description adds some value but leaves out important consequences.

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 extremely concise—two short sentences with no filler. The action and scope are front-loaded, and every word earns its place. This is an example of efficient, high-density 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 tool with one optional parameter and no output schema, the description covers the basic mechanics (clears a checkpoint, local-only, optional scope). However, it omits any guidance on when to use it or what happens to in-flight consumers, which might be critical for an agent deciding whether to invoke this destructive operation. Given the low complexity, a score of 3 seems fair—adequate but with a noticeable gap.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that the 'collection' parameter is optional by saying '(or all)', implying that omitting it clears all checkpoints. However, it does not specify the expected format (e.g., name vs. ID) or how a single collection is identified. This is minimal but useful semantics.

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

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

The description clearly states the action ('Clear'), the resource ('Atom CDC checkpoint'), and the scope ('for a collection (or all)'). This is a specific and unambiguous verb-resource pairing that distinguishes it from sibling tools like hcm_atom_get_checkpoint (which retrieves) and hcm_atom_poll/consume (which process entries).

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 is provided on when to use this tool versus alternatives. It does not mention scenarios where resetting a checkpoint is appropriate, nor does it reference sibling tools like hcm_atom_get_checkpoint for comparison. The only contextual hint is 'Local store only,' which is behavioral rather than usage-oriented.

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 signal readOnlyHint=false, indicating this is a mutating operation. The description adds a dry-run preference and a cryptic '--write' flag, which hints at behavior but does not clearly explain the mutation's effect, reversibility, or the exact meaning of the flag.

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-loaded with the main action. The second sentence 'Prefer dry-run first' is useful, but the parenthetical 'approval unless --write' is ambiguous and would benefit from clearer phrasing.

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 and a mutating tool, the description omits important context: what the tool returns, how it reports successes/failures, and how it relates to the explicit hcm_bulk_bp_dry_run sibling. The dry-run guidance is not enough to fully understand invocation and expected 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 0% description coverage, so the description must compensate, but it provides no parameter details. The single parameter notificationIds is self-explanatory from its name, yet the description does not clarify whether these are BP notification IDs, whether array order matters, or what happens to invalid IDs.

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 action ('Bulk approve') and the resource ('BP notifications'), making the core purpose evident. It is distinguishable from sibling tools like hcm_bulk_deny_notifications by the word 'approve', but the phrase 'approval unless --write' is confusing and detracts from clarity.

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 instruction 'Prefer dry-run first' provides some usage guidance, implying a safe preliminary step before this approval tool. However, it never names the dry-run sibling tool (hcm_bulk_bp_dry_run) or explains when to choose this over hcm_perform_bp_action, hcm_approve_write, or hcm_bulk_deny_notifications.

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

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

The description explicitly discloses that no execution occurs and that planned actions are returned, which adds meaningful behavioral context beyond the readOnlyHint annotation. It does not detail the structure of the planned actions, but the core no-side-effect behavior is clearly communicated.

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 conveys the operation, target resource, and key behavioral promise without filler. Every part of the description 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?

The tool is simple and the schema covers the required parameters, but with no output schema the description only vaguely says 'planned actions' without indicating what the response looks like. It is adequate for making a basic call but leaves some uncertainty about the return format.

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 maps 'notification ids' to notificationIds and 'approve/deny' to action, but it omits the REJECT enum value and does not explain the distinction between REJECT and DENY. With 0% schema description coverage, more parameter clarification would be needed to fully compensate.

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 a dry-run bulk approve/deny operation on notification IDs and explicitly says it returns planned actions without executing. This differentiates it from executing siblings like hcm_bulk_approve_notifications and hcm_bulk_deny_notifications.

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 word 'dry-run' and 'without executing' imply a preview use case, but the description does not explicitly say when to use this tool versus the executing bulk-action siblings, nor does it name alternatives. Usage guidance is present only by implication.

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 only annotation is readOnlyHint: false, so the description carries the full burden of behavioral disclosure. It adds a hint about an approval-vs-write dual mode, but this is terse and ambiguous, and nothing explains side effects of a bulk deny, reversibility, or prerequisites. For a mutation tool, this is a significant transparency gap.

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

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

A single 14-word sentence with the core action front-loaded and zero wasted words. The parenthetical compresses behavioral nuance into a compact clause. Appropriately sized for what it conveys.

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 bulk write operation with no output schema, a single undocumented parameter, and only readOnlyHint: false in annotations, the description is far too thin. An agent needs to understand the approval-vs-write modes, where notification IDs come from, and the consequences of bulk denial to invoke this safely — none of that is provided.

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 compensate. It confirms that notificationIds refers to BP notifications, but it gives no guidance on ID format, where to source them (e.g., hcm_list_notifications), batch-size limits, or empty-array behavior. This is minimal compensation for an undocumented parameter.

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 action ('reject/deny') applied to a specific resource ('BP notifications') at bulk scope, which semantically differentiates it from hcm_bulk_approve_notifications and from single-item tools like hcm_get_notification. The parenthetical '(approval unless --write)' is cryptic and slightly muddies the clarity, but the core purpose 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?

No guidance is given on when to use this tool versus hcm_perform_bp_action, hcm_deny_write, hcm_bulk_bp_dry_run, or hcm_bulk_approve_notifications. No alternatives, exclusions, or selection conditions are named; the agent must infer intent purely from the tool name.

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

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

The annotation readOnlyHint: false already declares this is a write operation, and the description's 'Create' aligns with that — no contradiction. The description adds a behavioral trait beyond the annotation by hinting at an approval workflow ('approval unless --write'), which is useful context, but it's vague and unexplained — the agent doesn't know what --write means or how approval is triggered.

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

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

The description is a single short sentence with the core purpose front-loaded, which is efficient. However, the parenthetical 'approval unless --write' wastes its space on an unexplained flag rather than conveying actionable information — it's cryptic, not informative.

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 create operation with a free-form nested object body and no output schema, this definition is incomplete. The agent has no information about required body fields, the approval workflow's implications, or return values. With no schema constraints and 0% description coverage, there is nothing to guide a 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 description coverage is 0%, so the description carries the full burden of explaining the `body` parameter, but it says nothing about it. The body is an unconstrained object (additionalProperties: {}) with no field documentation, and the description doesn't mention what fields an absence entry needs (e.g., worker, absence type, dates). The agent cannot construct a valid request from this definition.

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 ('Create an absence entry'), which clearly distinguishes it from the many absence siblings like hcm_search_absences, hcm_get_absence, hcm_update_absence, and hcm_delete_absence based on the action verb. However, it doesn't name any sibling explicitly, and the parenthetical 'approval unless --write' is cryptic and detracts from clarity.

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 is given on when to use this tool versus alternatives. There is no mention of related tools such as hcm_update_absence, hcm_delete_absence, or the approval-flow siblings (hcm_list_pending_approvals, hcm_approve_write, hcm_deny_write). The 'approval unless --write' hint gestures at a workflow but doesn't explain the conditions for using this 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?

With only readOnlyHint=false, the annotation already tells the agent this is a mutation; the description adds little beyond a cryptic approval/write caveat. It does not disclose side effects, approval semantics, required permissions, or what happens to the created AOR.

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 extremely short, but brevity here is under-specification rather than useful conciseness. It contains no structured guidance and front-loads an unresolved, ambiguous parenthetical.

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 write operation with an opaque body and no output schema, this description is far from complete. It omits the meaning of AOR, the approval workflow, the body structure, and any indication of the result or next steps.

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 'body' parameter has 0% schema description coverage and is a free-form object with no properties documented. The description gives no hint about required fields, structure, or expected content, so the agent cannot construct a valid body.

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 action and resource ('Create AOR'), but the acronym AOR is never expanded and the parenthetical '(approval unless --write)' muddies whether the tool creates an approval, an AOR, or a direct write. It does not differentiate this create tool from the many sibling create tools.

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 when-to-use or when-not-to-use context is given relative to hcm_get_aor, hcm_update_aor, hcm_delete_aor, or hcm_approve_write. The only conditional cue, 'unless --write', refers to a flag that does not appear in the input schema, so it cannot guide invocation.

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

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

Annotations only indicate readOnlyHint=false, so the mutation is already clear. The description adds value by disclosing the approval requirement and providing an example body, which gives insight into expected input. It does not mention side effects or failure modes, but for a simple create operation this is reasonable.

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 sentences with no fluff. The purpose is front-loaded, and the example is directly useful. Every element 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?

This is a create operation with a single object parameter, but the description does not specify required fields (the example may not be exhaustive), what the response contains, or any validation rules. Without an output schema, the agent lacks information about the result or potential errors. This is a significant gap for a mutation tool.

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

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

The schema describes 'body' as 'Worker JSON payload' with additionalProperties allowed, which is vague. The description supplements this with a concrete example containing 'DisplayName' and 'PersonNumber', giving agents a practical starting point for constructing the payload. This goes 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 states the action 'Create a worker' with a specific resource. It is unambiguous and distinct from sibling tools like hcm_update_worker or hcm_get_worker by its verb and noun.

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 notes 'requires approval unless --write', which is a usage constraint, but it does not explicitly contrast this tool with alternatives or state when to use it versus other create tools (e.g., hcm_create_absence). The naming convention helps, but explicit guidance is missing.

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

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

The annotation only indicates readOnlyHint: false. The description adds valuable behavioral context by stating that the operation requires approval unless the --write flag is used, and that it creates a nested resource. This goes beyond the minimal annotation and helps the agent understand the mutation's approval flow.

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

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

The description is a single sentence with the key action front-loaded. It is efficient, but the ellipsis in 'workRelationships/.../assignments' introduces ambiguity and reduces clarity. Overall, it is appropriately concise.

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

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

Given the tool has three parameters (including a complex body object), no output schema, and no parameter documentation, the description is far from complete. It omits the body schema, workerId semantics, and response expectations. The approval nuance is helpful but does not fill the 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 0%, and the description does not explain any of the three parameters (workerId, body, periodOfServiceId). It hints at periodOfServiceId via the path 'workRelationships/.../assignments' but provides no details on body structure or required fields. The description fails to compensate for the lack of schema documentation.

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 the action ('Create nested worker assignment') and the resource location ('under workRelationships/.../assignments'), distinguishing it from sibling tools like hcm_get_worker_assignments (read) and hcm_update_worker_assignment (update). It is specific and not a tautology, though it could be more explicit about the resource semantics.

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 includes an approval condition ('approval unless --write') but does not explain when to use this tool versus alternatives, nor does it mention prerequisites or scenarios where a different tool (e.g., update) would be appropriate. No explicit when/when-not guidance is provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds a cryptic 'approval unless --write' note but fails to explain what --write does, how the approval process works, or the consequences of deletion. This adds confusion rather than clarity.

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, but the parenthetical structure is poorly formed and ambiguous. It is not verbose, but the lack of clear sentence structure and the cryptic note make it less effective than a straightforward single clause.

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 destructive tool with one parameter and no output schema, the description is incomplete. It does not explain the approval flow, the meaning of --write, success/failure behavior, or how it relates to other tools like hcm_get_absence or hcm_approve_write. An agent would be uncertain about the actual effects and required steps.

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% and the description provides no explanation of absenceId. It does not specify the format, how to obtain a valid ID, or any validation requirements. With zero coverage, the description should have compensated but did not.

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 clear action ('Delete an absence'), but the parenthetical '(approval unless --write)' introduces ambiguity about whether the tool deletes directly or via an approval workflow. This muddles the primary purpose and does not clearly distinguish it from hcm_approve_write or hcm_update_absence.

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 is provided on when to use this tool versus alternatives like hcm_update_absence or hcm_approve_write. The description does not mention any prerequisites, conditions for direct deletion vs approval, or when the --write flag should be used.

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

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

The annotations declare destructiveHint=true and readOnlyHint=false, so the description correctly implies a destructive operation, but it adds confusion with 'unless --write'. It does not explain what happens to related data, whether the deletion is reversible, or whether approval is required. The description partially contradicts the annotations by suggesting a non-destructive '--write' mode.

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 extremely short, which is concise, but the parenthetical 'unless --write' is cryptic and wastes the only sentence. It is front-loaded with the verb 'Delete' but the ambiguity undermines its efficiency.

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 destructive tool with no output schema and minimal parameter documentation, the description is inadequate. It does not explain the deletion scope, side effects, or how the '--write' flag relates to the operation. An agent cannot confidently invoke this tool correctly based on the description alone.

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%, and the description only mentions 'AOR' without explaining the aorId parameter. The description does not clarify what an AOR is, how to obtain a valid aorId, or any constraints on the ID format. With a single required parameter and no schema description, the description should compensate but fails to do so.

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 'Delete AOR (approval unless --write)' states a verb and resource, but the parenthetical is confusing and ambiguous. It suggests the tool deletes an AOR unless a '--write' flag is present, which contradicts the tool name and the destructiveHint annotation. It does not clearly distinguish from sibling tools like hcm_delete_absence or hcm_update_aor.

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 is provided on when to use this tool versus alternatives. The parenthetical 'unless --write' is unclear and could mislead an agent about when deletion actually occurs. There is no mention of prerequisites, such as needing an existing AOR ID or approval workflow context.

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

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

readOnlyHint=false already signals mutation; the description only repeats that by saying 'Deny'. It does not disclose consequences, reversibility, permission requirements, or what happens to the pending write after denial. With no annotations beyond readOnlyHint=false, the description carries the full burden and falls short.

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

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

One short sentence with the action and parameter front-loaded. No wasted words; perfectly scoped for a single-parameter tool.

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

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

For a mutation with no output schema and minimal annotations, the description is underspecified. An agent is not told what response to expect, whether denial is reversible, or how this fits into the pending-approval workflow with hcm_list_pending_approvals and hcm_approve_write.

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 0%, but the description at least says the approval_id identifies the pending write to deny, going beyond the bare 'string' type. It lacks details about where the ID comes from or what format it is expected to be in.

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

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

The description uses a specific verb ('Deny') and a specific resource ('a pending write'), and identifies the key (approval_id). It is immediately distinguishable from the sibling hcm_approve_write and from read-only tools.

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 no guidance on when to choose this tool over hcm_approve_write or how to obtain a valid approval_id (e.g., via hcm_list_pending_approvals). It states the action but no workflow context, prerequisites, or exclusion criteria.

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

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

The readOnlyHint annotation already declares this is a read-only operation, and the description does not contradict that. It adds a useful behavioral caveat that the catalog is curated and not full Fusion metadata, but it does not go deeper into return format, completeness guarantees, or other operational behavior. This is decent but not rich behavioral context.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the 'not full Fusion metadata' caveat is placed prominently in the second sentence. Every word 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 two-parameter, read-only tool, the description covers the general purpose and an important caveat. However, it leaves the list-all-finders trigger ambiguous and provides no output-shape guidance, which matters more here because there is no output schema. A little more detail about how to invoke each mode would make it 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?

The schema has 0% description coverage, so the description must carry parameter meaning on its own. It only loosely implies that 'resource' scopes the finder and that a finder may be omitted to list all finders, but it never explains valid values, requiredness, or how the two parameters interact. This is insufficient compensation for the total lack of schema-level parameter documentation.

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 the verb ('Describe'), the resource type ('curated ADF finder parameters'), and an alternate mode ('list all finders'). This distinguishes it from related siblings like hcm_describe_resource or hcm_lov_finder. The 'Unofficial catalog' qualifier further narrows its scope.

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

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

The description implies a lightweight, unofficial use case and hints that omitting a finder may list all finders, but it never explicitly states when to use this tool versus alternatives. It also does not warn against using it when full Fusion metadata is required, even though that is the main value of the 'unofficial' caveat.

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 annotation readOnlyHint=true already indicates this is a safe read operation. The description adds minimal behavioral context beyond that—it implies the tool returns a description or schema, but the exact return format is not disclosed. This is acceptable but not rich.

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

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

The description is a single, compact sentence that is front-loaded with the core action ('Describe a curated resource by name') and gives examples. It is appropriately sized with no wasted words.

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

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

Given the tool is a simple metadata/descriptor with one parameter and no output schema, the description is mostly adequate. However, it doesn't mention what 'describe' returns (e.g., a schema, a list of fields, etc.), which could leave the agent uncertain about the output format. Since the output schema is absent, a little more detail would be beneficial.

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 covers 100% of the parameter 'name' with a clear description and example. The description repeats the example, providing little additional value. However, it does reinforce that the name should be a curated resource name, which is slightly more specific.

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 the tool's purpose: to describe a curated resource by name. It gives examples like 'workers' and 'planBalances', making it specific. However, it doesn't explicitly differentiate from hcm_describe_finder or hcm_list_resources, though the intent is 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?

No explicit guidance on when to use this tool versus alternatives. It doesn't mention that it's for metadata/introspection versus actual data retrieval, nor does it list any exclusions or conditions. The agent must infer from the name and examples.

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

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

The readOnlyHint=true annotation aligns with the read-only nature of 'summarize'. The description adds useful context about client-side filtering and the optional timestamp, but it does not disclose pagination behavior, output shape, or how 'recent' is determined.

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

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

The description is a single, compact sentence with no filler, and it front-loads the core action. The phrasing 'Atom/change entries' and 'client-side filter on feed' is somewhat jargon-heavy but still concise.

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 and three parameters, the description does not explain what the summarized result looks like, what 'collection' refers to, or how 'limit' behaves. The lack of sibling differentiation and parameter context leaves an agent with an incomplete picture for calling the tool correctly.

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

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

Schema coverage is only 33%, with solely 'since' described. The description reinforces that 'since' is an optional ISO timestamp, but it adds no meaning for 'limit' or 'collection', leaving those parameters effectively undocumented in both the schema and the description.

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 clear action ('summarize') and resource ('recent Atom/change entries'), and mentions the optional 'since' timestamp. However, it does not explicitly differentiate this tool from closely related siblings like hcm_list_atom_entries or hcm_atom_poll.

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

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

There is no guidance on when to use this tool versus alternatives. The phrase 'client-side filter on feed' implies it reads feeds, but it never contrasts with hcm_list_atom_entries or hcm_atom_poll, so an agent cannot decide confidently between them.

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 the description adds meaningful context: it validates path/method/body shape and explicitly states 'does not call Fusion'. This goes beyond the annotation by clarifying the tool's non-execution behavior and validation scope, providing useful additional transparency without contradicting 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?

The description is a single, concise sentence that front-loads the core action ('Dry-run an allowlisted mutate') and then efficiently states what it validates and what it does not do. There is zero redundant phrasing, making it highly economical and easy to parse.

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?

The tool has only three parameters and no output schema, and the annotations cover safety (readOnlyHint). The description explains the validation scope and the non-call behavior, but it does not specify what the tool returns (e.g., validation errors, success status) or clarify what 'allowlisted' means in practice. For a dry-run tool, understanding the output format is important, and this 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?

Schema description coverage is 0%, yet the description only mentions 'path/method/body shape' without elaborating on each parameter's meaning, format, or constraints. It does not compensate for the schema's lack of descriptions; the enum for method and type for path are provided only in the schema, not clarified in the description. The description adds minimal semantic value beyond what the schema already exposes.

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 the tool's function: to dry-run an allowlisted mutate operation, validating path/method/body shape without actually calling Fusion. This distinguishes it from actual mutation tools like hcm_rest_mutate and hcm_rest_get, and the specific verb 'dry-run' plus resource 'allowlisted mutate' makes the purpose 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 description implies when to use it (for validation without side effects) by stating 'does not call Fusion', but it does not explicitly reference sibling tools or state when NOT to use it. There is no direct comparison to hcm_rest_mutate, so the guidance 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, so the description does not need to restate safety. It adds useful context that the output is redacted and secrets are placeholders, but it does not describe the fragment structure, defaults, or any side effects. This is a modest value-add beyond the annotation.

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

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

A single sentence with no filler, front-loading the action and artifact. Every word contributes meaning.

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?

The tool is simple, with one optional boolean and read-only annotations, so the description covers the core purpose. However, it omits includeWriteServer semantics and any routing guidance, making it adequate but incomplete for a fully confident 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 description coverage is 0%, and the description never mentions includeWriteServer. An agent must infer from the parameter name and the 'oracle-hcm / oracle-hcm-write' pairing that it controls inclusion of the write server, which is not reliable.

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

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

The description uses a specific verb ('Emit') and names the exact artifact ('redacted Cursor mcp.json fragment') plus the target integrations ('oracle-hcm / oracle-hcm-write'). This makes it distinguishable from data-access siblings like hcm_export_config even without opening the schema.

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

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

No guidance is given on when to use this tool versus alternatives, and no exclusions or conditions are stated. The intended usage is only implied by the tool name and the Cursor-specific wording.

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, and the description adds that the tool returns classification and usage hints without indicating side effects. It does not describe output format or behavior for unknown tool names, but for a read-only metadata tool the disclosure is adequate.

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

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

A single sentence front-loads the core action and then lists the returned dimensions. There is no filler, repetition, or unnecessary 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 meta-tool meant to aid tool selection, the description does not state when to use it, what 'curated' means, or how the name parameter maps to sibling tools. With no output schema and no parameter documentation, the description leaves important context 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%, and the description does not explicitly explain that the 'name' parameter should be the exact identifier of the MCP tool to explain. The tool name and phrasing imply it, but no valid values, format, or relationship to the sibling list is provided.

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 action (explain) and target (a curated MCP tool), then enumerates the output facets: class, related resource, and usage hints. This distinguishes it from hcm_describe_resource, which is likely about resources rather than MCP tools, though the description does not explicitly name that sibling.

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

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

The description gives no guidance on when to use this tool versus alternatives like hcm_describe_resource, hcm_probe_capabilities, or hcm_rbac_hint. It does not provide context for choosing it or exclude any 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?

The readOnlyHint annotation already signals safety, and the description adds meaningful context by emphasizing that only public, non-secret config is exported and that the output is JSON. This clarifies the tool's behavioral boundary without contradicting the annotation.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource before stating the intended use cases. Every phrase contributes meaning, and there is no redundant or filler content.

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-parameter, read-only export tool, the description provides sufficient context: what is exported, its non-secret nature, and typical use cases. While no output schema is present, the simple nature of the operation does not demand extensive additional detail.

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

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

With zero parameters, the schema leaves nothing undocumented, and the description need not elaborate on parameter meaning. The description appropriately focuses on the tool's purpose and output rather than fabricating parameter guidance.

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 ('Export'), a concrete resource ('public (non-secret) config JSON'), and an intended purpose ('multi-env profiles / backup'). This clearly distinguishes it from sibling tools like hcm_emit_mcp_config, which likely generates rather than exports configuration.

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 communicates the appropriate context: exporting non-secret configuration for multi-environment profiles or backup purposes. It does not explicitly name alternative tools or state when not to use it, but the use case is clear enough for an agent to select it appropriately.

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

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

The readOnlyHint annotation already tells the agent this is a safe read operation, so the description does not need to restate safety. It adds a small behavioral clue about finder and country filtering, but it does not explain what the finder returns, whether results are paged, or how the filter behaves.

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 extremely concise with no filler, and the key idea is front-loaded. However, it is so terse that it sacrifices the explanatory value needed for a tool with no parameter descriptions.

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, zero parameter description coverage, and no differentiation from similar location tools, the description is not sufficient for an agent to select and call the tool correctly. The brief parenthetical leaves too much to inference.

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 compensate for the undocumented parameters. It only explains 'finder' and 'country' at a high level, leaving 'q' and 'limit' completely unexplained.

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 location finder helper with a country filter, so it names a resource and a filtering behavior. However, 'helper' is vague, and it does not explain how this tool differs from the sibling hcm_search_locations or hcm_get_location.

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 about when to use this tool instead of hcm_search_locations, hcm_lov_finder, or hcm_describe_finder. The parenthetical '(finder + country filter)' hints at a mechanism but does not state the intended use case or alternatives.

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

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

Annotations already signal readOnlyHint=false and destructiveHint=true, and the description adds the notion of approval via 'approval unless --write'. However, --write has no corresponding parameter in the schema, so the disclosure is confusing and incomplete. The description also says nothing about consequences, reversibility, or the meaning of 'approval' in this flow.

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

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

The description is a single short sentence with the core action front-loaded and no wasted words. The parenthetical is cryptic and arguably adds confusion, which keeps it from being perfect.

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 destructive tool with no output schema, an undocumented nested body object, and no parameter descriptions, one sentence is insufficient. The agent is left without information about what body should contain, when approval is required, what side effects force-closing has, or how this relates to the write-approval workflow suggested by 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 0% and the description does not explain checklistId or body. The required checklistId is inferable from the tool's name and action, but body is completely opaque, and the --write mention muddles rather than clarifies parameter or behavioral semantics.

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

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

The description names a specific verb ('Force-close') and resource ('allocated checklist'), which clearly distinguishes it from siblings like hcm_allocate_checklist and hcm_get_checklist. The parenthetical 'approval unless --write' introduces ambiguity, but the core action is clear enough for an agent to know what the tool does.

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

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

The description gives no guidance on when to use force-close versus alternatives such as hcm_update_task_status, hcm_list_pending_approvals, or hcm_approve_write/hcm_deny_write. The phrase 'allocated checklist' implies a precondition, but it is never explicitly stated, and no when-not-to-use or alternative routing is provided.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description's 'Get' wording is consistent with that. No additional behavioral context is added, such as behavior for unknown IDs or whether all absence fields are returned, but the annotation meaningfully lightens the burden for this simple read.

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

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

The description is a single front-loaded sentence with no filler words. It earns its place by naming the resource and the lookup key, though its brevity leaves the burden of context to other dimensions.

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-only getter with no output schema, the description is minimally adequate: it communicates the operation and the key. It is not fully complete because it omits what an absence record contains, how to obtain a valid absenceId, and when to prefer search_absences over this direct 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?

With schema description coverage at 0%, the description needed to compensate for the undocumented absenceId parameter, but it only restates that the lookup is by ID. It does not explain the ID format, source, uniqueness, or how to obtain a valid absenceId from a search.

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

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

The description uses a specific verb-resource pair — 'Get absence' — and adds the retrieval key 'by id', which clearly communicates this is a single-record lookup rather than a search, create, update, or delete operation. It does not explicitly contrast itself with hcm_search_absences, so it stops short of full sibling 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?

The description provides no guidance on when to use this tool instead of hcm_search_absences, hcm_absence_balance, or hcm_get_absence_type_balance. An agent must infer that a direct ID lookup is intended, but no context, prerequisites, or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds no real behavioral context: it doesn't explain how absenceType filters the balance, what the finder returns, whether it aggregates plans, or how a person is identified beyond the schema property.

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

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

The description is short, but the single sentence is mostly a restatement of the tool name and an internal implementation reference. It is under-specified rather than efficiently informative, and no useful structure is present.

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, zero parameter descriptions, and a vague one-line description, an agent cannot confidently invoke this tool or interpret its result. The required parameter and read-only annotation are the only reliable signals, which is far from 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 0%, so the description carries the burden of explaining personNumber and absenceType. It does neither. The agent only learns from the schema that personNumber is required and absenceType is optional, but not their semantic meaning or format.

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

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

The description restates the tool name in camelCase ('getAbsenceTypeBalance-style helper') and adds only an opaque implementation detail ('via planBalances finder'). It does not plainly state that this tool returns an absence type balance for a person, nor does it distinguish the behavior from similar tools like hcm_get_plan_balance or hcm_absence_balance.

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

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

There is no guidance on when to use this tool versus alternatives. The phrase 'style helper' is ambiguous, and the description never mentions conditions, exclusions, or related tools that should be considered instead.

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

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

The readOnlyHint annotation already declares this as a read-only operation, so the description adds little beyond that. It does not disclose behavior such as error handling on non-existent IDs, response format, or pagination (irrelevant here). The description is consistent with the annotation and provides minimal extra context.

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

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

The description is four words and directly states the core action. There is zero fluff or repetition, making it exceptionally concise and easy to scan. For a simple get-by-id tool, this level of brevity is appropriate.

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

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

Given the low complexity (one parameter, no output schema) and the read-only annotation, the description covers the essential action but omits context like what an AOR is, what the response looks like, and any error behavior. With many sibling tools, it could benefit from a sentence clarifying its role, but it is minimally adequate for an agent that understands the domain.

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 is the only source of parameter meaning. It says 'by id' but does not explain what an AOR ID is, its format, or how to obtain it. This adds only slightly more than the schema's bare 'aorId' field, which is insufficient for a complete understanding.

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 ('Get') and resource ('AOR') and specifies retrieval by id, which distinguishes it from the search tool hcm_search_aor. However, it does not define the acronym 'AOR' or the exact scope of the resource, leaving some ambiguity for agents unfamiliar with the domain.

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 explicit guidance on when to use this tool versus alternatives. The presence of hcm_search_aor implies that hcm_get_aor is for fetching a single known AOR, but the description does not state this distinction or mention any prerequisites like needing the ID beforehand.

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, matching the read-only 'Get' verb; there is no contradiction. The description adds little beyond what the annotation conveys, however—it does not disclose what an Atom entry is, how it relates to Atom feeds and checkpoints, what happens on a miss (e.g., null vs error), or whether pagination/replay behaviors apply. With the safety profile carried by annotations, a 3 baseline is appropriate.

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 that front-loads the verb and resource, with zero filler or repetition of the tool name. Every word contributes meaning.

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?

The tool has no output schema and sits inside a dense Atom-related sibling cluster (feeds, poll, consume, checkpoints, list_entries). The description does not suffice for an agent to understand how this single-entry fetch relates to those flows or what the returned entry contains. For such a simple call shape it is acceptable, but the missing ecosystem context and absence of any return-value hint keep it below 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 0%, so the description carries the full burden for the single entryId parameter. It does tell the agent that the ID is an EntryId that identifiers the Atom entry, which adds meaning beyond the raw schema type. However, it does not specify the value format, whether the ID is globally unique or feed-scoped, or how to obtain a valid EntryId (e.g., via hcm_list_atom_entries), leaving a gap the schema cannot fill.

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 ('Get'), a distinct resource ('a single Atom entry'), and the identifying mechanism ('by EntryId'). This clearly differentiates it from the sibling hcm_list_atom_entries (plural listing) and hcm_atom_poll/consume (processing flows), which is exactly what a retrieval-by-ID tool should convey.

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 is given on when to use this tool versus its many Atom-related siblings (hcm_list_atom_entries, hcm_atom_poll, hcm_atom_consume). The description does not say it's the right choice when you already know a specific entry ID, nor does it clarify how it fits into the feed/checkpoint workflow. An agent must infer all usage context 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?

The readOnlyHint annotation covers the safety profile, so the description only needs to add behavioral context. It does mention the format switch to XML and the 'dummy' mechanism, but both are vague. The description does not disclose pagination, how 'since' affects results, or whether the feed is a live or stubbed source.

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

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

The description is short and front-loaded with the core action, which is good. However, 'via dummy' is an unclear and potentially misleading phrase that adds confusion without earning 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 should explain return shape and behavior more thoroughly, but it only says 'as JSON entries.' It also fails to address the 'limit' and 'collection' parameters and does not orient the agent among the many atom-related sibling tools, leaving important context 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 low (only 'collection' is described in the schema), so the description must compensate. It does add meaning for 'since' as an ISO filter and for 'format' as controlling JSON vs XML, but it says nothing about 'limit' or the 'collection' filtering behavior beyond the schema's terse enum values.

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

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

The description clearly states the tool retrieves an Atom feed, with JSON as the default and optional XML format. However, the phrase 'via dummy' is confusing and not explained, which slightly muddies what the tool actually does. It does not explicitly differentiate this tool from sibling Atom-related tools like hcm_list_atom_entries or hcm_detect_changes.

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 is given about when to use this tool versus the many closely related Atom feed tools such as hcm_atom_poll, hcm_atom_consume, hcm_list_atom_entries, or hcm_detect_changes. The description implies a basic retrieval use case but provides no exclusions or alternatives.

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

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

The annotation readOnlyHint=true already establishes that this is a safe read operation, and the description adds no contradiction. 'SENSITIVE gate' contributes useful context that the data may require elevated permissions or special handling, but it is vague and does not explain what the gate entails or what happens if access is denied.

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 extremely short and front-loaded with the core operation, and every word is purposeful. The 'SENSITIVE gate' label is cryptic and could have been phrased more clearly, but the overall structure has no unnecessary filler.

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

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

For a single-parameter read-only getter, the basic shape of the call is clear, and the schema covers the required input. However, the description does not explain the return value (there is no output schema), the meaning of 'SENSITIVE gate,' or how this tool differs from hcm_search_bank_accounts, leaving an agent without enough context for confident 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?

With schema description coverage at 0%, the description needed to compensate for the undocumented bankAccountId parameter but did not. The parameter name is somewhat self-explanatory, but the description adds no meaning about the ID format, where to obtain it, or how it is used to select the bank account.

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 clear verb and resource: 'Get bank account.' It identifies the tool as a single-record retrieval operation, and the 'get' versus 'search' naming in the sibling list helps distinguish it from hcm_search_bank_accounts. However, it does not explicitly say it fetches one account by ID, leaving some detail to the schema and tool 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?

There is no guidance about when to use this tool versus hcm_search_bank_accounts or other bank-related tools. 'SENSITIVE gate' hints at access restrictions but does not explain when the tool is appropriate or what preconditions apply. The agent is left to infer usage from the tool 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?

The readOnlyHint annotation already communicates that this is a safe read operation, but the description adds no behavioral details beyond that. It does not mention what happens when the id is not found, what data is returned, or any edge cases. With no extra behavioral context from the description, the transparency is limited.

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 appropriately short and front-loads the verb and resource. There is no filler or redundant information. It is slightly terse, but every word earns its place for such a simple lookup tool.

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

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

For a one-parameter read-only lookup, the description is adequate but sparse. An agent with an enrollmentId can invoke the tool, but the description does not explain how to obtain the ID, what the response contains, or how not-found cases are handled. Since there is no output schema, some of this missing context is a real gap.

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

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

The schema provides no description for enrollmentId, only that it is a required string. The description's 'by id' confirms that the parameter is the lookup key, but it adds no detail about the ID format, source, or uniqueness. The compensation for the schema coverage gap is minimal.

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 ('Get'), a clear resource ('benefits enrollment'), and the lookup method ('by id'). This distinguishes it from the sibling tool hcm_search_benefit_enrollments, which searches rather than fetches a single record. The purpose is immediately 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?

The phrase 'by id' implies this tool should be used when an enrollment ID is already known, and that it retrieves a specific record. However, there is no explicit guidance about when to use it versus hcm_search_benefit_enrollments, nor any mention of prerequisites or alternatives. The usage context is only minimally 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?

The annotations already declare readOnlyHint=true, and the description's 'Get' aligns with a read-only operation. The description adds no further behavioral detail beyond the id-based lookup, but the annotation covers the most important safety trait.

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

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

The description is a single, concise, front-loaded sentence with no wasted words. It communicates the core operation and key parameter role efficiently.

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-parameter read operation with readOnlyHint=true, the description provides enough to invoke the tool correctly: it names the resource, the lookup key, and the operation. It does not describe return format or not-found behavior, but those are not critical to selecting and calling such a simple get-by-id tool.

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

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

With schema description coverage at 0%, the description's 'by id' does clarify that candidateId is the identifier for the candidate being retrieved. However, it provides no additional detail about id format, origin, or constraints beyond what the schema already states with the property name and type.

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

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

The description uses a specific verb ('Get'), a clear resource ('recruiting candidate'), and identifies the lookup key ('by id'). It clearly differentiates from the sibling hcm_search_candidates by implying a single-record fetch by identifier, though it does not explicitly name that 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?

Usage is implied: use this tool when you have a candidate ID and need the corresponding candidate record. However, there is no explicit guidance about when not to use it or which alternative tool to choose, such as hcm_search_candidates for search scenarios.

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

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

readOnlyHint=true already establishes the operation is safe; the description adds a modest behavioral note that expand=allocatedTasks may not be supported in all environments. No contradictions. However, it does not disclose error behavior, not-found handling, or response structure.

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 states the core action immediately and appends a useful caveat about expand support. No unnecessary words.

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

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

For a simple read-only get-by-id with an optional expand parameter, the description covers the essential call semantics. The main gap is unspecified return behavior for missing IDs and the meaning of 'allocated checklist', but annotations and schema cover the rest.

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

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

With 50% schema coverage, the description partially compensates by naming 'id' and 'allocatedTasks', but the guidance is thin: it does not clarify the format of checklistId or fully explain expand values. Adds some meaning beyond the raw schema but leaves details to inference.

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 specifies a verb ('Get'), a resource ('allocated checklist'), and a selector ('by id'). This distinguishes it from list/allocate/force-close siblings, making the operation identifiable at a glance.

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

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

The description implies the tool should be used when you have a checklist ID, but it does not explicitly contrast with hcm_list_checklists or other checklist-related tools. No exclusions or alternative-router guidance is provided.

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

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

The readOnlyHint annotation already covers the read-only nature. The description adds 'SENSITIVE gate', which signals access sensitivity, but gives no detail about what the gate entails or what behavior the agent should expect beyond the annotation.

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 extremely short and front-loaded, but it is terse to the point of under-specification. 'SENSITIVE gate' is attention-grabbing but adds a warning without explanation, so the brevity does not fully earn its place.

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

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

For a sensitive compensation-data tool with no output schema and minimal description, an agent is left without important context such as what the response contains, what 'SENSITIVE gate' means operationally, or how compensationId should be obtained. The annotations cover read-only safety but not the gating 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?

Schema description coverage is 0%, and the description does not explain the meaning or format of compensationId beyond the schema's field name. The phrase 'compensation row' loosely implies the id identifies a row, but that adds little semantic value.

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 clear verb and resource: 'Get compensation row' indicates a fetch-by-identifier operation. It is broadly distinguishable from a search tool like hcm_search_compensation, though it does not explicitly contrast itself with that 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?

No guidance is given about when to use this tool versus alternatives such as hcm_search_compensation. The 'SENSITIVE gate' phrase hints at caution but does not explain when this tool should or should not be invoked.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds no extra behavioral context such as error behavior, required permissions, or exact payload returned. It merely restates the operation without adding transparency beyond 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?

The description is a single, front-loaded sentence with no fluff. It is concise, though arguably under-specified for a tool in a large API surface.

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 and no parameter descriptions, the one-sentence description leaves the agent without knowledge of the return shape, potential workspaces, or error semantics. It is sufficient only for a trivially obvious GET, which is not the case given the broad 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?

Input schema has contactId as an untyped string with no description; schema coverage is 0%. Description says 'by id' which adds little beyond the parameter name. It does not clarify ID format, source, or distinguish it from other IDs in the system.

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 the specific verb 'Get' and resource 'contact', with retrieval by ID. This distinguishes it from hcm_search_contacts (search vs direct id lookup) and other get_* tools, though it doesn't elaborate on the contact type.

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 use this tool versus hcm_search_contacts or other lookup tools. It does not state prerequisites, alternative tools, or conditions that would select this 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?

The annotations declare readOnlyHint=true, and the description's 'Get' phrasing is consistent with a read operation. However, the description adds no behavioral context beyond the annotation—it does not state what the response contains, whether it can return null, or any error behavior. With annotations present, the description contributes little additional transparency.

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 extremely concise—a single sentence with no wasted words. However, it is under-specified; it carries no information beyond the tool name and parameter, so the brevity reflects a lack of content rather than efficient structure. It is not structured to lead with important clarifications.

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 tool, the description is not complete. It does not describe the return value, which is critical given there is no output schema. It also fails to note error conditions or related context. The annotations only cover read-only safety, leaving the agent without enough detail to correctly interpret the tool's 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?

The schema has one required parameter goalId (string) with no description coverage. The description's phrase 'by id' adds no semantic value beyond the parameter name itself; it does not explain the format of goalId, how to obtain it, or any constraints. Since schema coverage is 0%, the description fails to compensate for the missing parameter documentation.

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 ('Get goal') and indicates the access method ('by id'), making it clear this tool retrieves a single goal by its identifier. It does not explicitly contrast with sibling hcm_search_goals, but the 'by id' phrasing distinguishes it from search-oriented tools.

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 versus alternatives such as hcm_search_goals or hcm_get_performance_document. It does not mention prerequisites like needing a valid goalId or that search should be used when 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?

The annotation readOnlyHint=true already indicates a safe read operation, and the description's word 'Get' is consistent. However, the description adds no additional behavioral context beyond what the annotation provides—no mention of response structure, error behavior, rate limits, or any side effects. With the annotation carrying the main safety signal, the description does not enhance transparency further.

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 extremely succinct—just three words—with no redundancy or filler. It front-loads the essential action and resource. While it is terse, it is appropriately concise for a simple lookup tool; there is no unnecessary detail that would impede comprehension.

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?

In the context of a large API surface with many related tools (e.g., hcm_search_grades, hcm_get_worker), this one-liner lacks essential context. It does not explain what a 'grade' represents in this system, how to locate the correct id, or what fields will be returned. Without an output schema and with zero parameter descriptions, the description falls short of providing a complete contract for an agent to call it correctly with confidence.

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 only parameter gradeId is briefly implied by the phrase 'by id', but the description does not elaborate on what a gradeId is, how to obtain it, or any constraints (format, length, etc.). The schema only defines it as a string, so the description adds minimal semantic value beyond the parameter name itself.

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 the action (get), the resource (grade), and the access method (by id). It is specific enough to distinguish from the sibling hcm_search_grades, which implies a search over grades rather than a direct lookup. However, it does not explicitly name that alternative, so it earns 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?

The description provides no guidance on when to use this tool versus the many siblings, particularly hcm_search_grades. There is no mention of prerequisites, typical scenarios, or exclusions. An agent would have to infer that 'get by id' is for single-record retrieval, but no explicit usage context is given.

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

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

The readOnlyHint annotation already communicates that this is a read operation, but the description adds no behavioral detail beyond that, such as what happens when the job ID doesn't exist or what the response contains. It does not contradict the annotation.

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 words with no filler, front-loaded with the verb and resource. Every word earns its place for such a simple getter.

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

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

Given the single required parameter and read-only annotation, the description is sufficient to invoke the tool correctly. It lacks return-format details, but for a simple get-by-id operation this is not a critical gap.

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

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

Schema description coverage is 0%, so the description must compensate for explaining the jobId parameter. 'By id' only weakly maps to the jobId field and adds no detail about format, source, or examples.

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 clear verb and resource: 'Get job by id.' It conveys a get-by-id operation and distinguishes itself from search-style siblings by requiring a specific identifier, though it doesn't explicitly name the alternative search_jobs tool.

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?

Provides no explicit guidance on when to use this tool versus alternatives such as hcm_search_jobs. There is no mention of prerequisites, when to prefer search over get-by-id, or what to do when 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?

The readOnlyHint annotation already covers the safe read-only nature of the tool, and the description does not contradict it. However, the description adds no behavioral context beyond the verb 'Get'—no mention of not-found behavior, authentication needs, or response characteristics.

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

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

The description is a single concise sentence with the verb and resource front-loaded. There is no filler or redundant wording, making it highly scannable 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?

For a simple one-parameter getter with a readOnlyHint, the description is minimally adequate. However, with no output schema and no documentation of the enrollmentId format, plus no mention of the sibling search tool for obtaining IDs, an agent is left with some gaps 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 0%, and the description only says 'by id,' which adds no meaning beyond the parameter name enrollmentId. It does not specify the ID format, where to obtain it, or any constraints, so the description fails to compensate for the missing schema documentation.

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?

Description states a specific verb ('Get'), a specific resource ('learning enrollment'), and the access method ('by id'). It clearly distinguishes itself from sibling hcm_search_learning_enrollments, which is for searching rather than direct retrieval.

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

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

The description implies that this tool is used when you already have a learning enrollment ID, but it does not explicitly say when to use this versus hcm_search_learning_enrollments. No exclusions or alternative conditions are provided.

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

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

Annotations declare readOnlyHint=true, so the description does not need to restate safety. The description adds no behavioral context beyond the annotation, such as return format or error behavior, but for a simple read-by-id tool the annotation covers the main safety profile.

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

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

The description is a single short sentence with no wasted words. It is appropriately sized for a simple get-by-id tool.

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

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

For a simple read-only lookup with one parameter and no output schema, the description is nearly complete. However, it does not mention what the response contains or whether the location is a physical address, organizational unit, or other entity, which could matter for an agent deciding between this and hcm_find_locations.

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%, but there is only one parameter, locationId, whose meaning is self-evident from the tool name and description. The description adds minimal semantic value beyond the schema, but the parameter is simple enough that the baseline is acceptable.

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 'Get location by id' clearly states the verb (get) and resource (location) and identifies the key parameter (id). It is distinguishable from siblings like hcm_search_locations and hcm_find_locations, though it does not explicitly name them.

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

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

No guidance is provided on when to use this tool versus alternatives such as hcm_search_locations or hcm_find_locations. The context implies a direct lookup by ID, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

The readOnlyHint annotation already signals a read operation. The 'SENSITIVE gate' warning adds useful context about restricted access, but it does not explain what the gate entails, such as permissions, denial behavior, or payload restrictions.

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 extremely short and front-loaded with no filler. However, 'SENSITIVE gate.' is a fragment, and the brevity leaves important context underspecified rather than being a clean, complete summary.

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 getter, the description is minimal but incomplete. It omits the relationship to hcm_search_national_identifiers, the meaning of the sensitive gate, and what happens on unauthorized or missing-identifier requests.

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%, and the description adds no parameter-specific meaning. The parameter name nationalIdentifierId is self-explanatory as an identifier, but there is no guidance on format, how to obtain it, or how it maps to search results.

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 clear verb and resource ('Get national identifier') and the schema confirms a fetch-by-ID operation. It is distinguishable from hcm_search_national_identifiers by singular 'get' wording, though it does not explicitly name that distinction.

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

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

Usage is implied: the caller must already have a nationalIdentifierId. It gives no explicit alternative or condition, even though hcm_search_national_identifiers is the obvious sibling for finding identifiers.

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

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

The description matches the readOnlyHint annotation, so there is no contradiction. However, it adds no behavioral details beyond what the annotation already conveys, such as not-found behavior, response format, or any additional context about the operation.

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

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

The description is a single, focused sentence with no filler. The key action and target are presented immediately, making it easy for an agent to parse and act on.

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-parameter, read-only get operation, the description combined with the schema and readOnlyHint is sufficiently complete for basic invocation. It could optionally mention how to discover notification IDs via hcm_list_notifications or describe the return shape, but the low complexity and lack of an output schema make those omissions acceptable.

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 compensate. It does clarify that notificationId can refer to a task/notification id, which adds some meaning beyond the bare schema. However, it does not explain the expected format, source, or possible difference between task and notification IDs.

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 the verb 'Get' and a specific resource ('business process notification') identified by ID. It naturally distinguishes this tool from hcm_list_notifications by focusing on a single record fetch rather than a list 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?

The description implies the tool should be used when a specific notification ID is available, but it does not explicitly state when to use it versus alternatives like hcm_list_notifications. No exclusions or pitfalls are mentioned, but the guidance is largely implicit.

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 declare readOnlyHint=true, so the agent knows this is a read-only operation. However, the description adds no additional behavioral context—it does not mention what the tool returns, how errors are handled (e.g., 404 if ID not found), or any permissions needed. Since annotations already cover safety, the description's lack of added context lowers the score, though it does not contradict the annotation.

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

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

The description is a single, concise sentence: 'Get organization by id.' It is front-loaded with the action and resource, contains zero filler, and is appropriately sized for a simple get-by-id operation. Every word 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?

Given the simplicity (one parameter, no output schema, no nested objects), the description is somewhat complete but lacks explicit mention of the return behavior or error cases (e.g., what happens if the ID is not found). Since there is no output schema, the description could have clarified the expected response, but it does not. It is adequate for a basic operation but leaves minor 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 0% and the schema only defines organizationId (string, required). The description's phrase 'by id' gives some semantic meaning, indicating that the parameter is an ID, which is helpful. However, it does not specify the ID format (e.g., UUID vs numeric) or provide additional interpretation. Given the very low coverage, the description partially compensates but does not fully clarify parameter semantics.

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

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

The description 'Get organization by id' clearly states the action (get), resource (organization), and identification method (by id). It distinguishes from search tools like hcm_search_organizations, but does not explicitly differentiate from close siblings such as hcm_get_org_hierarchy, which may also involve fetching organization-related data. Thus, it is clear but not fully differentiated.

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 usage guidance whatsoever. It does not indicate when to prefer this tool over alternatives like hcm_search_organizations (for searching) or hcm_get_org_hierarchy (for hierarchy). No exclusions or context are given, leaving the agent to infer the appropriate usage 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?

The annotation readOnlyHint: true already discloses that this is a read-only operation, so the description's burden is lighter. The description adds the behavioral trait that the tree is 'simple' and includes 'dummy parent/child' nodes, suggesting the result is a simplified or placeholder-augmented structure. However, it does not disclose error conditions, depth limits, data freshness, or whether the tree includes all descendants or only immediate children, leaving notable gaps.

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

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

The description is a single, tightly worded sentence of 12 words. It front-loads the action and resource, then adds a clarifying parenthetical. Every word earns its place; there is no fluff, and the structure is ideal for quick parsing.

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

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

With a single parameter, a read-only annotation, and low complexity, the description is adequate but not complete. It tells the agent what the tool returns (an org hierarchy tree) but does not describe the shape of the tree—fields, depth, whether it is recursive, or how 'dummy' nodes appear. Since there is no output schema, the agent must guess the response structure. This is a clear gap, though the simplicity of the tool keeps the score at a moderate level.

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 compensate for the lack of parameter documentation. It does so by stating that organizationId is the root of the hierarchy, giving semantic meaning beyond the raw 'string' type in the schema. This helps an agent understand the role of the parameter. It does not explain the expected ID format or that it is required, but the schema already lists it as required, so this is acceptable.

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 the tool returns an org hierarchy tree rooted at the given organizationId. It specifies the verb 'Return', the resource 'org hierarchy tree', and the root parameter, which distinguishes it from siblings like hcm_get_organization (single entity) and hcm_list_direct_reports (direct reports only). The parenthetical 'dummy parent/child' further characterizes the simplified tree shape, making the purpose 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 description provides no guidance on when to use this tool versus alternatives such as hcm_get_organization, hcm_search_organizations, or hcm_list_direct_reports. It does not mention use cases, nor does it explain when one would prefer this over fetching a single org or direct reports. An agent must infer the usage from the name alone, which is not reliable given the rich sibling 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?

The only behavioral trait mentioned, 'read-only', duplicates the existing readOnlyHint annotation and adds no new context. No information is provided about return behavior, missing IDs, errors, permissions, or response shape, so the description carries little weight beyond the annotation.

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

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

The description is a single concise sentence with no filler; 'read-only' is somewhat redundant with the annotation but does not harm clarity. It is appropriately sized and front-loaded for a simple getter.

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-only getter, the description covers the core facts an agent needs: the operation, target resource, lookup key, and read-only nature. It could mention the response shape or explicitly compare with the search variant, but these are not critical 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?

The single parameter, payrollRelationshipId, is self-descriptive, and the phrase 'by id' confirms it is the lookup key. However, the description does not add substantive guidance beyond the schema property name—no format, source, or example—and with 0% schema description coverage it only minimally compensates.

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 'Get' and resource 'payroll relationship', with the qualifier 'by id' that clearly differentiates from the sibling hcm_search_payroll_relationships: this tool fetches a single entity by identifier rather than searching. The read-only note also signals intent.

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 rather than explicit: 'by id' indicates the tool is appropriate when a payrollRelationshipId is already known, but the description does not call out alternatives or state when to prefer hcm_search_payroll_relationships. There is no when-not-to-use guidance.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds 'SENSITIVE gate,' which hints that this operation may trigger additional access controls or approval steps, but it does not explain what the gate entails, leaving the behavioral context vague.

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 extremely short and front-loaded: 'Get payslip by id' says the core action, and 'SENSITIVE gate' adds a relevant caution. No words are wasted, though the terseness leaves room for more 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 tool with no output schema and a sensitive-data annotation, the description is too sparse. It does not clarify what the sensitive gate does, what authorization is required, or how the returned payslip data is structured, so an agent may not know the implications of calling 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?

Schema description coverage is 0%, so the description must compensate for the undocumented payslipId parameter. It only restates 'by id' without clarifying the ID format, source, or whether this is an Oracle HCM payslip ID versus another identifier, so it adds little beyond the property name.

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 a specific verb ('Get') and resource ('payslip by id'), so an agent can tell this is a direct fetch operation. However, it does not explicitly distinguish itself from the sibling hcm_search_payslips, so it misses the full differentiation expected for a 5.

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

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

There is no guidance on when to use this tool versus hcm_search_payslips or other related getters. The phrase 'by id' implies direct lookup, but it never states that search should be used when the payslip ID is not already known, nor does it mention any 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?

The description adds no behavioral detail beyond what the readOnlyHint annotation already conveys. It does not contradict the annotation, but it also does not disclose any additional context such as error handling, response format, or required permissions, which is expected when annotations only cover safety.

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

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

The description is a single, terse sentence with no unnecessary words. It is appropriately sized for the tool's simplicity and front-loads the core action without padding.

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

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

For a simple get-by-ID tool with one parameter and a read-only annotation, the description is minimally viable. It does not describe the return value or failure behavior, but these are less critical given the simplicity and the readOnlyHint. However, it could be more complete by mentioning what the document contains or how to interpret the ID.

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%, and the description provides no explanation of the documentId parameter. The parameter name is self-explanatory, but the description fails to compensate for the lack of schema coverage by clarifying format, source, or any special constraints.

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

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

The description clearly states a specific verb ('Get'), resource ('performance document'), and access method ('by id'). It is unambiguous about the tool's function, though it does not explicitly contrast with the sibling hcm_search_performance_documents, which would earn 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?

No guidance is given on when to use this tool versus alternatives. The presence of hcm_search_performance_documents suggests a distinction, but the description does not state when a direct get is appropriate (e.g., when an ID is already known).

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

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

The description does not contradict the readOnlyHint annotation. It adds a small amount of behavioral context by naming the exact Fusion endpoint and indicating single-resource retrieval. However, it does not mention error behavior, authorization needs, or response characteristics. Since the annotation already covers the safety profile, a 3 is appropriate.

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

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

The description is a single front-loaded sentence with no filler. It states the action, the resource, the lookup key, and the endpoint efficiently. Every word 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 one-parameter read-only tool, the description is nearly sufficient to invoke the tool. However, with no output schema and no clarification of how this relates to other balance-oriented siblings, an agent may lack enough context to fully interpret the result or choose correctly among nearby 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 0%, and the description only repeats that retrieval is 'by id', adding no meaningful semantics for balanceId. It does not clarify what a plan balance is, where the ID comes from, or any expected format. The description fails to compensate for the schema's lack of parameter documentation.

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 the verb 'Get', the resource 'single plan balance', and the lookup mechanism 'by id'. The parenthetical 'Fusion planBalances/{id}' helps identify the underlying endpoint. It doesn't explicitly distinguish itself from related balance tools like hcm_get_absence_type_balance, but the resource is reasonably 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?

No guidance is given about when to use this tool versus sibling tools such as hcm_absence_balance or hcm_get_absence_type_balance. There are no conditions, prerequisites, or alternatives described, so an agent must infer usage solely from the 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?

The readOnlyHint annotation already communicates that this is a safe read operation, and the description does not contradict it. However, the description adds no extra behavioral context, such as return shape, error behavior, or scope of the returned position, so it contributes minimal transparency beyond the annotation.

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 five words with no filler and front-loads the core operation. For a simple get-by-id tool with a single parameter, this is appropriately sized and every word 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?

Given the single required parameter and the readOnly annotation, the description is nearly sufficient. However, since there is no output schema, it omits any indication of what the returned position contains or how failures like not-found are handled, leaving a small but real gap for an agent invoking the tool.

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

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

Schema coverage is 0%, and the description only echoes the notion of 'id' without explaining what positionId represents, where it comes from, or whether alternate identifiers are accepted. The parameter name is self-explanatory, but the description adds little beyond the schema itself.

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 clear verb and resource: 'Get position by id.' The 'by id' qualifier broadly distinguishes it from hcm_search_positions, but it does not explicitly name the sibling or describe scope, so it stops 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?

There is no guidance about when to use this tool versus alternatives such as hcm_search_positions. The only hint is that an id is needed, which is already obvious from the required positionId parameter; no exclusions or sibling routing are provided.

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

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

The readOnlyHint annotation already declares the operation is read-only, and the description adds no additional behavioral details such as response format, error handling, or permission requirements. The description carries minimal burden beyond what annotations already provide, offering no extra transparency.

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 extremely concise—one sentence with no waste. However, it is under-specified to the point of being terse rather than effectively structured. It front-loads the key action but lacks supporting context that could be included without bloat.

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 tool with a single parameter and read-only annotation, the description is minimal. It does not explain what a 'publicWorker' is, what data is returned, or how it differs from a regular worker. Given the large sibling list with similar get/search tools, this lack of context makes it incomplete for an agent to correctly choose and use 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?

With schema description coverage at 0%, the description must compensate. It only mentions 'by id', which merely restates the parameter name 'publicWorkerId'. No format, constraints, or meaning beyond the name is given, offering negligible value over the schema.

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

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

The description clearly states the verb 'Get' and the resource 'publicWorker' identified by id. It is specific enough to know it retrieves a single public worker by ID, but it does not differentiate from sibling tools like hcm_get_worker or hcm_search_public_workers, which weakens clarity slightly.

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

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

There is no guidance on when to use this tool versus alternatives such as hcm_search_public_workers (when ID is unknown) or hcm_get_worker (for full worker data). No context on prerequisites, exclusions, or conditions for selection is provided.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation; the description simply repeats 'Get' without adding behavioral context such as response shape, null behavior, required permissions, or rate limits. It adds no information beyond what the annotation and name already convey.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the essential operation efficiently and is easy for an agent 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?

For a simple read-only getter with one required parameter, this is minimally adequate. However, there is no output schema and no description of what is returned, nor any mention of alternates like hcm_search_requisitions, leaving clear but minor 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 0%, so the description should compensate for the undocumented parameter. It does not: 'by id' merely restates the requisitionId parameter name and gives no format, source, or examples. The parameter name is self-explanatory, but the description adds no meaningful semantic 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?

The description uses a specific verb ('Get') and identifies a clear resource ('recruiting job requisition') with a lookup key ('by id'). It is understandable on its own, though it does not explicitly contrast with sibling tools like hcm_search_requisitions or hcm_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?

There is no guidance on when to use this tool versus alternatives such as hcm_search_requisitions or hcm_get_job. The 'by id' phrasing implies a single-record lookup, but no explicit context, prerequisites, or exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds no further behavioral context, such as what happens for invalid IDs, what fields are returned, or any error behavior.

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

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

The description is a single, front-loaded sentence with no filler or redundant content. It is appropriately short for a simple get-by-id tool.

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

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

For a low-complexity tool with one parameter and a readOnly annotation, the description is adequate but minimal. It omits any indication of what the returned schedule contains and does not mention the likely relationship to hcm_search_schedules.

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 compensate. The phrase 'by id' minimally ties scheduleId to the operation, and the single parameter is self-describing, but no guidance is given on how to obtain the ID or what format to use.

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: 'Get work schedule by id.' It distinguishes itself from hcm_search_schedules by making clear this is a direct ID-based lookup rather than a search, though it does not explicitly name that sibling.

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

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

The phrase 'by id' implies the tool is used when a schedule ID is already known, likely after using hcm_search_schedules. However, it does not explicitly say when to use this tool versus alternatives or when not to use it.

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

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

The readOnlyHint annotation already covers the safe read profile, and the description's 'Get' aligns with that. It adds no extra behavioral context like error behavior, authorization needs, or payload scope, but for a simple read-only getter the risk 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 six-wored sentence with no filler, front-loading the action and target. Every word 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?

Adequate for a one-parameter read-only getter: an agent knows to pass profileId and can expect a profile in return. But there is no output schema and no mention of return shape, nor guidance to search_talent_profiles when the ID is unknown, so it is only minimally 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 has zero descriptions for the profileId parameter, so the description must compensate. 'by id' clearly indicates that profileId is the identifier used to fetch the profile; the parameter name itself reinforces this. It lacks format or example, but is sufficient for a single string 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 clear verb (Get), resource (talent person profile), and method (by id). It does not explicitly distinguish itself from hcm_search_talent_profiles or hcm_get_worker, so it misses top sibling-diferentiation.

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?

Implies use when a known profileId is available, which is the natural context for a get-by-id tool. However, it gives no explicit when/when-not guidance, no pointer to the corresponding search tool for finding IDs, and no contrast with similar worker/profile getters.

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 the description's 'Get' is consistent with that. The description adds no additional behavioral context such as error behavior, auth requirements, or what a successful response contains, but the read-only nature is already covered by 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?

The description is a single six-word sentence with no filler. It is front-loaded with the action and resource, and every word earns its place.

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

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

For a one-parameter read-only getter, the description is nearly complete: an agent knows the operation and the parameter role. It loses one point for not naming the search sibling as the way to locate an id and for omitting any note about response shape, though no output schema exists.

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 compensate for the undocumented timeRecordId parameter. It adds only 'by id', which mostly restates the parameter name; it does not explain the id format, source, or relation to search results.

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 ('Get') and resource ('time record') with a qualifier ('by id'), which clearly differentiates it from sibling hcm_search_time_records. An agent can tell this is a direct fetch-by-ID tool without opening the schema.

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

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

The description implies usage when the caller has a timeRecordId, but it does not explicitly state when to prefer this over hcm_search_time_records or any other alternative. There is no when-not guidance, so the agent must infer the choice from the sibling names.

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

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

The readOnlyHint annotation already declares this is a safe read operation, and the description aligns with that by using 'Get'. The description does not add behavioral context beyond the annotation, such as response shape, error behavior, or permissions, but for a simple get operation the annotation covers the safety profile. No contradiction 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?

The description is one short sentence plus a compact example, with no filler or repetition. The key lookup mechanism is front-loaded and the example reinforces the parameter shape efficiently. This is appropriately sized for a one-parameter get tool.

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

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

For a low-complexity read-only lookup with a single required parameter and a fully documented schema, the description plus annotation is sufficient for an agent to invoke the tool correctly. The lack of an output schema is not a gap here because the return value is implied by 'Get a worker'. Nothing essential is missing.

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

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

Schema description coverage is 100% and the workerId parameter is already documented as the 'Worker primary key'. The description's example provides a concrete value format, which is mildly helpful, but it does not add significant meaning beyond what the schema already states. Baseline 3 is appropriate given the high 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 states a specific verb and resource: 'Get a worker by WorkerId'. It is clear that this is a direct-fetch operation keyed on the worker's primary key. However, it does not explicitly differentiate itself from siblings like hcm_search_workers or hcm_get_public_worker, so it earns 4 rather than 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?

The phrase 'by WorkerId' implies the tool is intended for direct lookup when a worker ID is already known, which is useful guidance. It does not explicitly state when to prefer hcm_search_workers or hcm_get_public_worker, nor does it mention exclusions. Usage conditions remain implied 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, so the description correctly implies a read operation. However, it adds little beyond the annotation: the 'prefers/falls back' detail is about endpoint selection, not user-visible behavior. It doesn't disclose response format, pagination, or error conditions, which would be useful given no output schema exists. It does not contradict the annotation.

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 extremely concise—two short sentences—and avoids fluff. It leads with the primary purpose. However, the brevity comes at the cost of missing critical details, so while it's efficient, it's under-specified. Structurally it's acceptable but not exemplary.

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 tool with no output schema, the description should explain what the returned data looks like, but it does not. It also doesn't address pagination, filtering, or the meaning of 'deep-read'. Given the tool's simplicity (two params, one required), the description leaves significant gaps that an agent would need to infer or test.

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 50% (expand has a description, workerId does not). The description does not mention either parameter, so it adds no meaning beyond the schema. For workerId, which is required and undocumented, the description provides zero clarification. It fails to compensate for the coverage gap.

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 tool reads worker assignments, which is a specific resource, but 'deep-read' is vague jargon that isn't explained. It also references an implementation detail (preferring workers/{id} expand over workerAssignments) without clarifying what the returned data actually contains. While it's distinguishable from siblings by name, the description itself doesn't explicitly differentiate it from hcm_get_worker or hcm_get_work_relationship.

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 is provided on when to use this tool versus alternatives. It mentions a fallback path, but that's an internal routing detail, not usage context. There are no stated exclusions or conditions for selection, leaving the agent to infer when to call this tool over hcm_get_worker or others.

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

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

The readOnlyHint annotation already communicates that this is a read-only operation, and the description adds that the result is a 'nested' work relationship. However, it does not explain what nesting means, whether related objects are embedded, or what the response shape is, so behavioral transparency beyond the annotation remains limited.

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

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

The description is a single concise sentence with the verb and resource front-loaded, so it is efficient and free of filler. It could be expanded with parameter or usage context without becoming bloated, but as written it is faithful to the principle of conciseness.

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 two required parameters, no output schema, and a large sibling tool set, the description is too sparse for reliable invocation. An agent cannot determine what 'nested work relationship' returns, how periodOfServiceId is obtained, or how this tool differs from related worker or relationship getters.

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 clarify the parameters, but it only partially explains workerId via 'for a worker'. The required periodOfServiceId parameter is completely unexplained, leaving the agent without enough information to know how to construct a valid request.

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 ('Get') and a resource ('nested work relationship') for a worker, so the general purpose is clear. However, 'nested' is ambiguous and the description does not distinguish this from related sibling getters such as hcm_get_worker_assignments or hcm_get_payroll_relationship.

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 no guidance about when to use this tool instead of alternatives, no prerequisites beyond the required parameters, and no indication of what kind of work relationship scenarios it covers. An agent would have to infer usage from the tool name and sibling context.

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

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

Annotations declare readOnlyHint=truehol, and the description is consistent with that. It adds that the tool targets the configured HCM REST base and is an unofficial MCP wrapper, but it does not disclose response format, timeout behavior, or whether it merely pings the base URL. Given the annotation coverage, this is adequate but not rich.

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 terse, front-loaded sentence contains the essential scope ('configured HCM REST base') and a relevant caveat ('unofficial MCP'). There is no filler or redundant content.

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 parameterless, read-only health check, the description covers the core purpose and target sufficiently. It does not specify what result the agent should expect, and there is no output schema, but the tool's semantics are predictable from its name and description.

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 input schema has zero parametersahan, so there is no parameter documentation burden for the description to carry. The baseline of 4 for a parameterless tool applies.

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

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

The description states a specific verb and resource ('Check connectivity to the configured HCM REST base'), making the tool's purpose clear. However, it does not distinguish this tool from the sibling hcm_test_connection, which appears to perform a similar connectivity check.

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 compared with hcm_test_connection, hcm_setup_status, hcm_probe_capabilities, or related diagnostic tools. There is no mention of prerequisites, alternatives, or 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?

The readOnlyHint annotation already communicates safety, so the description only needs to add value beyond that. It does add one meaningful behavioral trait: 'Dummy returns mock change events,' which warns that the tool may return synthetic data. It does not disclose pagination behavior, return format, or the meaning of the finder/q parameters, so the behavioral picture is only partially complete.

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 core purpose: 'List Atom feed / change-detection entries.' The second sentence about dummy/mock behavior is useful and earns its place. It is not bloated, though the term 'Dummy' itself is slightly unclear.

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 tool with 5 parameters, no output schema, and only a readOnly hint, this description is too sparse. It does not explain the meaning of the filtering/search parameters, how pagination works, or what shape the mock change events take. The 'Dummy returns mock change events' note is helpful but insufficient for an agent to confidently invoke the tool 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 only 20%, with only 'collection' having a description ('e.g. workers'). The description adds no parameter semantics at all: q, limit, finder, and offset remain unexplained in both the schema and description. With low schema coverage, the description was expected to compensate, but it does not.

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 clear verb and resource: 'List Atom feed / change-detection entries (Fusion atomfeeds).' This distinguishes it from sibling tools like hcm_list_atom_feeds and hcm_get_atom_entry by focusing on entries rather than feeds or individual entry retrieval. However, it does not explicitly differentiate itself by naming an alternative or scope, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus related tools such as hcm_get_atom_entry, hcm_atom_poll, hcm_detect_changes, or hcm_atom_consume. The phrase 'Dummy returns mock change events' hints that the output may be non-production data, but it does not explain the intended use case or when an alternative should be preferred.

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

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

The description is consistent with the readOnlyHint=true annotation — 'List' is a read operation, so no contradiction exists. It adds modest value beyond the annotation by clarifying the feeds are change-detection oriented and by revealing that this environment exposes workers/absences/all. However, it does not disclose the return format or behavior when no feeds exist, and with the safety profile already covered by annotations, the extra disclosure is limited.

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 the core action front-loaded in the first sentence ('List known Atom / change-detection feeds'). The second sentence about the dummy environment is useful context, though the phrase 'Dummy exposes' is slightly cryptic and could confuse an agent about whether this is a production or test listing. Overall it is efficiently sized with minimal waste.

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

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

For a simple, no-parameter, read-only listing tool, the description covers the purpose and even hints at available feed types. However, it does not describe the output structure (e.g., what a feed entry looks like or how IDs map to hcm_get_atom_feed), and since there is no output schema, an agent has no structured fallback for that information. This is adequate but leaves a meaningful gap for downstream feed consumption.

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 has zero parameters, and the schema coverage is vacuously 100%. Per the rubric, a no-parameter tool starts at a baseline of 4. The description adds contextual value by naming the actual feed types available (workers/absences/all), even though no parameter semantics are needed here.

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

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

The description states a specific verb ('List') and resource ('known Atom / change-detection feeds'). The qualifier 'collection-oriented' implicitly distinguishes it from the sibling hcm_get_atom_feed, which would target a single feed. The note 'Dummy exposes workers/absences/all' adds concrete detail about what feeds exist, making the purpose tangible. It falls short of a 5 only because it doesn't explicitly name the sibling it contrasts 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?

The description gives no explicit when-to-use guidance or exclusions. 'Collection-oriented' only implies that this is for enumerating feeds rather than retrieving a single one (hcm_get_atom_feed), and it doesn't differentiate from related siblings like hcm_atom_poll, hcm_atom_consume, or hcm_detect_changes. An agent must infer the intended use case from the name and the qualifier rather than from explicit routing guidance.

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

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

The annotation readOnlyHint=true already signals a read operation. The description adds value by clarifying the exact content (MCP audit trail, not Fusion transaction history) and implies no side effects. It does not describe pagination or response format, but for a simple read-only list tool, the provided context is adequate and consistent with the annotation.

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

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

The description is a single, front-loaded sentence with no filler. It efficiently conveys the core function and the key distinction from Fusion history. Every word earns its place.