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

With no annotations, the description carries the full behavioral burden. It usefully discloses the HTTP call and approved=true plus return fields, but it omits permissions, error cases, idempotency, and other side effects of approving a clearance.

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 followed by implementation detail. There is no wasted text.

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

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

For a simple two-parameter approve action, the description covers purpose, endpoint behavior, and return fields despite there being no output schema. It is nearly complete, though authorization and failure behavior are still unstated.

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 id and note. The description only reiterates id through the endpoint path and does not add meaning beyond the schema, making 3 the appropriate baseline.

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: 'Approve a pending clearance.' The action is clearly distinguishable from siblings such as clearances_deny and clearances_revoke.

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 makes clear this is for approving a pending clearance, which gives adequate context. It does not explicitly name alternatives like clearances_deny, but the approve-vs-deny distinction is obvious from the verb and 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?

With no annotations, the description carries the burden well: it discloses the async human-in-the-loop model, that a human must open approval_url to approve or deny, and the two ways to observe the decision. It omits auth/permission needs, idempotency, and whether the call blocks until decision.

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, then requirements, then the return value and the follow-up flow. No filler sentences; every clause conveys actionable information.

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

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

No output schema exists, and the description compensates by naming the returned clearance and its key field (approval_url). The async decision flow is covered, but expiry behavior, error cases, and authorization requirements are left to the schema or unstated.

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

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

Schema coverage is 100%, so all eight parameters are already documented in the schema. The description only restates that title and scope are required and that callback_url is a decision-notification hook, adding little beyond the structured data. 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+resource: "Create a human approval request" tells the agent exactly what it makes, and the returned approval_url makes the outcome concrete. It is clearly distinguishable from the approve/deny/revoke/list/get siblings, which operate on an already-existing clearance.

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?

States the required inputs up front and gives explicit next-step routing: poll clearances_get or pass callback_url to learn the decision. It does not say when creating a clearance is inappropriate versus e.g. verify_token, so it falls just short of full when/when-not/alternatives coverage.

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?

No annotations are provided, so the description carries the burden. It does disclose the exact backend call (POST /v1/clearances/{id}/decide with approved=false) and that the note becomes the decision note, which adds real value. However, it omits irreversibility, required permissions, and behavior for non-pending clearances — notable gaps for a mutation tool.

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

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

Two tight sentences, zero filler, action and endpoint front-loaded.

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 no-annotation mutation tool with no output schema, the agent still lacks return information and side-effect/permission details, though the endpoint disclosure partially compensates.

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. The description only restates that the note is stored as the decision note, adding little beyond the schema text; 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 ('Deny a pending clearance') and even names the underlying endpoint and payload flag, so an agent can instantly distinguish it from clearances_approve or clearances_revoke.

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

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

The word 'pending' implies a state precondition, but the description never says when to prefer deny over revoke or approve, nor what happens if the clearance isn't pending. 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?

With no annotations, the description carries the burden and does disclose the return payload and a meaningful conditional behavior: the signed token is only exposed when status is approved. It omits error behavior for an unknown or revoked ID, required auth/scope, and whether token retrieval is audited or rate-limited.

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

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

Two short sentences, zero filler, with the action front-loaded and the return contract following. Every clause earns its place.

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

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

No output schema exists, so the description usefully enumerates the returned fields (status, approval_url, expiry, signed token) and the condition gating the token. A brief note on what happens for a missing/invalid ID would close the remaining gap.

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

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

Schema description coverage is 100% and the example format (clr_a1b2c3d4) is already documented in the schema, so the description adds nothing beyond it. Baseline 3 applies for a fully documented single parameter.

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

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

States a specific verb and resource ('Get one clearance by ID') and the singular framing distinguishes it from clearances_list. It does not explicitly name siblings, but the scope is unambiguous enough that an agent can select it without opening the schema.

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

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

Usage is only implied: the 'by ID' phrasing signals you need a known clearance ID, which implicitly rules out list-style discovery. No alternatives are named (e.g. 'use clearances_list to find an ID') and no prerequisites or exclusions are stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return type (JSON array), ordering (newest first), the API default page size of 50, and the key-scoping of results. It omits whether all statuses are returned by default and says nothing about pagination beyond the default limit.

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 purpose and then return behavior, with no filler. The trailing enumeration of status values duplicates the schema enum and is the one line that does not fully earn its place.

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

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

For a two-optional-parameter list tool with no output schema, the description supplies the essential return shape, ordering, and default limit that an agent needs to interpret results. Only pagination/cursor behavior and the default status coverage are missing.

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

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

Schema coverage is 100%, and the description largely restates what the schema already declares — the same five enum values and the same default of 50. It adds no filter-combination or format guidance, so 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 and resource ("List clearances") plus the scope ("for this API key"), which clearly distinguishes it from clearances_get, clearances_approve, and clearances_create. It stops short of naming those siblings explicitly, so an agent must infer the routing from the verb alone.

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

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

Usage is only implied: the word "List" plus optional filters signals a read/enumeration call, and the sibling names make the alternatives guessable. There is no explicit statement of when to use this versus clearances_get or when to prefer filtering by status over fetching all.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the key consequence that 'the signed token will no longer verify,' but omits whether revocation is irreversible, what permissions are required, or what happens if the clearance is not in an approved state.

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 followed by the endpoint and the consequence. Every sentence adds information and none is redundant.

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 mutation tool, the definition covers purpose, the underlying call, and the primary effect on token verification. It lacks error-state, idempotency, or permission context, which keeps it from being fully complete given the absence of annotations and output schema.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already fully documented as the 'Clearance ID to revoke.' The description adds no syntax or format 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 ('Revoke an approved clearance'), and the qualifier 'approved' implicitly separates it from sibling operations like clearances_deny or clearances_approve. It does not explicitly name those alternatives, so the differentiation is left partly 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?

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'approved clearance' implies the tool applies only to already-approved clearances, but that constraint is not spelled out against alternatives such as clearances_deny.

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 no annotations, the description carries the full burden and does well: it discloses that keys always start on the free Starter tier (50 clearances/month) and cannot be assigned a tier here, lists the exact return fields, and warns that the raw key is shown only once. It omits permissions/auth requirements and behavior when the email already has a key, so not quite complete.

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

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

Four short sentences, each front-loaded and earning its place: verb+resource first, then constraint, then return shape, then the one-time key visibility warning. 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 creation tool with no annotations and no output schema, the description supplies tier constraints, quota, return fields, and the irrecoverable raw-key behavior, which is enough to call it correctly. It lacks error/duplicate-email behavior and auth expectations, 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%, so both parameters are already documented. The description reinforces that email is required and clarifies that tier is deliberately not a parameter, but it does not add format or constraint detail beyond the schema (e.g., whether the optional name affects key identification).

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 Clearance API key") and names the product scope, which cleanly separates it from the sibling tools that all operate on clearances, tokens, or usage rather than keys. 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?

Implies when to use it (when a new key is needed) and notes email is required, and it usefully excludes choosing a tier here. However, it never states exclusions or alternatives (e.g., whether to reuse an existing key via verify_token instead), 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?

With no annotations and no parameters, the description carries the disclosure burden. It makes clear this is a read operation on the caller's key and enumerates returned fields, but it omits auth requirements, rate limits, or whether the period is configurable.

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 states the operation and immediately enumerates the returned fields. No sentence is wasted.

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 zero-parameter read tool with no output schema, the description supplies the return fields an agent needs. Minor gaps like error behavior or period semantics are acceptable at this complexity.

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

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

The tool takes zero parameters, so the baseline is 4. The description appropriately does not invent parameters and instead explains what the implicit API-key context yields.

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

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

The description uses a specific verb and resource ('Get usage for this API key') and names the exact fields returned. It is clearly distinguishable from sibling tools like clearances_get and keys_create, which cover different resources.

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 'for this API key', suggesting the tool reports the calling key's own usage. However, it doesn't say when to prefer it over siblings, nor mention any prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden and mostly delivers: it discloses that no authentication is required, that the operation is a GET (implying a non-mutating read), and that failures surface through an 'error' field rather than throwing. The main remaining gap is status-code or rate-limit behavior, plus whether an invalid token still returns HTTP 200.

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, both front-loaded: the action and endpoint come first, followed by the return contract. Nothing is wasted and no sentence merely restates the tool name.

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

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

For a single-parameter read tool with no annotations and no output schema, the description covers the essentials: what it does, that it needs no auth, and the exact fields returned including the error case. It falls just short of a 5 because failure modes (HTTP status, malformed vs expired token) are not distinguished.

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 there is only one parameter, so the schema already explains that the token is the JWT returned on approval. The description adds only that the token is a path segment in /v1/verify/{token}, which is a marginal increment — 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 pairs a specific verb ('verify') with a specific resource ('signed clearance token') and even names the underlying endpoint GET /v1/verify/{token}. That makes it trivially distinguishable from siblings like clearances_get, clearances_approve, or clearances_revoke, which all operate on clearances rather than tokens.

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: verifying a token returned by an approval is clearly a read-only validation step, and the note that the endpoint requires no authentication helps an agent know it can call it without credentials. However, there is no explicit guidance on when to prefer this over clearances_get, nor any precondition or exclusion stated.

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