Basis Theory MCP by usefulapi

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds the endpoint mapping (GET /applications/{id}) and the shape of what comes back (type plus permission list), which is useful context, but there is no note on 404 behavior or scope/tenant 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 short sentences, front-loaded with the purpose and followed by the endpoint reference. No filler or redundancy.

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

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

For a single-parameter read tool with an annotation covering safety and no output schema, the description is nearly sufficient: it names the resource and the returned fields. Only minor gaps remain, such as error behavior when the id does not exist.

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 schema description coverage at 100% and a single documented parameter, the schema already carries the semantics. The description adds nothing about id format or where the id originates, 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 ('Fetch a single application') and notes the payload contents (type and permission list), which cleanly separates it from basis_theory_list_applications. It stops short of explicitly naming the list sibling, so differentiation is implied by 'single' rather than stated.

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

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

Usage is only implied: the required application_id makes clear this is the by-id lookup, contrasted implicitly with the list endpoint. There is no explicit when-to-use/when-not guidance or named alternative for retrieving many applications.

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 establishes this as a safe, non-mutating read. The description adds content-level context about what the resource contains (destination URL, transform config), which is genuinely useful, but says nothing about 404/not-found behavior, permissions, or response shape.

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

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

Two short sentences, front-loaded with the action and resource. The trailing 'Basis Theory: GET /proxies/{id}' is mildly redundant but compact and maps the tool to the underlying API 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?

For a single-resource read with one well-documented required parameter, no output schema, and a readOnlyHint, the description covers enough: what it returns and the endpoint. Missing only not-found/error semantics, which is a minor gap 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?

Only one parameter (proxy_id) and the schema documents it at 100% coverage, so the schema carries the burden. The description adds no format, sourcing, or lookup guidance 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 (Fetch) and resource (a single proxy) and even names the payload fields (destination URL and transform configuration). It implicitly contrasts with basis_theory_list_proxies by saying 'single', though it does not name the sibling 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: you fetch one proxy when you have its id. There is no explicit when-to-use vs. when-not guidance (e.g., 'use list_proxies to discover ids first'), and no stated prerequisites or error conditions for an unknown id.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds "with its configuration" as a hint about return content, but says nothing about auth requirements, missing-id/404 behavior, or the REST endpoint's failure modes. Modest added value against a lowered bar.

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 operation and then the REST mapping. Nothing is padded, though the "Basis Theory: GET /reactors/{id}" clause is largely redundant for an agent that already has the name and 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?

A simple one-parameter read tool with readOnlyHint annotation and no output schema; the description covers what it returns at a high level and needs no return-value detail. Complete enough for correct invocation, with only failure/auth context 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%, so the single reactor_id parameter is already documented as "The reactor's id." The description adds no format, syntax, or sourcing guidance 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 (Fetch) and resource (a single reactor) plus the payload content (its configuration), which cleanly separates it from list_reactors. However, it does not name or contrast with any sibling tool by name, so differentiation is implicit rather than explicit.

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?

"single reactor" implies the when-to-use case relative to the sibling basis_theory_list_reactors, but the description never states that contrast, prerequisites, or exclusions. Usage is inferable from the wording alone, which is the minimum viable level.

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 establishes this is a safe read, so the burden is lighter. The description adds only the shape of the payload (name, id, settings); it says nothing about auth requirements, scope, or whether settings can be large/sensitive.

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

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

Two compact clauses, front-loaded with the action and the returned fields, followed by the underlying API endpoint. No filler or redundancy.

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

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

For a zero-parameter, read-only fetch with no output schema, the description compensates by naming the returned fields. It omits any contrast with adjacent tenant-related siblings (usage, members), which is the only meaningful 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate; the empty schema is fully self-explanatory.

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 the current tenant') and enumerates what comes back (name, id, settings). It doesn't explicitly differentiate from the similarly named sibling basis_theory_get_tenant_usage or basis_theory_whoami, so it lands at clarity without sibling routing.

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 exclusions, and no mention of alternatives such as get_tenant_usage or whoami. The word 'current' weakly implies it operates on the credential's own tenant, but that inference is left entirely to the agent.

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 profile is covered. The description adds useful content detail (what the report contains) and the underlying endpoint, but says nothing about rate limits, the period covered by the "monthly" figure, or whether reporting is scoped strictly to the calling tenant.

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, zero filler, with the report's contents front-loaded ahead of the endpoint reference. Nothing is repeated from the title beyond what adds specificity.

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 parameterless read tool with an output-less schema, the description covers purpose and content well enough to invoke correctly. It could be more complete by clarifying the reporting window (no way to specify a date range) and whether the data is scoped to the current tenant only.

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 no parameters, so the baseline is 4. The description reinforces that the report is implicitly scoped to the current tenant (GET /tenants/self/reports/usage), which is the only semantically relevant fact left to convey.

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

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

States a specific verb and resource ("Fetch the tenant's usage report") and enumerates the report's contents — token counts by type and container plus monthly API call volume. This clearly separates it from siblings like basis_theory_get_tenant and basis_theory_list_tenant_members, which return configuration rather than usage metrics.

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 by the tool's name and subject matter; there is no explicit when-to-use statement, no exclusions, and no routing to a sibling (e.g., get_tenant for tenant metadata). The unique resource name makes the intent inferable, but the description does not carry that guidance itself.

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

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

Annotations only declare readOnlyHint=true, so the description carries real weight here: it discloses that the response may contain the token's plaintext data if the API key has a reveal permission, and recommends issuing a read-only management key. That is exactly the kind of side effect an agent must know before calling.

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

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

Three short sentences, front-loaded with what the tool does, then return fields, then the security warning. No filler; every sentence carries 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?

With no output schema, the description steps in to enumerate the returned fields (metadata, container, fingerprint, timestamps) and flags the conditional plaintext payload. That is sufficient for an agent to call and interpret this tool safely.

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 a single required token_id, so the schema already documents the parameter fully. The description says "by id" but adds no format, encoding, or lookup semantics beyond that, making the baseline 3 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 ("Fetch a single token by id") and scopes it to one record, which distinguishes it from the list_tokens and search_tokens siblings 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?

Usage is implied by "by id" versus the list/search siblings, but the description never explicitly says when to prefer this over search_tokens or list_tokens, nor does it state any exclusions or 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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that the description adds only that results carry 'types and permissions'; it says nothing about pagination behavior, result volume, or any auth/rate-limit constraints, which for a paginated list tool is a real 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?

Two short sentences, zero filler. The scope statement leads and the endpoint reference trails, so the most important information is 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?

With no output schema, the description usefully hints at returned content ('types and permissions'), and pagination inputs are fully documented in the schema. Complete enough to call correctly, though it omits any note about how paging results are shaped or how many records to expect.

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%: page, size, and type are all documented in the schema with examples for type and bounds for page/size. The description adds no parameter 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 (List) and resource (applications), and clarifies the domain term by noting these are API-key holders in the tenant. The 'GET /applications' reference pins the operation precisely, distinguishing it from the singular basis_theory_get_application sibling, though it never names that alternative.

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 guidance on when to use this versus basis_theory_get_application, basis_theory_list_tenant_members, or the other list tools. Usage is only implied by 'List ... in the tenant' and the endpoint reference; 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds scope (audit-log entity types) and the underlying endpoint, but says nothing about the shape or ordering of the returned values beyond the fact that they are valid entity_type values.

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 front-loaded sentence states the purpose before the endpoint reference. The trailing 'Basis Theory: GET /logs/entity-types' is mildly redundant metadata, but it does not obscure the core statement.

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 parameterless enum-lookup tool with no output schema, the description covers what the tool yields and why it exists. Only the concrete return shape (e.g., array of strings) is left unstated, which 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 tool takes no parameters, so the baseline is 4. The description helpfully frames the payload as the enum consumed by entity_type elsewhere, even though there is no parameter here to document.

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: it enumerates the entity types the audit log records, and explicitly ties them to the entity_type filter values. This distinguishes it from the sibling basis_theory_list_logs, which returns log entries rather than the enum of entity types.

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 clause 'the valid values for entity_type' tells the agent when this tool matters: to discover legal values before filtering logs. There is no explicit 'use this before list_logs' routing or stated exclusions, but the use context is clear rather than merely 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?

The readOnlyHint annotation already establishes the safe-read profile, so the burden is lower. The description adds only that entries are audit-style records (who/what/which entity/when) and restates the HTTP endpoint; it says nothing about pagination limits, retention, or result volume beyond what the schema implies.

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 resource and the disambiguating summary. The trailing 'Basis Theory: GET /logs' is near-redundant metadata 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?

A read-only list tool with no required params, fully documented schema, and a safety annotation — the description supplies the one thing structured fields don't: what an entry conceptually contains. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so all six filters (page, size, dates, entity_id, entity_type) are already documented in the schema. The description adds no parameter-level guidance, which is acceptable at full coverage but earns only the 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 (list) and resource (audit-log entries) and immediately disambiguates with 'who did what to which entity and when.', making it clearly distinct from sibling list tools like list_tokens or list_applications.

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 a concrete selecting scenario ('The tool for answering \'who touched this token?\''), which tells the agent when this tool applies. It does not, however, mention exclusions or point to list_log_entity_types as a companion for discovering valid entity_type values.

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 agent knows this is a safe read. The description confirms it is a GET, but adds no behavioral detail beyond that (no pagination, result shape, or filtering semantics). With the safety profile covered by annotations, a 3 is appropriate.

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 purpose before the filter detail. The trailing 'Basis Theory: GET /permissions' is largely redundant with the readOnlyHint and adds little, but costs almost nothing.

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

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

For a zero-required-parameter read-only list endpoint with an output-schema-less return, the description supplies enough to call it correctly. Nothing critical is missing given annotations cover the safety profile.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented in the schema. The description paraphrases the same idea ('optionally for one application type') without adding syntax, format, or behavior beyond the schema. 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: it lists permissions that can be granted to an application, and narrows the scope to a single application type. It is distinguishable from the sibling list_* tools (applications, roles, tokens) without opening a schema, though it never names them.

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

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

The phrase 'optionally for one application type' conveys the available usage mode, so the agent can infer when the filter applies. There is no explicit when-to-use versus when-not-to-use guidance and no alternative tool is referenced.

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 profile is covered. The description adds domain context about what proxies do (forwarding and detokenizing), but says nothing about pagination behavior, result ordering, or rate limits beyond what the schema implies.

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 trailing 'Basis Theory: GET /proxies.' is marginally useful API mapping rather than agent-facing guidance, 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 a simple paginated list tool with a readOnly annotation and a fully-described schema, the essentials are present. Still, no mention of pagination behavior or return shape leaves minor gaps for an agent that has no output schema to consult.

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% — name, page, and size are each documented in the schema, so the description is not required to carry them. It correctly adds nothing redundant, but also contributes no extra filter syntax or pagination semantics.

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 (proxies), plus a helpful gloss on what a proxy is — 'forward requests to third parties, detokenizing in flight.' This distinguishes it from basis_theory_get_proxy in intent, though it does not name the sibling 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?

No when-to-use guidance, no prerequisites, and no mention of when to prefer get_proxy or other list tools. The agent must infer usage from the name alone.

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 profile is covered. The description adds domain context about what reactors are but says nothing about pagination defaults, result caps, or what the listing returns — with a low annotation bar, this is adequate but 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 with the resource definition front-loaded. The trailing 'Basis Theory: GET /reactors' endpoint reference is mildly redundant but very brief.

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 list tool with fully documented params and no output schema, the description covers what the tool is. It stops short of describing return shape or pagination behavior, but the page/size params make that largely inferable.

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 all three parameters (name, page, size) are documented in the schema with constraints. 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?

States a specific verb (List) and resource (reactors) and further defines the resource — 'serverless functions that run against detokenized data inside the vault' — so an agent unfamiliar with Basis Theory knows what a reactor is. This clearly separates it from siblings like list_applications, list_proxies, and list_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?

The plural 'List reactors' implies bulk enumeration and the sibling get_reactor implies single-fetch, but the description never states when to use this versus get_reactor or search-style siblings. Usage is left to inference rather than stated explicitly.

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, so the description carries a lower burden, but it adds essentially no behavioral context beyond the annotation and the endpoint line — no pagination, ordering, or completeness notes for the returned role set.

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 purpose. The trailing 'Basis Theory: GET /roles' is API-doc boilerplate rather than agent-facing information, a minor waste.

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

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

For a simple read-only list endpoint with no parameters and no output schema, the description covers the essentials but says nothing about what a role entry contains or how results are ordered/limited. Adequate but with a visible 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading parameter language is present.

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 clear verb+resource ('List the roles') and scopes it to 'tenant members', which separates it from siblings like basis_theory_list_permissions and basis_theory_list_tenant_members. It does not explicitly contrast with those siblings, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as basis_theory_list_permissions. The agent must infer that this is the tool for enumerating assignable roles.

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 profile is covered. With no output schema, the description's note that results include each person's roles is the only hint at return content, but it says nothing about pagination behavior, ordering, or rate limits.

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

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

Two short, front-loaded sentences with no filler; the return content comes first. The trailing REST endpoint reference adds little for an agent, a minor inefficiency.

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 low-complexity, zero-required-parameter read tool with a fully documented schema, the description is sufficient to invoke it correctly. Only pagination expectations and response shape are left implicit, which is acceptable given there is no output schema to explain.

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%, documenting page (1-based) and size (1-100) fully, so the baseline is 3. The description adds nothing about pagination or defaults, but nothing is missing from the structured data.

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 (tenant members) plus what is returned (people with access and their roles). It somewhat overlaps with sibling list_roles and does not explicitly differentiate itself from whoami or get_tenant, 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?

No when-to-use guidance and no alternatives named, despite siblings like list_roles, list_permissions, and whoami covering related ground. The agent must infer that this is for enumerating tenant-level membership.

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 profile is covered. The description adds valuable behavioral context beyond annotations: it returns METADATA fields only and explicitly excludes the underlying card number and PII. It does not describe pagination behavior or rate limits, but that is a minor 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?

Two tightly written sentences front-load the key scope ('as METADATA') and returned fields, followed by a concise API endpoint reference. Every clause earns its place and there is no redundancy.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description usefully names returned metadata fields and the PII exclusion. It is nearly complete, though it could briefly clarify pagination or ordering behavior rather than relying entirely on the start parameter's schema description.

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 all five parameters including the fingerprint/duplicate-finding semantics. The description mentions returned fields rather than parameter behavior, so it adds little meaning beyond the schema, making the baseline 3 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') and resource ('vault tokens'), and scopes it to METADATA with named returned fields. It is clearly distinguishable from get_token and search_tokens in practice, but it does not explicitly name or differentiate against those siblings.

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

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

The description implies this is a listing operation but gives no explicit when-to-use guidance, no prerequisites, and no alternatives such as search_tokens or get_token. The PII note is behavioral context, not usage routing.

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, and the description materially extends that: it resolves the POST/read-only tension ("Read-only despite being a POST — the query goes in the body") and discloses the return scope ("Returns metadata only") as well as the underlying endpoint. These are behavioral facts beyond the 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?

Three short sentences, no waste, all front-loaded: purpose, return scope, and the behavioral caveat appear before the endpoint reference. Every clause earns its place.

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

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

For a search tool with readOnlyHint and no output schema, the description covers purpose, query syntax, return scope, and the POST caveat. Pagination is only handled in the schema (start/size), so the description is slightly light on how to page, but otherwise complete.

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

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

Schema coverage is 100%, so the query, size, and start parameters are already documented. The inline example query (metadata.customer_id:"cus_1") largely mirrors the schema's own example, adding only marginal meaning beyond what the schema provides; 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 (search) and resource (tokens) and clarifies the scope: query syntax over metadata with metadata-only returns. This naturally separates it from list_tokens and get_token, but no sibling is named explicitly, so it stops short of a 5.

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

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

The description implies when the tool applies (query-based filtered search) but gives no explicit when-to-use/when-not guidance, nor does it route the agent away from list_tokens or get_token for related needs. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the bar is lower. The description adds real context beyond that: authentication comes from a server-configured BT-API-KEY rather than request parameters, and the result reflects the permissions the server actually holds. Return shape is left unspecified, which is a minor 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?

One front-loaded sentence stating purpose and utility, followed by the endpoint reference. No filler or repetition; every clause earns its place.

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

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

For a no-parameter, read-only tool this is nearly complete — purpose, auth source, and value are all covered. Without an output schema it could say a bit more about what the returned application payload contains, but nothing critical is missing to call it correctly.

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, which is the baseline-4 case. The description correctly conveys that no input is needed.

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: 'Return the application the configured BT-API-KEY belongs to.' The word 'configured' implicitly distinguishes it from sibling basis_theory_get_application, which takes an explicit identifier, but no sibling is named outright, so this stops short of a 5.

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

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

'The fastest way to check which permissions this server actually has' gives a clear, concrete use case. It does not name competing siblings (e.g. basis_theory_list_permissions) or state when not to use it, so it lacks the explicit routing of a 5.

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