basis-theory

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 bar is lower. The description does add useful return-content context ('with its type and permission list'), which matters because there is no output schema, but it says nothing about auth/permission requirements or not-found behavior.

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

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

Two compact sentences, zero waste, with the resource scope front-loaded and the endpoint reference as trailing detail.

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 full schema coverage and annotations, the definition is nearly sufficient, and it helpfully names the main fields returned in the absence of an output schema. Only the lack of any alternative-routing guidance keeps it short of 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% for the single application_id parameter, so the schema already carries the semantics. The description adds no format, sourcing, or ID-resolution guidance beyond what the schema 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 a specific verb and resource ('Fetch a single application') and even gives the underlying endpoint GET /applications/{id}. The word 'single' distinguishes it from basis_theory_list_applications, though that sibling is never named.

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

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

Usage is only implied by 'a single application' versus the sibling list tool; there is no explicit 'use this when you have an id, use list_applications when browsing' guidance. Adequate but leaves the agent to infer the routing decision.

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, and the description adds value by naming the returned fields (destination URL, transform config), which matters since there is no output schema. It does not mention error behavior (e.g., missing id) or auth requirements, so it stays at a solid but unremarkable 3.

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 return fields. The trailing API mapping ("GET /proxies/{id}") is mildly redundant but compact and does no harm.

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 single-resource read with full parameter coverage and readOnly annotations, the description covers what the tool does and what it returns, compensating for the absent output schema. Error and auth behavior are the only missing pieces.

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?

There is a single parameter with 100% schema description coverage, so the schema fully documents proxy_id. The description adds no format or syntax detail beyond the schema, matching the baseline of 3 when the schema does the heavy lifting.

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 gives a specific verb ("Fetch") and resource ("a single proxy") and even names the returned fields (destination URL and transform configuration). This implicitly separates it from the sibling basis_theory_list_proxies, though no alternative tool is named explicitly.

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

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

There is no explicit when-to-use guidance or mention of alternatives such as list_proxies or search_tokens. The agent must infer that this is the right tool when it already holds a single proxy_id.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that configuration is included in the response, but says nothing about error behavior (e.g., not-found), permissions, or auth requirements.

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

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

Two short sentences, front-loaded with the action and resource, and the API endpoint reference is compact and useful. 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 simple single-resource GET with full schema coverage and a readOnly annotation, this is adequate. It lacks return-value detail, but that's forgivable given the endpoint reference; still, no output schema means the agent has only a vague sense of what 'configuration' contains.

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 parameter is fully documented in the schema. The description adds nothing about the id format or source beyond what's already provided, 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) with configuration scope. The 'single reactor' phrasing distinguishes it from the sibling basis_theory_list_reactors, but it doesn't name that sibling explicitly, leaving differentiation implied by the singular/plural contrast.

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 'single' plus the reactor_id parameter implies this is the detail-lookup counterpart to a list call, but there is no explicit when-to-use or alternative naming. 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?

The readOnlyHint=true annotation already covers the safety profile, so the description only needs to add context. It discloses that no identifier is needed (it is always the current tenant) and what is returned, which is useful. It does not mention auth requirements or what 'settings' entails, but the annotations lower the 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 compact clauses, one carrying the return payload and one carrying the endpoint mapping, with nothing wasted. The key fact (current tenant) 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?

For a zero-parameter read tool with no output schema and annotations covering safety, the description supplies the essential missing piece: what comes back (name, id, settings). Only the unpacked contents of 'settings' are left vague, 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?

There are zero parameters, so the baseline is 4. The description correctly implies no input is required by scoping to the 'current' tenant, and the empty schema is consistent with that.

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 (the current tenant) and enumerates the returned fields (name, id, settings). It also pins the exact API endpoint, GET /tenants/self, making the target unambiguous. It doesn't explicitly differentiate from siblings like get_tenant_usage or whoami, but the scope is clear.

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 guidance on when to use this versus alternatives such as basis_theory_get_tenant_usage or basis_theory_whoami, both of which also touch the current identity/tenant. An agent gets no signal about choosing among them; the usage is only implied by the name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses what the report actually contains (token counts by type and container, monthly call volume), which is behavioral context beyond the annotations, but it says nothing about aggregation windows, latency, or refresh cadence.

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, with the substantive payload description front-loaded. The trailing endpoint reference is mildly redundant but cheap and aids traceability.

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 must stand in for return values, and it does list the two main report sections. It would be stronger with units/period granularity (e.g. billing cycle), but nothing essential for invocation is missing for a no-arg read tool.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly avoids inventing parameter details.

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 (tenant usage report) and enumerates the report's contents — token counts by type and container plus monthly API call volume — which clearly separates it from siblings like list_tokens or get_tenant.

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: this is a zero-parameter self-reporting endpoint, so there is no parameter choice or filtering decision to guide. However, the description never states when to reach for this versus the sibling reporting/list tools, nor any preconditions.

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 goes well beyond that by disclosing that a reveal-permission API key causes plaintext token data to be returned, and recommends a read-only management key. That is a non-obvious, security-relevant side effect an agent could not infer from the schema or annotations.

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

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

Front-loaded with the core action, then return fields, then the warning, then the endpoint. Every sentence carries distinct information with no filler.

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

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

No output schema exists, and the description compensates by naming the returned metadata fields. With one fully-documented parameter and an explicit secret-exposure caveat, nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100% for the single token_id parameter, so the schema already carries the semantics. The description's "by id" adds no syntax, format, or failure-mode detail beyond it, 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 single token by id") and pins the singular scope, which cleanly separates it from list_tokens and search_tokens in the sibling set. It also enumerates the returned fields, so the agent knows exactly what it gets back.

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 (call it when you have a token id) and the API-key warning gives operational context, but there is no explicit when-to-use/when-not guidance or routing to alternatives like search_tokens for lookup by other criteria. 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 already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds useful context by saying the response includes application types and permissions and by naming the underlying GET /applications endpoint, but it does not describe pagination behavior or any rate/auth constraints 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?

Two sentences with zero waste, front-loading the action and scope before the API endpoint detail. Every part earns its place by either describing the resource or grounding it in the underlying Basis Theory 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 read-only list tool with no output schema and fully documented parameters, the description covers scope and returned fields well enough to call correctly. It could be slightly stronger by explicitly noting pagination behavior or routing the agent to get_application for single-item retrieval, but no critical information is missing.

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

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

Schema description coverage is 100% and all three pagination/filter parameters (page, size, type) are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

States a specific verb (List), resource (applications/API-key holders), scope (in the tenant), and returned attributes (types and permissions). It does not explicitly name the sibling get_application as the single-resource alternative, but the list-vs-get distinction is clear enough for selection.

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 usage by stating it lists applications in the tenant, and the endpoint hint reinforces that this is a collection read. However, it gives no explicit when-to-use guidance, no exclusions, and does not name alternatives like get_application for retrieving a single application.

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 declares this as a non-mutating read, and with zero parameters there is little behavior to disclose. The description adds that the result is an enumeration of valid entity_type values, which is useful, but says nothing about caching, stability of the list, or return 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 compact clauses: the purpose is front-loaded, followed by the API endpoint reference. No filler, nothing an agent must read past to get the meaning.

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

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

For a zero-parameter read-only enumeration tool with no output schema, the description supplies all the decision-relevant information. A brief note that the returned values are stable/reference data would make it 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?

The tool takes no parameters, so the baseline is 4. The description correctly frames the output as the value domain for entity_type, which is the only semantic an agent needs here.

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

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

States a specific verb and resource ('List the entity types the audit log records') and disambiguates from the sibling basis_theory_list_logs by clarifying this returns enum values rather than log entries. 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?

The phrase 'the valid values for entity_type' implies when this tool is useful (resolving/filtering by entity_type elsewhere), but it never states when to call it versus list_logs or how to consume the result. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint=true, and 'GET /logs' reinforces that this is a safe read. The description adds useful context about what each entry contains, but says nothing about pagination behavior, retention windows, max date-range spans, or rate limits that matter for a paged audit 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 short clauses: purpose, disambiguating question, and endpoint confirmation. Front-loaded with the core verb+resource, and 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 six-parameter paged list with no output schema, the description does convey entry contents and a targeting use case, which partly compensates for the missing return-shape detail. It still omits pagination semantics and how the entity filters interact, leaving the agent to infer endpoint behavior.

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 parameters (page, size, date bounds, entity_id, entity_type) are already documented. The description adds no filtering syntax or format detail beyond the schema, so the 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 audit-log entries) plus the fields returned (who/what/entity/when), which is far more informative than the title alone. It implicitly distinguishes itself from sibling getters since it is the only logs tool, but it never names a sibling or contrasts scope explicitly.

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

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

The line 'The tool for answering \'who touched this token?\'' gives an implied use case, which nudges an agent toward audit queries. However there is no explicit when-to-use vs when-not guidance, no mention of the sibling basis_theory_list_log_entity_types that pairs with the entity_type filter, and no 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 declares this a safe read, lowering the bar. The description adds that these are grantable permissions scoped to an application, which is useful context, but 'Basis Theory: GET /permissions' merely restates. No pagination or return-shape detail.

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 core action and scope. The trailing API endpoint reference is low-value filler but the rest is tight with no padding.

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

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

A simple read-only list tool with a single fully documented optional parameter and annotations covering the safety profile. The description is adequate; only return format/pagination are unspecified, which is minor here and partly excused by the trivial 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 coverage is 100%, so the schema already documents application_type as 'Only permissions valid for this application type.' The description's 'optionally for one application type' reinforces optionality and filtering but adds no syntax or format beyond the schema. Baseline 3 is appropriate.

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

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

Specific verb+resource: 'List the permissions' with the added scope that they are permissions grantable to an application. This clearly separates it from siblings like list_roles or list_applications, though it never explicitly names a sibling.

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

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

'optionally for one application type' implies when the lone parameter is relevant, but there is no explicit when-to-use vs alternatives or prerequisite guidance. 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 readOnlyHint=true, so the safety profile is covered. The description adds useful domain context that proxies forward requests to third parties and detokenize in flight, but says nothing about pagination behavior, result limits, or auth requirements 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 tight sentences with the core purpose front-loaded; the trailing 'Basis Theory: GET /proxies' REST mapping is mildly redundant but compact and harmless.

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

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

For a simple, read-only, three-parameter list tool with no output schema, the description is minimally adequate. It omits what the returned list contains (proxy objects, pagination envelope), which an agent would need to consume results 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?

Schema description coverage is 100% (name, page, size all documented in the schema), so the parameter contract is fully carried by structured fields. The description adds no additional meaning about how filtering or pagination interact, 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?

The description gives a specific verb and resource ('List the proxies') and even explains what a proxy does ('forward requests to third parties, detokenizing in flight'), which helps distinguish it from sibling list tools. It does not explicitly contrast with the singular sibling basis_theory_get_proxy, so sibling differentiation is only partial.

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 basis_theory_get_proxy for a single proxy, nor any stated prerequisites or exclusions. The description merely asserts what the tool does, leaving usage entirely to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful domain context about what reactors are and where they execute (against detokenized data inside the vault), but discloses nothing about result ordering, pagination defaults, or filtering 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?

Two tight sentences with the purpose front-loaded and a useful API endpoint mapping appended. Every clause earns its place with no filler.

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

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

For a read-only, zero-required-parameter list tool with a fully documented schema and an existing readOnlyHint, the definition is essentially complete. The only soft gap is a lack of any note on pagination behavior or result shape, which is less critical given there is no 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% — name, page, and size are all documented in the schema, so the description carries no additional parameter burden. It adds no syntax, format, or semantic nuance beyond what the schema already states, which is the baseline case.

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 ('List reactors') and goes further by defining what a reactor is ('serverless functions that run against detokenized data inside the vault'), which disambiguates the domain term. It does not explicitly distinguish itself from the sibling basis_theory_get_reactor, though the list/get contrast is reasonably apparent from the name.

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 verb 'List' — an agent can infer this returns multiple reactors, but the description never states when to prefer this over basis_theory_get_reactor for a single reactor, nor does it mention how pagination or the name filter should be used when enumerating.

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 safe-read profile is covered structurally. The description adds the scoping detail that roles are tenant-member roles, but says nothing about pagination, result size, or whether the list is static or custom-defined.

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' endpoint reference is mildly redundant for an agent but harmless and compact.

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-only list endpoint with no output schema, the description gives enough to call it correctly. Sibling discrimination against list_permissions is the only missing piece.

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 clarify and no schema gap to compensate for. Baseline 4 applies for a no-argument tool.

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') plus the scope ('available for tenant members'), so the agent knows exactly what is returned. It does not differentiate itself from neighboring list tools such as list_permissions, which is the only real weakness.

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: an agent can infer it is the lookup to run before assigning roles to tenant members, but there is no explicit when-to-use statement and no mention of how it differs from list_permissions. Adequate but leaves routing to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is disclosing that the payload includes roles alongside members. It says nothing about pagination behavior, default page size, or whether results are scoped to the calling tenant, which would be useful for a list 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?

Front-loaded and short: the purpose sentence comes first, with the REST endpoint mapping appended as compact provenance. Every element earns its place, though the endpoint string is metadata rather than agent-facing guidance.

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-required-param read tool with readOnlyHint and full schema coverage, the essentials are covered, but there is no output schema and the description doesn't characterize the return shape beyond 'people and their roles' or address pagination, leaving minor 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 only two optional pagination parameters, so the schema fully documents page and size. The description adds no parameter-level meaning, which is acceptable here since the baseline is 3 when the schema carries the load.

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 people with access to the tenant, and their roles'), which is clearer than a bare 'list members'. It distinguishes itself reasonably from siblings like list_roles by framing the result as people plus their roles, though it never explicitly contrasts with get_tenant or whoami.

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 does not say how this differs from whoami (the caller's own membership) or list_roles, and it gives no hint about pagination expectations despite page/size parameters.

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, but the description adds genuinely useful behavioral context: the response is metadata-only and deliberately excludes card numbers/PII. That is exactly the kind of trait annotations can't express and it also names the backing endpoint. It stops short of describing pagination mechanics or result 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 sentences, tightly front-loaded with the action and return shape, followed by the key limitation and the API mapping. Every clause carries information; nothing 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?

With no output schema, the description usefully enumerates returned fields and explicitly states what is omitted, which is the critical fact for an agent handling token data. The only remaining gap is any note on pagination beyond the cursor parameter already documented in the schema.

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

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

Schema description coverage is 100%, with each of the five parameters (size, type, start, container, fingerprint) documented including cursor semantics and the duplicate-detection use of fingerprint. The description adds no parameter-specific meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List vault tokens') and enumerates the returned fields (id, type, container, fingerprint, metadata, timestamps), which goes beyond the name. It clearly distinguishes itself from single-entity read siblings like get_token, though it doesn't name search_tokens as the alternative for richer filtering.

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 'Does not return the underlying card number or PII' clause implicitly tells the agent this is a safe metadata-listing operation as opposed to a value-revealing one, which is useful routing context. However, there is no explicit statement of when to prefer this over search_tokens, nor any prerequisite/exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, but the description adds real value beyond them: it explains that the POST is read-only because the query travels in the body, and that the result is 'metadata only' (not token payloads). It stops short of noting rate limits or result-shape 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?

Front-loads the search capability, then layers the example, return scope, and read-only clarification. The trailing raw endpoint reference is slightly redundant but compact overall.

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

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

With no output schema, the description compensates by stating the return is metadata only, and pagination is fully covered by the schema's start cursor. Enough for an agent to invoke it correctly; only explicit alternative-routing 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 the schema already documents query, size, and the start cursor. The description restates a query example but adds no syntax the schema lacks, hitting 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 (search) and resource (tokens) plus the query mechanism (Basis Theory query syntax over metadata). It is clearly distinct from a plain listing, though it never names the sibling basis_theory_list_tokens it competes with.

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 mention of 'query syntax over metadata' implies use when filtered retrieval is needed, but there is no explicit when-to-use guidance or routing to basis_theory_list_tokens for unfiltered listing. Usage is left to inference.

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

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

readOnlyHint=true already establishes this is a safe, non-mutating read, so the description's burden is lower. It still adds useful context: the call is driven by the server-configured key rather than an agent-supplied credential, and it discloses the underlying endpoint (GET /applications/key), which is genuine value beyond the annotations.

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

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

Two tight clauses: the outcome is front-loaded, the value proposition follows, and the endpoint reference is a compact trailing anchor. 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 zero-parameter, read-only identity tool with no output schema, the description covers what the agent needs to decide to call it. It could briefly characterize the returned application object (id, permissions) but the gap is minor given the simplicity.

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 reinforces why — the identity comes from the configured BT-API-KEY rather than an argument — which is the only parameter-relevant information an agent could need.

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') and makes the identity/whoami nature unmistakable against siblings like basis_theory_get_application or basis_theory_list_applications, which require an explicit id or enumerate resources. The agent can tell what this tool returns without opening anything.

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 clear usage context — 'the fastest way to check which permissions this server actually has' — which tells the agent when this is the right call. It stops short of naming an explicit alternative or exclusion, but the zero-argument, self-scoped nature is implied by 'the configured key'.

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