Quinyx MCP by usefulapi

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

Goes beyond the readOnlyHint annotation by disclosing that payroll/private fields are omitted and that the underlying API is v3preview1, which hints at preview-level stability. The required permission scope is also stated. It stops short of describing the returned shape, but the omissions notice is genuinely valuable for a read tool.

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

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

Four tight clauses, each carrying distinct information: capability, key format, permission requirement, field omissions, and API version. Nothing is padded and the core purpose leads.

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

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

For a one-parameter read tool with annotations covering the safety profile and no output schema, the description supplies the important surrounding context (auth scope, field redaction, API version). A brief indication of what the agreement metadata contains would close the remaining 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 coverage is 100% and the pattern already constrains the id to digits or the xrefId: prefix form. The description's "internal numeric ID or documented external reference" restates rather than extends that, offering no format or example detail beyond the schema.

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

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

States a specific verb and resource ("Read operational agreement metadata") and the lookup key (internal numeric ID or external reference). It clearly implies singular retrieval, which distinguishes it from quinyx_list_agreements, though the sibling is never named explicitly.

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

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

The required scope hr:agreements:read gives a usable precondition, and "by internal numeric ID" implies direct lookup. However, there is no explicit guidance on when to use this versus quinyx_list_agreements for discovery or search, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=true, and the description adds valuable context beyond that: the required scope (hr:employees:read) and the fact that payroll/private fields are omitted. It does not describe the return shape, but without an output schema that gap is minor for a simple read tool.

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

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

Two short sentences, front-loaded with the action and resource, followed by the access condition and data-scope caveat. Every sentence carries useful information with no 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 single-parameter read tool with annotations and full schema coverage, the description covers purpose, authorization, and data exclusions. It could be slightly more complete by explicitly directing users to list_employees when the ID is unknown, but nothing essential is missing.

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

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

Schema description coverage is 100%, and the single parameter is fully documented with pattern and format. The description's mention of 'internal numeric ID or documented external reference' restates the schema rather than adding new syntax or constraints, so baseline 3 applies.

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

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

The description states a specific verb and resource ('Read operational employee metadata') and clarifies the lookup modes (internal numeric ID or documented external reference). It distinguishes retrieval-by-ID from the sibling list operations, though it does not explicitly name those 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?

The description implies this is a single-record lookup by ID, contrasting implicitly with the list_employees sibling, and states the required permission. However, it does not explicitly say when to use this versus list_employees or how to discover an ID if 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?

readOnlyHint=true already covers the safety profile, so the description earns credit for adding real context beyond annotations: the required permission (organization:groups:read) and the fact that payroll/private fields are omitted from results. It stops short of describing the not-found behavior or response shape.

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

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

Three short sentences, with the addressing modes and the permission requirement front-loaded ahead of the field-omission caveat. No wasted clauses, though 'documented external reference' is slightly vague where 'xrefId' would be precise.

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

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

For a single-parameter read tool with readOnlyHint annotation and no output schema, the description covers the essential calling information: how to address the group, the needed scope, and the fact that some fields are withheld. The absence of return-value detail is the only meaningful 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 coverage is 100% and the schema already documents 'Internal numeric ID or xrefId:external-id', which the description essentially restates. It adds only the qualifier that xref IDs are 'documented', giving no extra format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Read operational group metadata') plus the two addressing modes, which is enough to distinguish it from a generic group operation. It does not explicitly name quinyx_list_groups as the listing counterpart, so sibling differentiation is left implicit.

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

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

'By internal numeric ID or documented external reference' implies you should use this when you already hold an identifier, and the required scope hints at prerequisites. However, it never says when to prefer this over quinyx_list_groups or what to do when you lack an ID.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real behavioral context by naming the required permission scope and disclosing that payroll/private fields are omitted from results. It stops short of describing error behavior or what happens when an xrefId does not resolve.

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, front-loaded sentences: what it reads, the permission gate, and the field-omission caveat. No filler and the most important identification detail 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 single-parameter read-only tool with no output schema, the definition covers identity, permission, and data-scope well. The only gap is that return shape is only hinted at via the 'payroll/private fields omitted' note rather than described.

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 id parameter's format and pattern are already fully documented. The description reinforces the two accepted forms (numeric ID vs documented external reference) but adds no syntax detail beyond what the schema states, 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 (read) and resource (operational role metadata) and constrains the lookup to an internal numeric ID or external reference. It implicitly separates itself from quinyx_list_roles by being a single-record fetch, but never names the sibling or explicitly contrasts 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 permission requirement ('Requires organization:roles:read') gives useful preconditions, and the scope note implies when this single-role read applies. However, there is no explicit guidance on when to use this versus quinyx_list_roles or quinyx_list_role_assignments, leaving the agent to infer from tool 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely non-redundant behavior: required auth scope, one bounded page per call with no automatic crawl, and an explicit allowlist of excluded sensitive fields (payroll, national IDs, contact/health info, free-text comments). It does not describe response shape or the maximum page bound beyond 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 tight sentences, each carrying distinct payload: capability, auth requirement, pagination contract, and data-scope boundary. The permission and pagination constraints are front-loaded before the allowlist note.

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

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

There is no output schema, so the description should convey more about what the returned metadata contains beyond 'data plus opaque pagination tokens'. Auth, pagination, and sensitive-field exclusions are well covered, but with 8 parameters and low schema coverage the filter semantics remain unexplained, leaving the definition 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 coverage is only 38%: groupId, pageSize, and pageToken are documented in the schema, but employeeId, templateId, badgeNumber, startDateLte, and endDateGte have no description in either place. The description reinforces pageToken semantics ('never a URL to follow' appears only in schema) but never explains what the five filter parameters do, so 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 a specific verb+resource: reading a bounded page of agreement scheduling metadata (v3preview1). This is clearly a paged list operation, distinct from quinyx_get_agreement by implication (page, tokens), but the description never explicitly contrasts with the single-object 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?

It gives the prerequisite (hr:agreements:read) and explains the pagination usage pattern ('pass pageToken for another page, no automatic crawl'). However, it offers no guidance on when to use this vs quinyx_get_agreement or how the optional filters (employeeId, templateId, badgeNumber, date range) select which agreements to retrieve.

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

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

Annotations only declare readOnlyHint=true, so the description carries real weight and delivers: the required hr:employees:read scope, the fact that pagination is manual via opaque tokens, and an explicit allowlist that excludes payroll, national IDs, private contact/health data and free-text comments. Missing only rate-limit or ordering guarantees to reach 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?

Three tight sentences, front-loaded with what the tool does, then auth, then pagination, then data boundaries. No filler and nothing redundant with the annotations.

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

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

With no output schema, the description correctly steps in to describe the return shape (data plus opaque pagination tokens). Scope and data-exclusion boundaries are covered; the only gap is the unexplained idIn filter, which an agent would need to use the tool's main filtering capability.

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

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

Schema coverage is 67% and the description only reinforces pageToken behavior, which the schema already documents as an opaque nextPageToken. The idIn array — a digit-string ID filter capped at 50 items — receives no explanation in either the schema or the description, leaving its filtering semantics ambiguous.

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 — 'Read one bounded page of scheduling employee details' — which is clearly distinguishable from single-record siblings like quinyx_get_employee and from quinyx_list_shifts. It does not explicitly name a sibling, 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?

Implies usage via the pagination guidance ('pass pageToken for another page, no automatic crawl') and the required scope, but never states when to choose this over quinyx_get_employee for a single record or how idIn filtering should drive selection. Usage is inferable rather than explicit.

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

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

Goes well beyond readOnlyHint=true: declares results are bounded to one page, that tokens are opaque and must be echoed rather than followed, that there is no automatic crawl, and lists the operational allowlist exclusions (payroll, national IDs, private contact/health data, free-text comments). This is the kind of safety/scope context an agent cannot infer from annotations.

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

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

Three tight sentences, each carrying distinct information: scope/verb, auth + pagination mechanics, and data-exclusion policy. Front-loaded with the core action, no filler.

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

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

For a read-only, no-output-schema list tool, the description covers auth, pagination contract, and data-exclusion policy. Minor gap: no indication of what fields a group record contains or how idIn narrows results, though the schema covers the latter.

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

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

Schema coverage is 67% and the description reinforces pageToken behavior (opaque, pass back for another page) without contradicting the schema. It says nothing about idIn filtering or pageSize bounds, which the schema itself documents, so the description adds only marginal value 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?

Names a specific verb+resource ('Read one bounded page of organization groups (including units/sections)') and clarifies that units/sections are the same resource. It is distinguishable from quinyx_get_group by the explicit 'page' framing, though no sibling is named.

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

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

Gives clear conditions: required scope organization:groups:read, and 'pass pageToken for another page, no automatic crawl', which tells the agent how to iterate. It stops short of naming alternatives like quinyx_get_group for a single group or quinyx_list_employees for filtering by member.

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

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

Goes well beyond readOnlyHint=true by disclosing the auth scope required, the bounded single-page behavior with no auto-crawl, and an operational allowlist that excludes payroll, national IDs, private contact/health data and free-text comments. That last point materially tells an agent what data will and will not come back, which the annotations cannot 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?

Three short sentences, front-loaded with what the tool does and the auth requirement, then pagination, then data-scope caveats. No filler or restatement of the title.

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 return shape is sketched ('data plus opaque pagination tokens') and data exclusions are covered, which is good for a tool with no output schema. However, with 10 optional filter parameters at 20% schema coverage, an agent still cannot tell how to construct a meaningful query, leaving a real gap for a list 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 description coverage is only 20% across 10 parameters, so the description must compensate, but it only explains pageToken iteration. The filter parameters (idIn, employeeIdIn, roleIdIn, groupIdIn, startDateGte/Lte, endDateGte/Lte) and pageSize get no explanation of semantics, including the overlap between idIn and employeeIdIn or what the date ranges filter on.

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 ('Read one bounded page of employee role assignments'), which is distinguishable from siblings like quinyx_list_roles and quinyx_list_employees. It never explicitly routes the agent away from those siblings, 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?

Gives concrete operational context: the required scope hr:role-assignments:read and the instruction to pass pageToken for further pages with 'no automatic crawl'. No when-not-use case or named alternative among the sibling list tools is provided, so it is clear context rather than full 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?

Annotations only declare readOnlyHint, and the description adds substantive context beyond that: the required organization:roles:read scope, the fact that pagination is caller-driven with no automatic crawl, and an operational allowlist that excludes payroll, national IDs, private contact/health data and free-text comments. That last point materially shapes what an agent can expect in the payload.

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

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

Four short sentences, front-loaded with the operation and scope, then paging, then data-exclusion policy. No repetition and every sentence carries distinct 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 two-param read-only list tool with no output schema, the description covers the permission prerequisite, the return shape in outline (data plus opaque pagination tokens), how to continue paging, and the data-exclusion policy. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so pageSize and pageToken are already documented, including that the token is opaque and never a URL. The description reinforces the pageToken usage ('pass pageToken for another page, no automatic crawl') but adds no format or boundary detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Read one bounded page of organization roles') and the paging scope makes it distinguishable from the single-record quinyx_get_role. It never names a sibling explicitly, so the list-vs-get routing is left implicit.

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 the required permission scope and explicit paging instructions ('pass pageToken for another page, no automatic crawl'), which tells the agent how to iterate. It stops short of stating when to prefer this over quinyx_get_role or quinyx_list_role_assignments.

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, and the description adds substantial context beyond that: a required schedule:shifts:read scope, opaque token pagination with no auto-crawl, an operational allowlist excluding payroll, national IDs, contact/health data and free-text comments, and an explicit no-writes/no-punches statement. This is exactly the behavioral disclosure an agent needs before calling.

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 purpose, then prerequisites, pagination, and exclusions in a compact paragraph with no filler. It is slightly dense and semicolon-packed, but every clause carries operational information.

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

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

For a read-only list tool with no output schema, the description covers auth, pagination, date-range constraints, and data-exclusion scope, and it notes the shape of the return (data plus tokens). The remaining gap is filter semantics for the optional ID/status parameters.

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 only 22% schema description coverage the description must compensate, and it does explain the required beginGte/beginLte window and the 93-day cap plus pageToken semantics. However, it is silent on idIn, statusIn, groupIdIn, employeeIdIn and deleted, leaving five of nine parameters with no guidance anywhere.

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 ('Read one bounded page of scheduled shifts'), and the resource (shifts) cleanly distinguishes it from every sibling, all of which operate on employees, groups, roles, or agreements. An agent can select it without opening the schema.

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

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

Gives concrete usage conditions: beginGte/beginLte are required here and must be at most 93 days apart, and continuation requires passing pageToken because there is no automatic crawl. It stops short of naming an alternative tool or stating when not to use it, so it lands just below the top band.

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