unkey

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

Annotations supply destructiveHint=true, so the mutation profile is covered. The description adds only that the created resource is a namespace for keys; it says nothing about permissions/auth requirements, whether the name must be unique, or what a failure looks like. Endpoint string 'POST /v2/apis.createApi' restates the action rather than adding behavior.

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

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

Two short sentences, front-loaded with the action and resource. The API-endpoint fragment is redundant with the name but costs little.

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 create tool with annotations covering the mutation hint and no output schema, the description is minimally adequate. It omits any note about what is returned (an API id needed for subsequent key creation), which is the main practical 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?

Only one parameter with 100% schema description coverage ('The API name.'). The description adds no format, uniqueness, or constraint details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new API namespace') and adds clarifying scope ('to issue keys under'), which implicitly distinguishes it from sibling unkey_create_key. Clear enough to select without opening the schema, though it does not explicitly name 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?

No explicit when-to-use guidance or alternatives are given. The reader can infer this must precede unkey_create_key, but the description never states that dependency or any prerequisites.

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

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

Annotations provide destructiveHint=true, so the safety signal is covered structurally, but the description adds no behavioral context on top: no mention of idempotency of externalId, no auth/permission requirements, no statement of what is returned. For a mutation tool with no output schema, this 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 short sentences, front-loaded with the verb and resource, then the concept definition. The trailing "Unkey: POST /v2/identities.createIdentity." is routing metadata of marginal value to an agent already given the tool, but it is not harmful padding.

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

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

The tool is simple (2 params, 1 required, no output schema), and the description covers the core concept. However it omits what the call returns (an identity id presumably) and any interaction rules with sibling tools, leaving an agent to guess at the post-creation workflow.

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% — both externalId ("Your own id for this user or organisation") and meta ("Arbitrary JSON metadata") are documented in the schema itself. The description adds nothing about parameters, so the baseline 3 applies; it neither compensates nor detracts.

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 ("Create an identity") and goes further by defining what an identity is — "an end user or organisation that keys and shared rate limits attach to" — which is genuinely useful domain context. It does not explicitly distinguish itself from siblings like unkey_create_key or unkey_create_api, though the domain definition implies the relationship.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. The agent is not told that an identity must exist before keys or rate limit overrides can attach to it, nor whether to prefer unkey_create_identity over unkey_update_key workflows. Usage is left entirely to inference from the noun definition.

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?

Adds genuinely useful behavioral context beyond the sparse annotations: the plaintext key is returned ONCE and cannot be retrieved later unless recoverable is set. This signals an irreversible/one-shot property that an agent must handle carefully. It does not contradict the destructiveHint annotation.

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

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

Two tightly written sentences with the critical one-shot key behavior front-loaded before the API endpoint notation. No wasted words.

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

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

For an 11-parameter create tool with no output schema, the description covers the essential behavioral contract (one-time key return, recoverability) that the annotations and schema cannot. It leaves usage routing and permission requirements unstated, but the core information for correct invocation is present.

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

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

Schema description coverage is 100%, so all 11 parameters (meta, prefix, expires, byteLength, roles, etc.) are already documented in the schema. The description only reinforces the recoverable flag and adds no syntax or format detail beyond it; 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 ('Issue') and resource ('a new API key') with scope ('under an API'). An agent can distinguish this from sibling creators like unkey_create_api and unkey_create_identity without opening any schema.

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

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

The description explains behavior but never says when to use this tool versus alternatives or prerequisites (e.g., needing an existing apiId, or choosing this over unkey_create_identity). Usage is only implied by the tool name and the word 'Issue'.

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 tell the agent destructiveHint=true; the description adds the crucial detail that the default is a soft delete where 'the key stops working but stays queryable' and that permanent truly erases it. That is real behavioral context beyond the annotations, though it omits reversibility of the soft delete and any auth/permission requirements.

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

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

Two tight sentences with the action and default behavior front-loaded, then the permanent alternative, then a one-line API mapping. No filler or repetition.

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

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

For a two-parameter mutation with no output schema, the description covers what most agents need: the action, the default mode, and the destructive variant. Missing are return/confirmation behavior, whether the keyId must reference an existing key, and error semantics, but these are secondary.

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 meaning the schema lacks: it explains the consequence of the default (key still queryable) versus setting permanent (fully erased), which is the operative distinction for choosing a value. It does not add anything for keyId beyond what the schema already says.

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 ('Revoke a key') and goes further by defining the default mode and the alternate mode (soft vs. permanent erase). It is unambiguous what the tool does, though it never names or contrasts a sibling (e.g., unkey_update_key or unkey_get_key), so routing relies on the agent inferring delete-vs-update from the verb.

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

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

Usage is only implied: you revoke when you want a key to stop working. The description does give mode-selection guidance ('pass permanent to erase it'), which is genuinely useful, but there is no when-not-to-use, no prerequisites, and no pointer to alternatives such as disabling via update.

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, but the description adds genuinely useful context: the operation is read-only despite being issued as a POST, and it maps to the vendor endpoint POST /v2/apis.getApi. That prevents an agent from treating the HTTP method as a mutation signal. It stops short of describing return shape or error behavior.

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

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

Two short sentences with zero waste, front-loading what the tool fetches before the behavioral caveat.

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 lookup whose safety profile is covered by annotations and whose return values are not schematized, the description is essentially complete. A brief note on what the returned namespace contains would push it to a 5.

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?

Only one parameter (apiId) exists and the schema already documents it at 100% coverage, including the api_ prefix format. The description's 'by id' adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Fetch') and resource ('API namespace') plus the lookup key ('by id'). This is clearly distinct from sibling getters like unkey_get_identity and unkey_get_key.

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

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

Usage is implied by the name and the 'fetch by id' framing, and the note about it being a read-only POST helps an agent not misclassify it. However, there is no explicit when-to-use versus alternatives such as unkey_list_api_keys or unkey_get_key.

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 reinforces this with the valuable clarification 'Read-only despite being a POST', which preempts an agent's hesitation about a mutating-looking HTTP method. It adds no auth or rate-limit context, but the read-safety profile is well covered.

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 the core action and scoping note; every sentence earns its place with no padding.

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

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

For a simple one-parameter read with no output schema, the description adequately signals what is returned ('metadata and shared rate limits') and the read-only nature. Nothing essential is missing, though a brief note on id formats would help.

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% with a single documented 'identity' parameter, so the schema carries the load. The description adds no syntax or format detail beyond what is already structured.

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?

It states a specific verb and resource ('Fetch a single identity') and scopes the result to metadata and shared rate limits. The 'single' qualifier implicitly separates it from unkey_list_identities, though no sibling is named outright.

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

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

Usage is implied by 'single identity' versus the list siblings, but there is no explicit when-to-use/when-not guidance or named alternative. An agent must infer the selection rule.

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, but the description adds genuinely useful context beyond them: it warns that the operation is read-only 'despite being a POST', resolving a method/verb ambiguity the agent would otherwise face. It still omits auth requirements and rate-limit behavior, but the safety profile is well covered.

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

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

One dense sentence enumerating the returned fields, front-loading the primary action, followed by a short and valuable read-only note. The trailing 'Unkey: POST /v2/keys.getKey.' is mildly redundant framing but cheap and confirms the endpoint.

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

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

With no output schema, the description usefully enumerates the returned metadata fields (name, owner, permissions, credits, rate limits, enabled state). For a two-parameter read tool this is close to complete; only pagination/error or permission prerequisites are 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 coverage is 100% and both parameters (keyId, decrypt) are fully documented in the schema, including the important 'NOT the secret key itself' clarification and the recoverable-key constraint on decrypt. The description adds no parameter-level detail beyond what the schema already provides, 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 (fetch) and resource (a key's metadata by id) and enumerates the returned fields, so the agent knows exactly what it gets back. It does not, however, name or contrast with sibling lookups like unkey_whoami_key or unkey_get_identity, leaving sibling differentiation 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?

Usage is only implied — the agent can infer you call it when you already have a key id and need its metadata. There is no explicit when-to-use, no condition selecting it over unkey_whoami_key or unkey_list_api_keys, and no stated prerequisites.

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

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

Adds genuinely useful context beyond the readOnlyHint annotation: it discloses that the underlying call is a POST even though the operation is read-only, which prevents an agent from misreading the transport verb as a mutation. It still does not describe response shape or behavior when no override exists.

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

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

Three short sentences, all front-loaded: purpose first, then the POST/read-only caveat, then the endpoint reference. Zero 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 two-parameter read tool with full schema coverage and a readOnlyHint annotation, the description supplies everything needed to invoke it correctly. Only the return behavior (e.g., what happens when no override exists) is unaddressed, 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 coverage is 100%, with both namespace and identifier already documented in the schema. The description names neither parameter nor adds format/semantic detail, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (rate-limit override) scoped to one identifier in a namespace. The singular 'one identifier' implicitly distinguishes it from unkey_list_ratelimit_overrides and unkey_set_ratelimit_override, though it never names those siblings explicitly.

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

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

Usage is implied rather than stated: you call this to read the override for a specific identifier. There is no explicit when-to-use vs when-to-list/set guidance, and no prerequisites mentioned, leaving the agent to infer the choice from the singular scope.

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, but the description adds the genuinely useful disclosure 'Read-only despite being a POST,' reconciling the HTTP verb with safe-read semantics. It does not cover rate limits or result shape, but this is a meaningful addition beyond the annotations.

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

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

Two tight sentences plus an endpoint tag, front-loaded with the list scope and the optional narrowing before the HTTP-method caveat. 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?

There is no output schema, so the description could say more about pagination/return shape, though the cursor parameter hints at paging. For a straightforward list tool it is largely complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description only echoes externalId filtering semantics, adding little beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (List), resource (every key issued under one API), and scope (optionally narrowed to a single customer by externalId), which cleanly separates it from unkey_get_key and unkey_list_identities.

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

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

The description implies when to use it via the externalId narrowing condition, but it never names an alternative tool (e.g., unkey_get_key for a single key) or states when not to use it. Usage is inferable but not spelled out.

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, but the description adds genuinely useful context by flagging that the tool is 'Read-only despite being a POST' — resolving an apparent contradiction an agent might otherwise infer from HTTP-method conventions. It gives no pagination or result-volume behavior, but that is largely covered by the schema.

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

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

Two short sentences with zero waste; the core purpose and the critical read-only caveat are both front-loaded. Nothing is repeated from the title or annotations verbatim.

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 3-param, zero-required list tool with full schema coverage, readOnlyHint annotations, and no output schema, the description covers purpose and the POST/read-only quirk adequately. It could say more about pagination flow (cursor round-tripping), but that is documented in 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%, with limit (1-100), cursor, and search all documented in the schema. The description adds no parameter-level 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?

The description names a specific verb and resource ('List identities') and even clarifies what an identity is ('the end users or organisations your keys belong to') plus the underlying endpoint. It does not explicitly distinguish itself from unkey_get_identity or unkey_create_identity, relying on the verb to do that work, so it falls short of the sibling-differentiating bar.

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

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

Usage is only implied: listing implies enumeration, and the read-only note implies safe retrieval. There is no statement of when to pick this over unkey_get_identity (single lookup) or unkey_list_permissions, nor any exclusion or prerequisite 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 already declare readOnlyHint=true, but the description adds genuinely useful context beyond them: it explains that the underlying operation is a POST yet is still read-only, preempting a likely agent misread of the HTTP method. It does not cover pagination behavior or auth requirements, so not a 5.

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

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

Three short sentences, front-loaded with the purpose, followed by the behavioral caveat and the endpoint reference. Every sentence earns its place.

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

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

For a simple paginated read with full schema coverage and no output schema, the description covers purpose, safety semantics, and endpoint binding. Only minor gaps remain (no mention of return shape or default/max page size beyond 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%, so limit, cursor, and search are already fully documented in the schema. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (permissions) plus scope ('defined in the workspace'), making it immediately distinguishable from sibling list tools like unkey_list_roles and unkey_list_identities. No ambiguity about what is returned.

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

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

Usage is implied by the name and scope, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives such as unkey_list_roles. Adequate to select the tool but leaves routing to inference.

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

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

'Read-only despite being a POST' is a genuinely useful disclosure that reinforces and explains the readOnlyHint=true annotation, warning the agent off assuming a mutation from the HTTP verb alone. It does not, however, mention pagination/limit behavior, which the schema carries instead.

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 zero filler; the purpose and the read-only caveat are both front-loaded before the trailing API path reference.

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

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

For a three-parameter read-only list endpoint with full schema coverage, the description plus annotations cover what an agent needs to invoke it. With no output schema, a brief note on the returned shape would have closed 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 description coverage is 100%, so limit, cursor, and namespace are each documented in the schema already. The description adds no format or constraint detail 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?

Specific verb ('List') plus resource ('per-identifier overrides') and scope ('in one rate-limit namespace'), which implicitly separates it from the singular unkey_get_ratelimit_override sibling. It never explicitly names the sibling or states the list-vs-single distinction, so it falls short of the 5 bar.

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 choose this over unkey_get_ratelimit_override or unkey_set_ratelimit_override, nor any prerequisite or pagination-flow advice. Usage is left entirely to inference 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 readOnlyHint=true, but the description adds the valuable note that the operation is read-only despite being a POST, which prevents misinterpretation of the HTTP method. It also maps the tool to the API endpoint POST /v2/permissions.listRoles, providing useful transport context.

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

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

The description is short, front-loaded with the core purpose, and wastes no words. The endpoint attribution is slightly redundant metadata but still compact overall.

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 paginated list tool with no output schema, the description covers the operation, safety profile, and API mapping. It could briefly mention the response format or pagination behavior, but the schema already documents the pagination 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?

Schema description coverage is 100%, with limit, cursor, and search each documented directly in the input schema. The description adds no additional parameter 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?

States a specific verb and resource ('List the roles defined in the workspace'), making the operation unambiguous. It does not explicitly differentiate from siblings like unkey_list_permissions, so it falls 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?

Provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The listing action is implied but there is no explicit usage context.

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

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

Annotations already declare readOnlyHint=true, but the description adds a real behavioral trait: the check exercises the root key, so the agent knows this tool validates credentials and requires elevated auth. It does not describe failure signaling or return format, keeping it short of 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 short sentences, purpose front-loaded before the endpoint metadata. Every sentence carries information (what it does, what it validates, its unique position in the API), with no filler.

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

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

With no parameters, no output schema, and readOnlyHint already covering safety, the description covers nearly everything an agent needs. The one gap is that it never says what a healthy or failed response looks like, which matters slightly more given the absent 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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter surface for the description to clarify or omit.

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: verifying the Unkey API is reachable and that the root key authenticates. No sibling among the 19 tools overlaps with a health/liveness probe, so the agent can distinguish it immediately.

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 line 'The only GET in the v2 surface' implies this is a diagnostic probe, but the description never says when to call it (e.g., before a batch of writes, after credential rotation) or what to do on failure. Usage is implied rather than stated, though there are no competing alternatives to route away from.

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

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

The readOnlyHint annotation already declares the safety profile, and the description reinforces it with 'read-only SQL query'. It adds value beyond annotations by disclosing enforcement rules (alias-only, default.* rejected) and result scoping to the workspace. It does not mention rate limits, query cost, or timeouts, so it falls short of 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 dense sentences, front-loaded with the operation, then the hard constraint, then scoping, followed by the underlying endpoint for reference. Every sentence carries information; the trailing endpoint string is slightly extraneous but harmless.

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 SQL tool with no output schema, the description supplies the aliases needed to write a valid query and the rejection behavior to avoid. It stops short of listing available columns or return shape, which an agent must infer or discover, leaving a modest 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% with a single 'query' parameter, so the baseline is 3. The description exceeds that by enumerating the five legal alias names, which is a constraint the schema does not encode and which an agent must know to construct a valid query.

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: 'Run a read-only SQL query over key-verification analytics.' This is clearly distinguishable from every sibling, which are CRUD operations on keys, identities, APIs, permissions and roles. No ambiguity about what the tool returns conceptually.

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 constraints: the query must reference one of five named public aliases, and physical default.* table names are rejected. It also states results are workspace-scoped. It does not explicitly say when to prefer this over other analytics approaches, but no sibling competes for this use case.

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 supply destructiveHint=true, so the agent already knows this mutates state. The description adds the useful constraint that the override is scoped to a single identifier, but it does not say whether an existing override is overwritten (vs. only created), whether the call is idempotent, or what authorization/namespace existence is required.

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

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

A single front-loaded sentence that captures the operation and its scope with no wasted clauses. The trailing 'Unkey: POST /v2/ratelimit.setOverride.' restates the name/verb and is largely redundant, which keeps it short of 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?

All four required parameters are covered by the schema and the description establishes scope, so the core is complete. However, with no output schema and only a destructiveHint annotation, the description leaves return behavior and the create-vs-overwrite semantics unstated, which matters for a mutation tool.

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

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

Schema description coverage is 100% — limit ('requests allowed per window'), duration ('window length in milliseconds'), namespace, and identifier are all documented in the schema. The description adds no syntax, unit, or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (set a custom rate limit) and scopes it precisely to 'one identifier in a namespace', which distinguishes it from namespace-wide or per-key operations. It does not explicitly name the adjacent siblings (get_ratelimit_override, list_ratelimit_overrides), so the 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?

'How you raise or lower a single customer's limit' gives a use case, but there is no when/when-not guidance and no mention of checking an existing override first (get_ratelimit_override) or listing overrides. Usage is only implied by the scope wording.

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

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

Annotations already flag destructiveHint=true, so the safety profile is partly covered. The description adds an enumeration of mutable fields and the endpoint path, but does not disclose that omissions leave fields unchanged, that some fields are replaced wholesale, or what authorization is required for this mutation.

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 field list; nothing is padded. The trailing endpoint reference is of marginal value to an agent that already knows the tool name, but it is brief enough not to hurt.

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 8 parameters are fully described in the schema and destructiveHint covers the risk profile, so the description is broadly serviceable. However, for a mutation with replace-style fields and identity reassignment, the missing guidance on partial updates versus overwrites leaves a real gap.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents every parameter including the milliseconds expiry and the replace semantics of meta/roles/permissions. The description's term "owner" does not match any parameter name (externalId) and adds no syntax or format 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?

Names a specific verb (Change) and resource (a key) and enumerates the mutable fields, plus the underlying endpoint POST /v2/keys.updateKey, so the agent knows exactly what the tool does. It does not distinguish itself from the sibling unkey_update_key_credits, which could be confused with a general key update.

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 statement of when to use this versus unkey_create_key, unkey_delete_key, or unkey_update_key_credits. The need for an existing keyId is implied by the schema only, and no prerequisites or exclusions are given.

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

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

Annotations already declare destructiveHint=true, so the safety signal is present; the description adds meaningful semantic behavior for the unlimited case (omit value with operation=set). It does not, however, disclose whether decrement can drive credits negative, whether the change is reversible, or any auth requirements.

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

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

Two tight sentences front-load the core operation and the unlimited special case. The trailing 'Unkey: POST /v2/keys.updateCredits' endpoint reference is minor filler but does not obscure the meaning.

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

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

With only 3 params, full schema coverage, no nested objects, and an annotation covering destructiveness, the description gives enough to invoke the tool correctly. Missing only edge-case behavior (negative balances, error conditions), which is a modest gap for a simple mutation.

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 keyId, value, and operation are already documented in the schema. The description restates the unlimited-value rule that the value parameter's own description already covers, adding no new syntax or constraint detail. 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 set (set/increment/decrement) and resource (a key's remaining credits), which clearly separates it from the sibling unkey_update_key that handles key metadata. An agent can identify the operation and target 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?

Provides an explicit conditional rule: 'Use set with no value for unlimited.' However, it offers no guidance on when to prefer this over unkey_update_key or any prerequisites such as required permissions, so the routing context is only partial.

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, but the description adds two substantive behavioral traits: no credit consumption and no verification record created. Those billing and audit side-effect disclosures are exactly the context an agent needs before choosing between this and a verification call.

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

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

Two sentences, no filler, with the identifying behavior and the no-credits/no-audit guarantee front-loaded. The trailing 'Unkey: POST /v2/keys.whoami' is terse endpoint metadata rather than prose padding.

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

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

There is no output schema, and the description covers the return at a summary level ('which key it is and its metadata'), which is enough to set expectations. It could say more about the shape of the returned metadata, but nothing needed to invoke the tool correctly is missing.

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

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

With one parameter at 100% schema description coverage, the schema already documents 'key' as the plaintext API key to identify. The description reinforces the input form but adds no format, syntax, or validation detail beyond what the schema provides, 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 precise verb and resource: 'Given a plaintext API key, return which key it is and its metadata.' The qualifier 'plaintext API key' immediately separates it from ID-based lookups like unkey_get_key, so an agent can route correctly without opening either schema.

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

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

'This is the safe way to identify a key a customer sent you' gives a concrete usage context, and the contrast with 'recording a verification' implies the verification path is the alternative when credits/audit records are desired. It stops short of an explicit when-not or naming a sibling tool.

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