PaySpace MCP by usefulapi

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds a meaningful 'Personal data' sensitivity note and the underlying OData path, but says nothing about what happens with unknown employee ids or what fields the biographical record contains.

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

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

Front-loaded with the action and key scoping detail in one sentence; nothing is buried. The trailing raw endpoint path is the only low-value element for an agent and keeps it from a 5.

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

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

For a two-parameter single-record read with 100% schema coverage and full annotations, the description supplies what's needed: what entity is fetched, keyed by what, and the sensitivity class of the data. Absence of an output schema means the return shape is only loosely scoped as 'biographical record'.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's bare 'EmployeeId, a whole number' by explaining the id's provenance — it comes from payspace_list_employees — which is real added meaning an agent cannot get from the schema alone.

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

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

States a specific verb and resource ('Get one employee's biographical record') and narrows scope with 'by EmployeeId', clearly separating it from the list siblings. Naming payspace_list_employees as the source of the id tells an agent exactly which tool precedes this one.

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 reference to payspace_list_employees as where the numeric id comes from gives clear context for when this tool is the right second step. It stops short of an explicit exclusion (e.g. 'do not use for bulk retrieval; use payspace_list_all_employees'), so it is strong but not complete.

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 the operation as read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context by flagging 'Personal data' and exposing the underlying OData GET endpoint, though it does not discuss permissions, response size, or rate limits.

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

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

The description is extremely compact and front-loaded: purpose, data sensitivity note, and endpoint in three short fragments. Every element contributes useful information without repetition.

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

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

Given the rich schema and annotations, the description supplies enough context to select and call the tool safely. The main missing piece is explicit routing guidance relative to sibling employee-list and employee-get tools; return-value details are less critical for a list endpoint with obvious semantics.

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

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

Schema description coverage is 100%, so the seven parameters are already well documented in the schema. The description adds only the endpoint path mentioning {company}, but does not add meaning beyond the schema for filter, select, paging, or count parameters.

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

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

The description uses a specific verb and resource ('List all employees of a company') and adds the important scope qualifier 'including terminated ones.' It is clear enough to distinguish this from a single-employee lookup, but it does not explicitly contrast with the closely named sibling payspace_list_employees.

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 'including terminated ones' implies when this tool is preferable to a standard employee list, but the description never states when to use it versus payspace_list_employees or payspace_get_employee. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value by disclosing the data source ('From the token reply of POST /connect/token'), which implies this reflects credential scope rather than a paged API listing. It does not discuss result size or error behavior, keeping it below 5.

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

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

Two dense sentences with no filler; the purpose and returned fields are front-loaded, and the operational hint about company_id follows immediately. Every clause earns its place.

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

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

For a zero-param read tool with no output schema, the description compensates well by naming the four returned fields and the source of the data. It could still say whether the list is always complete or scoped by environment, but nothing essential for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description still helps by naming the downstream argument (company_id) these values feed, clarifying how the output is consumed even though there is nothing to parameterize here.

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

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

States a specific verb+resource ('List the companies') and enumerates the returned fields (id, code, name, group), plus the access scope ('the API credentials can access'). The note that company ids feed the company_id argument of the other tools makes its role distinct from the many payspace_list_* siblings.

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

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

'Company ids go into the company_id argument of the other tools' effectively tells the agent to call this first as a prerequisite for the rest of the toolset. It gives clear context but no explicit exclusions or alternatives, so it falls short of a full when/when-not statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered externally. The description contributes the concrete REST endpoint and the entity's field set, but says nothing about rate limits, page-size defaults, or result shape beyond what annotations and schema supply.

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

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

Two compact clauses with zero filler; the field subset is front-loaded alongside the verb. Slightly truncated rather than verbose, but efficient.

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

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

All parameters are optional and well described in the schema, and there is no output schema, so the parenthetical field list usefully signals return contents. However, with six parameters and a highly similar organization-positions sibling, the description leaves paging behavior and disambiguation implicit.

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

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

Schema description coverage is 100%, so all six parameters (top, skip, count, filter, orderby, company_id) are already fully documented, including the filter syntax example and company_id fallback. The description adds no parameter-level meaning beyond the field list, so baseline 3 applies.

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

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

States a specific verb and resource ('List employee position records') and enumerates the salient fields (job, organization unit, grade, manager, effective dates), plus the underlying OData entity. It is clear apart from most siblings, though it never explains how it differs from the closely named payspace_list_organization_positions.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. An agent must infer from the name alone that this is the record source for an employee's job/grade/manager assignment rather than, say, payspace_list_jobs or payspace_list_organization_units.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real value beyond them: the result set is restricted to active employees, the payload is personal data, and the underlying OData path is disclosed. It doesn't cover default page size or rate limits, but those live in the schema.

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

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

Three compact sentences, front-loaded with what the tool returns and its scope, then the sensitivity flag, the endpoint, and the sibling redirect. No filler.

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

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

Covers purpose, scope restriction, PII caution, return fields, and the alternative tool — enough to invoke correctly without an output schema. Pagination and filter syntax are delegated to a well-described schema, which is reasonable.

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

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

Schema description coverage is 100%, so top/skip/count/filter/select/orderby/company_id are already fully documented, and this is the baseline-3 case. The description adds only an indirect hint at the field vocabulary used by select/filter (name, employee number, contact, dates), nothing about syntax.

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

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

States a specific verb (List), resource (employees), and scope (active only) plus what data comes back (name, employee number, contact, dates) and the backing endpoint. The active-only qualifier and the pointer to payspace_list_all_employees make it unmistakable against both list and get siblings.

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

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

Explicitly routes the terminated-employee case to payspace_list_all_employees, which is the main decision an agent faces here. It does not contrast with payspace_get_employee (single record) or mention paging strategy, but the list-vs-single split is inferable from the verb.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only the underlying OData endpoint path, which hints at filter/paging semantics but discloses nothing about result shape, rate limits, or authorization needs beyond what annotations and schema provide.

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

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

Two short sentences with the resource scope front-loaded and no filler. The trailing raw endpoint string is somewhat developer-facing but supports understanding of the OData filter/paging model.

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

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

With no output schema, the description does at least sketch the returned record shape (hire, termination, reason, dates), and all six parameters are richly documented in the schema. Combined with annotations covering safety, an agent has nearly everything needed, though return-field detail is thin.

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

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

Schema description coverage is 100%, so every parameter (top, skip, count, filter, orderby, company_id) is already documented with examples and constraints. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

Names a specific verb and resource ('List employee employment status records') and scopes the payload with a parenthetical field list (hire, termination, reason, dates). It is clearly distinct from sibling list tools such as payspace_list_employees or payspace_list_suspensions, though it never explicitly contrasts itself with them.

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

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

There is no statement of when to use this tool versus alternatives, nor any prerequisite guidance in the description. The company_id hint about single-company credentials lives only in the schema, not in the description text. Usage is only inferable 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds nothing beyond the endpoint path: no note on paging defaults, result-set size, or entity fields. For a paged OData list, that is thin.

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

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

Two front-loaded sentences with zero filler; the verb and scope come first and the endpoint second. Nothing needs trimming, though the endpoint sentence is only marginally value-adding.

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 0 required parameters, full schema docs and complete read-only annotations, most of an agent's needs are met. But the description never says what a 'job' record contains or how it differs from organization positions, and gives no output-shape hint in the absence of an output schema.

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

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

Schema description coverage is 100%: top/skip/count/filter/orderby/company_id are each documented in the schema with examples and limits. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the jobs defined in job management for a company') and even names the backing endpoint. It is distinguishable from most siblings, though the boundary with payspace_list_organization_positions (jobs vs. positions) is never clarified.

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 when-to-use / when-not-to-use guidance and never names an alternative among the many list_* siblings. The only routing hint in the definition (call payspace_list_companies for company ids) lives in the schema, not the description.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds one genuinely useful behavioral flag — "Personal data" — warning that results are sensitive/PII, plus the underlying GET endpoint. It says nothing about pagination limits or result volume, which matters for a list endpoint over a potentially large entity.

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

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

Three short fragments, front-loaded with the purpose and the clarifying gloss. The trailing raw endpoint path is marginal filler for an agent, but overall there is no wasted prose.

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?

Annotations cover read-safety and the schema covers all six parameters, so the definition is callable as-is. It is still thin for a six-parameter OData list endpoint with no output schema: nothing about default page size, how to page through large result sets, or which fields are commonly filtered, all of which the agent must derive from the schema.

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

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

Schema description coverage is 100%, including per-parameter docs for $top/$skip/$filter/$orderby and the company_id fallback rule, so the baseline is 3. The description adds nothing beyond the schema — no filterable-field hints or default paging behavior — leaving the schema to carry all parameter meaning.

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

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

States a specific verb and resource ("List employee leave adjustments") and disambiguates the domain term with "manual changes to leave balances," which an agent needs to distinguish adjustments from entitlements/applications. However, it never names the closely related siblings payspace_list_leave_applications and payspace_list_leave_entitlements, so the reader must infer the boundary.

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

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

The parenthetical implies when this entity is the right one (balance corrections, not requests or accruals), but there is no explicit when-to-use, no prerequisites, and no named alternative among the many leave/payroll siblings. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the 'Personal data (absence)' privacy flag and the constraint that year/month must be supplied together to scope the period. It stops short of describing result ordering or paging behavior, but the additions are substantive.

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

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

Three short sentences, front-loaded with what the tool returns, followed by the one non-obvious usage rule and a compact endpoint reference. Nothing is padded, though the raw GET path is borderline redundant for an agent that only needs selection and invocation cues.

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

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

For a read-only list tool with 8 optional parameters and full schema coverage, the description supplies the returned fields, the period-restriction rule, the privacy classification and the underlying endpoint, while annotations carry the safety profile. There is no output schema, but the field list in the description covers what an agent needs to know about the response shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-parameter rule the schema does not express: year and month must be given together to restrict to a period. That is meaningful semantics beyond the individual field docs. The remaining parameters (top, skip, filter, orderby, count) are left entirely to the schema.

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

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

States a specific verb and resource ('List employee leave applications') and enumerates the returned fields (type, dates, days, status), so the agent knows exactly what data comes back. It does not explicitly distinguish itself from close siblings like payspace_list_leave_adjustments or payspace_list_leave_entitlements, leaving that differentiation to the names alone.

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

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

The sentence 'Give year and month together to restrict to a period' gives one concrete usage rule, which is genuinely helpful. However, there is no guidance on when to prefer this over the leave-adjacent siblings, no mention of prerequisites (e.g. company_id resolution), and no when-not-to-use conditions.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the description. The description adds only the underlying GET endpoint path, which signals a read-only OData query but says nothing about pagination limits, result size, or rate/authorization constraints beyond what annotations and schema 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?

Two terse fragments with the resource and returned fields front-loaded; nothing is padded. The trailing endpoint path is arguably redundant given the annotations, but it is compact and useful for API-aware callers.

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 required parameters, full schema coverage, and no output schema, the description plus structured fields give an agent everything needed to call it correctly. The only shortfall is that it does not describe the shape of a returned entitlement record beyond the two named fields, which is minor for a list endpoint.

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

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

Schema description coverage is 100%, with each of the six OData parameters documented in detail (top/skip paging, filter examples, orderby, count, company_id resolution). The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List employee leave setup entitlements') and enumerates the returned fields (leave type, days per cycle), which separates it from siblings like payspace_list_leave_applications and payspace_list_leave_adjustments. It does not explicitly name those siblings as the alternative, so differentiation is implicit rather than stated.

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

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

The phrase 'leave setup entitlements' implies configuration/entitlement lookup rather than transactional leave data, which is enough for an agent to infer usage. However, there is no explicit when-to-use, when-not-to-use, or named alternative among the many leave-related siblings, and no note about the company_id default behaviour that the schema describes.

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, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered. The description adds only the raw endpoint path (OData v2.0, company-scoped), with nothing about pagination behaviour, result shape, or permission requirements beyond what the schema and annotations already say.

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

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

Two short sentences with the core intent front-loaded and no filler. The endpoint sentence is marginally redundant with the title but does confirm the OData entity being queried.

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

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

For a read-only list tool with no required parameters, full schema coverage and complete annotations, what is missing is minor: sibling disambiguation and any hint about the OData response envelope. No output schema exists, but the gap is small for a straightforward listing operation.

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

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

Schema description coverage is 100%, and every parameter — top, skip, count, filter, orderby, company_id — is documented in the schema, including OData syntax examples. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (list organization position details) and even names the backing entity, OrganizationPositionDetail. However, it draws no boundary against the close sibling payspace_list_employee_positions, so an agent cannot tell from the description alone which one returns position records vs. employee-to-position assignments.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as payspace_list_employee_positions or payspace_get_employee. 'Defined for a company' faintly implies a company-level reference catalog, but the agent must infer that the tool is not employee-scoped.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the underlying endpoint (GET /odata/v2.0/{company}/OrganizationUnit), which is modestly useful for predicting OData behavior, but says nothing about whether the result is a flat list or a nested tree despite saying 'hierarchy'.

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

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

Two compact sentences, front-loaded with the resource definition followed by the endpoint. No filler, though the 'hierarchy' phrasing without a flat-vs-nested clarification is a small cost in an otherwise tight description.

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 full schema coverage and complete safety annotations, the description covers the essentials for a simple read tool. The main gap is that 'hierarchy' is left ambiguous — an agent cannot tell whether the response is nested or flat, and no output schema exists to resolve that.

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

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

Schema description coverage is 100%, with $top, $skip, $count, $filter, $orderby and company_id each documented in-schema including an example filter. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

Specific verb plus resource ('List the organization hierarchy units') with parenthetical examples (departments, divisions, cost centres) that disambiguate what an 'organization unit' is. It does not explicitly contrast with the closest sibling, payspace_list_organization_positions, but the resource naming is distinct enough that an agent can separate 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?

Purpose implies when to call it (discovering org units for filtering employees/positions), but there is no explicit guidance about when to prefer this over payspace_list_organization_positions or payspace_list_companies, and no prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the concrete endpoint and the fact that both frequency and period are mandatory scoping inputs, but says nothing about return shape, result volume, or failure modes.

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

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

Two sentences plus an endpoint reference, with the scope constraint front-loaded ahead of the prerequisite guidance. The trailing raw OData path is somewhat redundant but adds little cost.

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

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

For a read-only paged list with full schema coverage and annotations, the description supplies scope, prerequisites and the underlying resource. Nothing essential for correct invocation is missing, though paging behavior is left entirely to the schema.

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

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

Schema coverage is 100% and every parameter including top/skip/count/filter/orderby/company_id is already documented in the schema. The description only restates the sourcing of frequency and period, which the schema also says; baseline 3 applies.

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

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

States a specific verb+resource (list payroll components: earnings, deductions, contributions) scoped to one payroll frequency and run, and even names the backing endpoint. An agent can distinguish it from payspace_list_recurring_components and payspace_list_payslip_lines 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?

Explicitly states where the two required values come from ('get frequency from payspace_list_payroll_frequencies and period from payspace_list_payroll_runs'), which is actionable routing to prerequisites. It does not, however, contrast with alternatives or state 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds that this is a lookup endpoint (small, stable result set) and gives the raw path, but says nothing about result size, caching value, or paging behavior beyond the endpoint hint.

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

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

Three short sentences: purpose first, downstream use second, technical endpoint last. Everything is load-bearing, though the raw GET path is of limited value to an agent that already has the tool bound.

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

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

No output schema exists, but for a small lookup list the description conveys enough: what it returns (company payroll frequencies) and how the values are consumed. The only gap is that it doesn't describe the shape of returned items (code vs. name/id), which would matter for constructing the downstream `frequency` argument.

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

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

Schema description coverage is 100%, with $top/$skip/$filter/$orderby and company_id already documented in detail. The description adds no parameter-level guidance (e.g. whether filtering is useful on a small lookup), so baseline 3 applies.

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

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

Specific verb plus resource ('List the payroll frequencies of a company') with the underlying entity named (CompanyFrequency lookup) and the exact endpoint. It is clearly distinguishable from generic list siblings because it identifies itself as a lookup feeding a foreign-key argument.

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

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

Explicitly states the downstream use: values go into the `frequency` argument of payspace_list_payroll_components, payspace_list_payroll_runs and payspace_list_recurring_components. It doesn't explicitly say 'call this first if you don't already have a frequency id', but the implication is strong and the alternatives are named.

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, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered and the description doesn't need to repeat it. It adds modest behavioral context by exposing the GET /odata/v2.0/{company}/Lookup/CompanyRun endpoint and that frequency is a mandatory scoping dimension (one frequency per call). It says nothing about result size, default paging, or what the returned records look like.

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

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

Two compact sentences with the purpose front-loaded and the downstream-consumption note second. The raw endpoint string '(GET /odata/v2.0/{company}/Lookup/CompanyRun?frequency=)' is developer-facing filler for an agent and ends in a dangling '?frequency=', which is minor waste but not harmful.

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

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

With 100% schema coverage, no output schema, and annotations covering safety, the description supplies what's needed: what is listed, the scoping dimension, and how the results are consumed. It could say more about the shape of the returned period objects (e.g., id vs. label) and that results are capped at 100 per page, but nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all seven parameters are already documented, setting a baseline of 3. The description adds genuine semantics the schema lacks: the frequency parameter maps to a specific lookup entity (CompanyFrequency/CompanyRun) and the returned values are valid `period` arguments for two named sibling tools, explaining why frequency is required.

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

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

States a specific verb and resource ('List the payroll runs (periods) of a company for one frequency') and identifies the underlying entity ('the CompanyRun lookup'), which separates it from sibling lookups like payspace_list_payroll_frequencies. An agent knows exactly what comes back: run/period identifiers for a given frequency.

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

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

Explicitly tells the agent where the output goes: 'A value goes into the period argument of payspace_list_payroll_components and payspace_list_recurring_components', which makes the call ordering obvious. It does not state when not to use it or that the frequency argument should first come from payspace_list_payroll_frequencies (that routing only appears in the schema), so it stops short of a full 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds a genuinely useful behavioural signal by flagging 'Personal data (pay)', warning the agent it is handling sensitive compensation data, plus the underlying OData path for traceability. It does not discuss result volume or paging behaviour.

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

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

Two compact sentences plus an endpoint reference; the resource, its grain and the returned fields are front-loaded before the PII caveat. No filler.

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

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

With 8 parameters and no output schema, the description compensates by naming the returned fields (code, description, amount), which is the main thing missing from structured data. Paging and filtering behaviour are left entirely to the schema, which documents them well, so nothing critical 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 100%, so every parameter including filter, orderby, top/skip and company_id is already documented in the schema. The description only restates the year/month scope and adds no syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (payslip lines) and defines the grain precisely: 'one per component per employee: code, description, amount'. It is clear what comes back, though it never explicitly contrasts with the sibling payspace_list_payslips, which is the nearest 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?

Usage is implied by the year/month scoping rather than stated: an agent can infer this is the tool for per-component pay detail for a given period. There is no explicit when-not guidance and no pointer to payspace_list_payslips as the summary-level alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld. The description adds two useful facts beyond that: the payload contains personal pay data, and the underlying GET path identifies the entity. It says nothing about paging behavior in practice, response size limits, or what a per-employee total actually aggregates.

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

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

Two short sentences with the scope front-loaded; nothing is padded. The raw endpoint path is arguably redundant, though it does hint at the entity name for building $filter/$orderby expressions, so it earns partial keep.

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 eight parameters, no output schema, and a paging-capable list endpoint, the description should say more about what comes back (fields per employee, whether totals include components/deductions) and how it relates to payslip_lines. It covers the entity and scope but leaves return shape and drill-down workflow 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 100%, so all eight parameters including $top/$skip/$filter/$orderby and company_id fallback are already documented in the schema. The description's "calendar year and month" restates the required params without adding syntax, format, or edge-case guidance, so baseline 3 applies.

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

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

States a specific verb and resource ("List employee payslips") plus the aggregation granularity ("totals per employee"), which implicitly distinguishes it from payslip_lines. It does not name any sibling tool explicitly, so the differentiation is inferred rather than stated.

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

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

Usage is implied by "totals per employee" and the required year/month scope, which suggests when a detail-line tool like payspace_list_payslips_lines would be better. But there is no explicit when-to-use statement, no exclusions, and no mention of prerequisites (e.g. needing company_id only in multi-company credentials is left entirely to the schema).

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

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

Annotations already cover read-only, idempotent, non-destructive and open-world behavior, so the bar is lower. The description contributes one genuinely additive behavioral note — that Employee-level entities contain personal data — but says nothing about rate limits, permissions, paging behavior past 100 records, or response shape. It also restates 'read-only', which the annotations already declare.

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 endpoint and personal-data warning are front-loaded and earn their place, but the 18-item entity list largely duplicates the schema enum character-for-character, making the sentence disproportionately long for the value added. Structure is functional but padded by redundancy.

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

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

With 8 parameters, no output schema and rich annotations, the definition is serviceable but leaves gaps: it does not describe the return shape (OData value array, @odata.count behavior when count=true), how paging terminates, or that valid filter/select field names differ per entity. For a generic multi-entity lister an agent would benefit from those specifics.

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

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

Schema coverage is 100%, so top, skip, count, filter, select, orderby and company_id are all documented in the schema; baseline 3 applies. The description adds no parameter meaning beyond the {company}/{entity} path template, and it simply repeats the entity enum verbatim rather than explaining anything the enum does not already convey.

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

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

States a specific verb (list) and resource (records of one of 18 named entity sets) and pins it to a concrete endpoint, GET /odata/v2.0/{company}/{entity}. The enumeration makes the tool's reach unambiguous, but it never explains how this generic catch-all relates to the dedicated sibling listers (payspace_list_employees, payspace_list_jobs, etc.), leaving that routing decision to inference.

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

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

The enum constrains where the tool applies, which implies usage, but the description contains no explicit when-to-use or when-not-to-use statement and never points at the sibling list tools as alternatives. An agent must deduce from the entity names alone whether this or a dedicated lister is the right call.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the description's job is to add context — and it does, flagging that the payload is personal pay data and exposing the underlying OData GET shape and employee-filter requirement. It says nothing about result size or how the entity choice changes the returned shape, which keeps it below a 5.

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

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

Four short, front-loaded clauses: what it lists, the scope constraint, the personal-data warning, the prerequisite lookups, then the raw endpoint. No filler, and the most decision-relevant information comes first.

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

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

For a 9-parameter, 4-required read tool with no output schema, the description covers entity semantics, the mandatory employee filter, and how to obtain frequency/period. It leaves the returned field set uncharacterized, which is tolerable given no output schema but still a gap.

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

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

Schema description coverage is 100%, so all nine parameters are already documented; the description only restates the entity choice and the employee_number filter requirement. It adds no syntax, format, or interaction detail (e.g., how top/skip/count behave with the filter) beyond the schema.

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

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

States a concrete verb (List) and two concrete resources (EmployeeComponent / EmployeeLoan) scoped to exactly ONE employee for a given frequency and run. The capitalized 'ONE employee' plus the frequency/run qualifiers let an agent separate it from company-wide siblings like payspace_list_payroll_components without opening a schema.

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

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

Gives explicit prerequisite ordering: fetch frequency from payspace_list_payroll_frequencies and period from payspace_list_payroll_runs before calling. It does not state when to prefer this over payspace_list_payroll_components or payspace_list_payslip_lines, so the alternative-selection guidance is inferential 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete OData path, which is useful but thin; it says nothing about pagination defaults, page-size limits, or result ordering that would help an agent drive the six query parameters.

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

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

Two short sentences with the purpose front-loaded and no filler. The endpoint path is slightly redundant with the annotations but does add locational context, so nothing is wasted outright.

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 six optional parameters, no output schema and a mutation-free profile already covered by annotations, this is minimally adequate. It never states what fields a region record contains or how many records to expect, so an agent must rely entirely on the schema and vendor docs.

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

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

Schema description coverage is 100%, and each parameter already carries its own OData explanation and examples, so the baseline of 3 applies. The description contributes no additional parameter meaning or cross-parameter guidance (e.g. how top/skip interact, or when count is worth requesting).

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

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

States a specific verb and resource ('List the company's regions') plus the underlying endpoint, so the agent knows exactly what entity is returned. It doesn't explicitly contrast with siblings, but the resource noun ('regions') is distinct from every sibling in the list, so confusion risk is low.

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, no prerequisites, and no mention of alternatives. The only implicit cue is that it is a plain list endpoint rather than a filtered lookup, which the agent must infer from the schema.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds only the underlying GET/OData endpoint and does not add meaningful behavioral context such as pagination expectations, authentication needs, or response characteristics beyond what annotations and schema provide.

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

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

The description is two short sentences and front-loads the purpose. The second sentence gives the underlying endpoint, which is concise though not essential for tool selection.

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 list tool with rich annotations and full parameter schema coverage, the description is sufficient for selection and invocation. It does not explain return fields, but no output schema exists and the tool's scope is narrow enough that this is a minor gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description does not add parameter-specific meaning beyond that baseline, so a 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 and resource: 'List employee suspension records.' It is clear enough to distinguish this tool from sibling list tools because 'suspension' is a unique resource, but it does not explicitly compare itself to any 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 explicit guidance about when to use this tool versus alternatives, and it does not mention prerequisites or exclusions. Usage is only implied by the tool name and resource.

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