Unkey MCP by usefulapi

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

Annotations already declare destructiveHint=true, so the description needn't restate the safety posture. Beyond that it adds nothing behavioral — no note on what the created namespace contains, side effects, or what is returned; the only extra content is a bare 'POST /v2/apis.createApi' restatement that carries no decision value.

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 first sentence is front-loaded and efficient. The second sentence restates the HTTP endpoint, which adds nothing an agent needs and dilutes the definition's brevity.

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 create tool with a fully documented schema and no output schema, the description is adequate to invoke it correctly. It is thin on the return value (e.g., the new API's identifier) and on any creation constraints, leaving modest gaps.

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

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

With a single parameter at 100% schema description coverage, the schema fully documents 'name' and the description adds no naming conventions, uniqueness rules, or format constraints. Baseline 3 applies when the schema does all the work.

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 ('Create a new API namespace') and adds the purpose 'to issue keys under,' which distinguishes it from sibling creators like unkey_create_key and unkey_create_identity. It stops short of explicitly naming those siblings, so it falls just below a 5.

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

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

The phrase 'to issue keys under' implies this is the prerequisite namespace for key creation, giving an implicit ordering hint. There is no explicit when-to-use vs. when-not-to-use guidance and no mention of alternatives, so this is minimum viable.

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 supply destructiveHint=true, so the description is not contradicted but also adds no safety, auth, or side-effect detail. It does contribute useful domain context (identities are the parent object for keys and rate limits), but it omits behaviorally important facts for a create call: whether duplicate externalId values conflict or are upserted, and what the call returns.

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

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

Front-loaded with the action and a tight one-line definition of the resource. The trailing 'Unkey: POST /v2/identities.createIdentity.' is a minor spec pointer that is somewhat redundant with the title 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 two-parameter create tool with full schema coverage this is nearly adequate, but with no output schema the description could reasonably say what a successful create yields (an identity id) and how duplicate externalIds are handled. Those gaps are what keep it at minimum-viable rather than 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% and both parameters are documented in-schema, so the baseline is 3. The description reinforces externalId's meaning by tying it to the 'end user or organisation' concept, but adds no format, constraint, or uniqueness semantics beyond what the schema already states.

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

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

The description states a specific verb and resource ('Create an identity') and then defines the domain entity itself: 'an end user or organisation that keys and shared rate limits attach to.' That definition is what separates this tool from unkey_create_key and unkey_create_api, so an agent can distinguish 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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The clause about keys and shared rate limits attaching to identities hints at a prerequisite relationship, but the agent must infer that on its own.

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 supply title and destructiveHint=true, so the description carries most of the burden. It does so well by disclosing the critical irreversible trait: the plaintext key is returned once and cannot be retrieved later unless recoverable is enabled. It still omits auth/permission requirements and prefix or expiry consequences, 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?

Two sentences with no filler, and the one-time-return warning is front-loaded immediately after the purpose. The trailing endpoint reference is compact and 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?

There is no output schema, so the description correctly compensates by describing what the response contains (the plaintext key, shown once). With all 11 parameters documented in the schema and destructiveHint declared, the agent has what it needs, though permission requirements and default behaviors aren't restated.

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, but the description adds genuine meaning for the recoverable flag by tying it to key retrievability, a consequence not stated in the schema. This lifts it above baseline, though the other ten parameters get no added interpretation.

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 ('Issue a new API key under an API') and names the parent resource, which separates it from siblings like unkey_create_api and unkey_create_identity. An agent can identify the operation 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?

Usage is implied by the operation itself (issuing a key), and the description adds the conditional 'unless recoverable is set', but it never states when to choose this over unkey_create_api or unkey_update_key. No exclusions or prerequisites are given beyond the single-return warning.

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 say destructiveHint=true, so the description carries real weight by disclosing the default soft-delete semantics ('stops working but stays queryable') and that permanent irreversibly erases the key. It stops short of noting auth requirements, whether a soft-deleted key can be restored, or rate limiting.

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 key behavior front-loaded; the trailing endpoint reference ('Unkey: POST /v2/keys.deleteKey') is mildly redundant metadata but does not obscure the main point.

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 destructive mutation with no output schema, the description covers the critical behavioral facts: what the default does, what permanent does, and that soft-deleted keys remain queryable. Missing return-value and permission details are minor given no output schema exists.

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

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

Schema description coverage is 100% and the schema already documents both keyId and permanent, including the 'defaults to false' note. The description's explanation of permanent duplicates the schema rather than adding new 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 ('Revoke a key') and immediately scopes it with the soft-delete vs permanent distinction, which clearly separates it from siblings like unkey_update_key or 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?

The description explains the default behavior (soft delete) and the permanent option, which implies intent, but it never states when to prefer this over alternatives such as disabling via update_key or when a hard delete is warranted. Usage is inferable but not explicit.

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

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

The annotation already declares readOnlyHint=true, but the description adds the genuinely non-obvious disclosure that the underlying call is a POST yet still read-only — exactly the kind of transport quirk an agent would otherwise get wrong. It also names the raw endpoint (POST /v2/apis.getApi) for direct API callers.

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, followed by the behavioral caveat and the endpoint mapping. 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 trivial one-parameter read tool with annotations covering safety, the description is essentially sufficient. The only omission is any hint at the response shape (no output schema exists), which is minor for a single-resource fetch.

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 single apiId parameter is fully documented in the schema with its format (api_...). The description only restates the lookup-by-id behavior, 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) plus resource (API namespace) and the lookup key (by id), which cleanly separates it from unkey_create_api and the unkey_list_* siblings. An agent can identify the operation 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?

'by id' implies the preconditions (you must already have an api_... identifier), and the sibling set contains no other single-API getter to disambiguate against. There is no explicit when-to-use or when-not-to-use statement, so usage is only implied.

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

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

'Read-only despite being a POST' is genuinely valuable beyond the readOnlyHint annotation — it pre-empts an agent hesitating over the POST verb, and it is consistent with (not contradictory to) the annotation. The description also discloses the return payload (metadata, shared rate limits), which matters since there is no output 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 short clauses, front-loaded with the resource and scope, then safety context, then the API binding. 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 one-parameter read with no output schema, the description covers purpose, return content, and the POST/read-only nuance, which is nearly everything an agent needs. It stops short of enumerating what 'metadata' or 'shared rate limits' contain, but that 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?

The single parameter has 100% schema description coverage ('The identity's external id or Unkey id.'), so the schema already carries the semantics. The description adds no format or lookup details beyond it, making the 3 baseline 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'), a singular resource ('a single identity'), and names what the response includes ('its metadata and shared rate limits'). The word 'single' cleanly differentiates it from the sibling 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?

Usage is implied by 'single identity' plus a required identity id, but no condition is given for choosing this over unkey_list_identities or the other get_* siblings, and no prerequisites are stated. Minimum-viable routing guidance only.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuinely useful context by reconciling the surprising transport: 'Read-only despite being a POST.' That preempts an agent misjudging the call as a mutation. It stops short of describing error behavior or the decrypt caveat runtime implications.

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 trace. The return fields are front-loaded, the read-only clarification follows immediately, and nothing is redundant with the schema.

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

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

With no output schema, the description compensates by enumerating the returned metadata fields, and the read-only-via-POST note closes the main behavioral question. Nothing an agent needs to invoke this two-param read correctly is missing.

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

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

Schema description coverage is 100% — both keyId (id not secret) and decrypt (only for recoverable keys) are fully documented in the schema. The description adds no further 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 ('Fetch a key's metadata by its key id') and enumerates the returned fields (name, owner, permissions, credits, rate limits, enabled). An agent can distinguish it from list-style siblings, though it does not explicitly name near-neighbors like unkey_whoami_key or unkey_list_api_keys.

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

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

Usage is implied by 'by its key id' — this is the single-key lookup — but there is no explicit when-to-use guidance or contrast with unkey_whoami_key (current key) or unkey_list_api_keys. An agent must infer the routing decision from the tool name and fields.

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 structurally. The description's note that it is "Read-only despite being a POST" is genuinely useful context that resolves the apparent verb mismatch, but it does not disclose not-found or error behavior for a tool whose whole purpose is retrieving an item that may not exist.

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 action and scope, with the read-only caveat immediately after. The trailing endpoint reference is mildly redundant with the tool 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 two-parameter read with full schema coverage and a readOnly annotation, the essentials are present. However, with no output schema, the description should indicate what is returned when no override exists (null vs error), and it does not.

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 both parameters are already documented in the schema. The description restates that the identifier lives in a namespace but adds no format, casing, or lookup semantics beyond what the schema 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 (rate-limit override) scoped to "one identifier in a namespace." The word "one" implicitly distinguishes it from unkey_list_ratelimit_overrides, but the sibling is never named, so the differentiation is left 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 implied by the singular scope: call this to read a single override, list_ratelimit_overrides for many. There is no explicit when-to-use statement, no mention of prerequisites, and no exclusions (e.g., what to do when the override may not exist).

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; the description adds the genuinely useful disclosure that the transport is a POST yet the operation is read-only, which prevents an agent from misreading the method as a mutation. It stops short of covering auth needs, rate limits, or pagination behavior beyond the cursor parameter.

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 no filler; the scope and the read-only caveat are both front-loaded. Every clause carries information the agent needs.

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 carries the burden of describing what comes back, and it says nothing about the shape of the key list or how the cursor is returned. For a four-parameter paginated list tool with no annotations beyond readOnlyHint, this is adequate but incomplete.

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 schema already documents apiId, limit, cursor, and externalId; baseline 3 applies. The description mirrors the externalId filter ('narrowed to a single customer') but adds no syntax, format, or defaulting detail beyond what the schema provides.

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 every key') plus its scoping constraint ('issued under one API'), which cleanly separates it from unkey_get_key (single key) and unkey_list_identities. The optional externalId narrowing is called out up front, so an agent can tell what this returns without opening the schema.

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

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

The description implies when to reach for this tool (you want the full key set for an API) and shows how to narrow results with externalId. However, it never names an alternative or states exclusions, so the agent is left to infer that unkey_get_key is for a single key rather than being told.

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

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

The annotation only supplies readOnlyHint=true; the description adds the genuinely non-obvious context that the underlying call is a POST yet still read-only, which prevents an agent from mis-classifying it as a mutation. It does not describe pagination behavior or the shape of results, so it stops short of full disclosure.

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 with no padding; the resource definition and the read-only caveat both appear before the low-value endpoint restatement.

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

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

For a simple read-only list tool with a fully documented schema, the description covers purpose and the POST/read-only oddity. It is slightly incomplete in not indicating what a returned identity contains or that results are cursor-paginated, but nothing blocks correct invocation.

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

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

Schema description coverage is 100% (limit, cursor, and search are all documented in the schema), so the baseline is 3. The description adds no meaning about filtering or paging beyond what the schema already states.

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

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

States the specific verb (list) and resource (identities), then defines the resource as 'the end users or organisations your keys belong to' — which cleanly separates it from siblings like unkey_list_api_keys, unkey_list_roles, and unkey_get_identity.

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

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

No when-to-use or when-not-to-use guidance: it never says to prefer unkey_get_identity for a single identity or unkey_list_api_keys for keys. Usage is only inferable from the name and the definition of 'identity'.

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

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

Annotations declare readOnlyHint=true, but the description adds genuinely new context: it warns that this read-only operation is exposed as a POST, which would otherwise mislead an agent into treating it as a mutation, and it pins the underlying endpoint (POST /v2/permissions.listPermissions). It does not describe return shape or paging behavior 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 short sentences with no filler: purpose first, then the non-obvious safety caveat, then the endpoint mapping. Every clause earns its place and nothing is buried.

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 a fully documented parameter schema and readOnlyHint=true, the description covers what an agent needs: what is listed, that it is safe, and the real HTTP method. Only minor gaps remain (result volume, whether search is case-insensitive).

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, cursor, search all documented in-schema), so the baseline is 3. The description adds nothing about parameter usage such as search matching semantics or default page size, leaving the schema to do all the work.

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) scoped to the workspace, which cleanly separates it from the sibling unkey_list_roles and the list_* family. It stops short of explicitly naming a sibling or alternate, so it lands at clear-but-not-differentiating.

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 / when-not-to-use guidance, no mention of alternatives (e.g. unkey_list_roles), and no statement about pagination workflow beyond what the cursor parameter schema already says. The agent gets the purpose but no routing logic.

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

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

Annotations already declare readOnlyHint=true, so the safety bar is lower, yet the description adds genuinely useful context by noting it is read-only despite being a POST and naming the underlying endpoint. It stops short of describing pagination or result ordering.

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 resource and scope front-loaded, followed by the read-only clarification. No redundant or filler content.

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

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

With no output schema, the agent gets no description of the returned override shape or pagination continuation behavior, though the read-only annotation and endpoint reference cover the safety profile. Adequate but leaves return-format gaps.

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

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

Schema description coverage is 100%, so limit, cursor, and namespace are fully documented in the schema itself. The description adds no further parameter meaning, matching the baseline for high-coverage schemas.

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) plus resource (per-identifier overrides) and scopes it to a single rate-limit namespace. This cleanly separates it from the singular unkey_get_ratelimit_override and the mutation unkey_set_ratelimit_override.

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 namespace-scoped listing wording implies when it is used (to enumerate overrides) but never states when to prefer it over unkey_get_ratelimit_override or lists any exclusions/prerequisites. Usage is inferable but not explicit.

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

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

The line 'Read-only despite being a POST' is genuinely additive: it pre-empts an agent's natural inference that POST implies a mutation, and it is consistent with readOnlyHint=true. The endpoint mapping (POST /v2/permissions.listRoles) adds further context. It stops short of describing pagination or return behavior, but the safety profile is clear.

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 purpose front-loaded and no filler. The POST/read-only caveat and endpoint reference are compressed into a single clause each, so every element earns its place.

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

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

For a read-only list tool with no output schema or required parameters, the description covers the essentials: what it lists, its scope (workspace), and its safety profile. Only return shape and pagination expectations are unaddressed, which is acceptable given the schema documents the cursor contract.

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 documented in the schema, including their ranges and pagination semantics. The description adds nothing beyond that, which is the expected baseline when the schema carries the full parameter burden.

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

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

States a specific verb and resource ('List the roles defined in the workspace'), which is unambiguous about what the tool returns. It does not, however, differentiate itself from adjacent siblings like unkey_list_permissions or unkey_list_identities, so an agent must infer the boundary between roles and permissions.

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, or alternative routing guidance. Nothing tells the agent whether roles are the same as permissions or which sibling to pick when the desired object is ambiguous.

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

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

With readOnlyHint=true already declaring the safety profile, the description still adds real context: it discloses that the call validates the root key's validity, not just network reachability, and that it is a GET with no mutation semantics. It does not mention rate limits or failure behavior, which would be the remaining gap.

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

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

Three short, front-loaded sentences with no filler; the operative content ('reachable and the root key works') leads. The trailing 'Unkey: GET /v2/liveness.' partly repeats the tool name and adds little an agent cannot infer, costing it a point.

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 trivial zero-parameter tool this is close to sufficient, but no output schema exists, so the description carries the burden of explaining the response and it does not: an agent cannot tell whether success returns a boolean, a status object, or simply an HTTP 200. What is checked is clear; what comes back is not.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it does not falsely imply any inputs.

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 (check) and precise subject matter (API reachability plus root-key validity) rather than restating the title 'Check API health'. It is unmistakably distinct from all CRUD siblings such as unkey_get_key or unkey_create_api, which an agent can see 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?

It implies diagnostic usage ('reachable', 'root key works') and hints at minimal scope with 'The only GET in the v2 surface', but never states when an agent should call it (e.g., before a batch of calls, or to validate credentials after a 401). No alternatives or exclusions are offered, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely useful behavior beyond that: the alias whitelist, rejection of physical table names, and workspace scoping of results. It stops short of disclosing row limits, timeouts, or result caps, which matter for an arbitrary SQL endpoint.

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 sentences, front-loaded with the operation, then the hard constraint (allowed aliases), then the rejection rule and scoping. No filler and nothing repeated from 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?

For a single-parameter SQL tool with no output schema, the description covers what an agent must know to construct a valid query. The remaining gap is the shape/limits of results (row caps, pagination), which is a minor omission since output is query-dependent.

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 coverage the baseline is 3, but the description adds meaning the schema lacks: the exact set of legal FROM aliases and the fact that physical table names will be rejected. The schema's example query is complemented rather than duplicated.

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 (run a read-only SQL query) and resource (key-verification analytics), plus the Unkey endpoint it maps to. This clearly separates it from the CRUD siblings (create/get/update/delete key, identity, api), none of which touch analytics.

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 target one of five named public aliases, physical default.* tables are rejected, and results are workspace-scoped. It does not need to route to a sibling since no other analytics tool exists, but it also doesn't state any limits on query complexity or result size.

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 destructiveHint=true annotation already signals that this overwrites existing configuration, and the description's use of 'override' is consistent with that rather than contradicting it. However, it adds little beyond the annotation: it does not say whether a prior override is replaced or merged, whether the override can later be removed, or what permissions are required.

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

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

A single front-loaded sentence carries the meaning with no wasted words. The trailing 'Unkey: POST /v2/ratelimit.setOverride.' is endpoint plumbing of marginal value to an agent, which keeps it just 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?

For a four-required-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers what it does but not the operational consequences: what happens to an existing override, reversibility, or expected response. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, with all four parameters (namespace, identifier, limit, duration) documented including units ('per window', 'milliseconds'). 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 (Set) plus resource (rate-limit override) and narrows scope to 'one identifier in a namespace', which cleanly separates it from the get/list ratelimit_override siblings. The added gloss 'how you raise or lower a single customer's limit' removes any ambiguity about intent.

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

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

The phrase 'raise or lower a single customer's limit' implies when this tool is relevant, but there is no explicit guidance on when to prefer it over the namespace default, nor any mention of reading overrides first via unkey_get_ratelimit_override or listing them. Usage is inferred 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 destructiveHint=true, so the safety bar is lower, but the description adds nothing beyond that: it does not disclose that roles, permissions and metadata are wholly replaced rather than merged (that nuance lives only in the schema), nor mention auth requirements or reversibility. It largely repeats the field list and the HTTP endpoint.

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 mutation's scope. The trailing 'Unkey: POST /v2/keys.updateKey' is low-value for an agent choosing the tool, but it 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 an 8-parameter mutation with full schema coverage and a destructiveHint annotation, the description covers what can change but omits when to use it and the replace-semantics caveat that matters for destructive edits. No output schema exists, so return values need not be described, but the guidance gap keeps this at minimum viable.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters with their formats (e.g. expires as Unix ms, externalId as identity reassignment). The description restates the field names but adds no syntax or constraint detail 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 ('Change a key's ...') and enumerates the mutable attributes, and the update verb cleanly separates it from the create/get/delete siblings. Minor imprecision: it says 'owner' while the schema parameter is 'externalId' ('Reassign the key to this identity'), so the field list is not an exact one-to-one match.

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

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

There is no guidance on when to use this versus alternatives (e.g. unkey_update_key_credits, unkey_set_ratelimit_override) and no stated prerequisites such as required permissions or the fact that keyId must already exist. Usage is only implied by 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 flag destructiveHint=true, so the mutation risk is covered structurally. The description adds the meaningful semantic that omitting value with operation=set produces an unlimited key, but says nothing about whether credits can go negative, what happens on decrement below zero, or what the call returns.

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

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

Two short sentences, front-loaded with the capability and the special case, with no filler. The trailing endpoint reference is redundancy for an agent but is short and consistent with the server's naming convention.

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 small three-parameter mutation with fully documented schema and no output schema, the description covers the operation modes and the unlimited edge case. Missing only boundary behavior (negative credit handling, response shape), which is minor given the annotation already signals destructiveness.

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 schema already documents keyId, value, and operation, including the unlimited-on-omission behavior that the description repeats. The description adds no syntax or format detail 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?

Starts with a specific verb triple (set/increment/decrement) on a named resource (a key's remaining credits), which clearly separates it from the generic sibling unkey_update_key. It does not name that sibling explicitly, but the 'credits' scope makes the distinction inferable.

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

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

The second sentence gives a concrete usage rule for one mode ('use set with no value for unlimited'), which is genuinely helpful. However there is no guidance on when to choose increment vs set vs decrement, and no statement of when this tool should not be used instead of unkey_update_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 provide only readOnlyHint, so the description carries real weight here and delivers: it discloses two non-obvious side effects (no credit consumption, no verification recorded) that an agent would otherwise have to guess. It also sketches the return shape, which matters because there is no output 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: the core behavior leads, the safety/context claim follows, and the endpoint mapping is a compact trailing reference. 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?

For a one-parameter read tool with no output schema, the description gives enough: what goes in, what comes back at a high level, and the notable absence of side effects. Only the exact response fields remain unspecified, which is a minor gap for a lookup.

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

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

Single parameter at 100% schema description coverage, so the schema already documents it fully ('The plaintext API key to identify'). The description restates 'plaintext API key' without adding format, prefix, or validation semantics. Baseline 3.

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+input shape: 'Given a plaintext API key, return which key it is and its metadata.' The plaintext-secret input implicitly separates it from unkey_get_key, but no sibling is named, so the differentiation is left 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?

'This is the safe way to identify a key a customer sent you' gives a concrete use context, and 'without spending credits or recording a verification' implies the verify path is the alternative. It never names that alternative tool or states an explicit when-not condition, so it stops short of a 5.

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