autumn

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

Annotations mark destructiveHint=true, and the description adds meaningful behavioral context beyond that: it explicitly says 'MUTATES', may create an invoice, and may return a payment URL. This informs the agent of side effects and potential need for payment action, though it does not fully spell out all downstream consequences.

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

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

The description is two sentences with high information density: it front-loads the mutating nature, names the operation, gives the API endpoint, and lists the return shape. No filler or repetition exists.

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 complex 10-parameter tool with no output schema, the description provides essential context: mutation, side effects, endpoint, and return fields. It is slightly incomplete in not mentioning when to prefer preview_attach or preconditions, but the schema and annotations cover most invocation details.

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 every parameter is already documented in the input schema. The description adds no supplemental parameter meaning, but the baseline of 3 applies because the schema carries the full explanatory burden.

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

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

The description clearly identifies the action: attaching/subscribing a plan to a customer, and explicitly flags that it mutates billing data and may create an invoice or return a payment URL. However, it does not explicitly distinguish itself from sibling preview_attach, relying on the 'MUTATES' emphasis to imply the 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 description gives no guidance about when to use this tool versus alternatives, and notably preview_attach exists as a likely non-mutating counterpart. There are no prerequisites, exclusions, or conditional use cases stated, so an agent must infer usage from the tool name and schema.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this by explaining that paths are validated to only allow .get/.list/.check/.preview_* actions and write actions are rejected. This adds concrete behavioral detail beyond the annotation, though it does not cover auth or rate-limit 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 dense sentences with no filler. The purpose, read-only guarantee, validation rule, and API call format are all front-loaded and each sentence earns its place.

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

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

The description, schema, and annotations together give enough information to call the tool correctly: required path, optional body, allowed suffix classes, and read-only nature. It does not describe the response format, but for a raw pass-through endpoint that is a minor gap.

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

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

Schema description coverage is 100%: both path and body are already documented in the input schema. The description adds the HTTP method ('POST') and general role of body as endpoint params, but does not materially enrich parameter meaning beyond the schema.

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

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

States a specific verb ('POST') and resource ('any Autumn read/preview endpoint') and positions itself as an escape hatch for endpoints not wrapped by dedicated tools. This clearly distinguishes it from the sibling tools that wrap specific endpoints.

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?

Explicitly says when to use it: for read/preview endpoints not covered by a dedicated tool. It also says when not to use it by noting write actions are rejected, and implicitly directs users toward dedicated tools when available.

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 mark readOnlyHint=true, and the description reinforces this with 'READ-ONLY' and 'never records usage — it does not expose send_event or lock', adding concrete behavioral context beyond the annotation. It also identifies the underlying Autumn API endpoint, giving the agent useful operational 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?

The description is compact and front-loaded: it opens with the read-only nature and core question, then adds the endpoint and the key usage-related exclusion. Every phrase earns its place and there is no filler or redundant elaboration.

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 moderately simple check tool, the description covers purpose, read-only behavior, the usage-recording exclusion, and the API endpoint. Parameter details are covered by the schema, which also hints at the returned 'allowed' flag. Nothing essential is missing for an agent to select and invoke this tool 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 description does not discuss parameters, but all five parameters are already fully documented in the input schema (100% coverage). Since the schema carries the semantic weight, the description adds little beyond overall tool purpose, 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?

The description clearly states the specific action ('check') and resource ('customer access to or balance of a feature'), making it easy to distinguish from sibling tools. It explicitly positions itself as a read-only entitlement check and contrasts with usage-recording tools by saying it does not expose send_event or lock.

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 provides clear context: this is for checking access/balance, not for recording usage. It explicitly says the tool never records usage and lacks send_event/lock, which helps an agent avoid using it for metering. However, it does not name specific sibling alternatives or spell out 'use tool X when...', so routing is slightly less 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?

destructiveHint is already true, and the description reinforces it with 'MUTATES.' It adds context about operating on Autumn billing data and gives the REST endpoint, but it does not disclose idempotency, failure behavior, or side effects beyond the annotation. No contradiction exists.

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

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

The description is one front-loaded sentence containing the mutation flag, resource, example, relationship, and API endpoint. There is no redundant or filler content.

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

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

For a 5-parameter mutation with no output schema, the description plus fully documented schema cover the essential inputs. However, missing usage guidance, response format, and duplicate-entity behavior leave a moderate gap.

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

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

Schema coverage is 100%, so every parameter is individually documented. The description adds relational meaning by saying the entity is 'under a customer' and 'tied to a feature,' and it gives 'seat' as a concrete example for entity_id.

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 opens with 'MUTATES Autumn billing data' and states a specific verb/object: 'creates an entity (e.g. a seat) under a customer, tied to a feature.' This makes the operation concrete and differentiates it from sibling get/list tools.

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 create_entity versus alternatives such as get_or_create_customer, nor any mention of prerequisites like an existing customer or feature. The purpose is inferable, but explicit usage guidance is missing.

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

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

Annotations already declare readOnlyHint=true, and the description adds the endpoint detail ('POST /v1/customers.get') and optional expansion behavior. It does not contradict annotations, but it also doesn't add substantial behavioral context beyond what the annotation provides.

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 primary action and resource. The endpoint reference is useful context without adding bloat.

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 fetch tool with only two parameters, the description plus schema fully cover what an agent needs: what to fetch, how to identify it, what options exist, and the fact that the operation is read-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?

Schema documentation already covers both parameters fully. The description adds meaning by naming the expandable related data (invoices, entities, subscriptions, balances), which maps directly to the expand parameter and clarifies its purpose.

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

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

The description uses the specific verb 'Fetch' and names the exact resource ('a single Autumn customer'), scoped by id and with optional expansion. This clearly distinguishes it from siblings like list_customers or get_or_create_customer.

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 clearly implies usage for retrieving one customer by id, which is the core selection context. However, it does not explicitly mention alternatives or exclusions, such as when to prefer list_customers or get_or_create_customer.

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 already communicates that this is a safe read operation. The description adds the endpoint and the customer scoping, but does not disclose error behavior, expand semantics, or response content. It aligns with annotations and adds modest context.

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

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

Two short sentences with no filler. The key scope ('single entity belonging to a customer') is front-loaded, and the API endpoint line provides useful factual context without bloat.

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 lookup with fully documented parameters, the description covers what is fetched and its scoping. It does not mention error cases or return shape, but the phrase 'Fetch a single entity' plus the readOnlyHint makes the tool's purpose and safety clear.

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 parameters are already documented. The description restates that the entity belongs to a customer but does not add meaningful semantics beyond the schema.

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

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

Description clearly states the specific action ('Fetch a single entity'), the resource ('a seat'), and the owning customer. It also names the exact API endpoint, making it easy to distinguish from list_entities and create_entity.

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

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

It implies usage when retrieving one specific entity by ID and scopes it to a customer, but does not explicitly state when to prefer it over list_entities or mention any alternatives. The guidance is present but only implicit.

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 provide readOnlyHint=true, so the safety profile is covered. The description adds the concrete Autumn API endpoint and method, POST /v1/features.get, which is useful implementation context, but it provides no detail on errors, not-found behavior, 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 with the main action front-loaded and no filler. The endpoint sentence adds a useful API detail without obscuring the primary instruction, making this an appropriately sized and well-structured description.

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-only lookup, the description plus schema is nearly sufficient for an agent to invoke the tool correctly. The main gap is the lack of any stated return or error behavior, especially since no output schema exists to fill that in.

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 parameter feature_id is already documented as 'The ID of the feature.' The description adds no additional parameter meaning, so the baseline score of 3 applies.

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

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

States the exact action 'Fetch', the resource 'single feature', and the lookup criterion 'by id'. This clearly distinguishes it from list_features for bulk retrieval, so an agent can select it correctly without inspecting other schemas.

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 tool is for retrieving one feature when its ID is known, but it never explicitly names alternatives or states when not to use it. The context is enough for simple selection, but there is no explicit routing or 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?

The description clearly discloses a mutating side effect ('MUTATES Autumn billing data') that goes beyond the generic destructiveHint, and it specifies the exact API endpoint. It does not cover every potential side effect (e.g. Stripe creation behavior), but it is direct about the core behavioral risk.

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 deliver the key facts with zero filler, and the mutation warning is front-loaded. The API endpoint line is useful and not 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?

The tool has nine parameters and no output schema, yet the description explains only the core operation. It leaves the response shape and any additional side effects of parameters like create_in_stripe to be inferred rather than stated.

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 input schema already documents every parameter. The description adds only the context that lookup is by id, which maps to customer_id, but it does not need to repeat the schema.

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

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

The description states a clear verb and resource: it 'fetches a customer by id' and 'creat[es] them if they do not exist.' This distinguishes it from read-only siblings like get_customer by explicitly flagging the creation side effect.

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 intended use is implied by 'creating them if they do not exist,' so an agent can infer this is for ensuring a customer exists before acting. However, it never explicitly names alternatives such as get_customer or states when not to use this tool.

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, covering the safety profile. The description adds the concrete Autumn API endpoint and optional-version behavior, but does not disclose return shape, error cases, or authentication 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?

A single compact sentence front-loads the action and resource, and the endpoint reference provides useful grounding without unnecessary detail. Every element earns its place.

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

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

For a simple read-only fetch with two well-documented parameters and no output schema, this is nearly complete. It omits an explicit statement of the return value, but the tool name and purpose make it obvious, and the endpoint reference adds useful context.

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 schema fully describes plan_id and version, including the default behavior. The description's 'optionally a specific version' largely restates schema information, adding minimal semantic value beyond 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?

The description uses a specific verb ('Fetch') with a precise resource ('a single plan by id') and an optional qualifier ('specific version'). This clearly distinguishes it from list_plans and other siblings, making the tool's scope immediately obvious.

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 when a single plan id is known, and 'single' hints at not using this for listing. However, it never explicitly names alternatives like list_plans or states when not to use it, leaving the agent to infer routing from context.

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

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

The readOnlyHint annotation already covers the read-only safety profile, and the description adds useful behavioral detail by naming the POST endpoint and the exact response shape, { list, next_cursor }, which is especially valuable since no output schema exists. It does not discuss rate limits or auth, but the readOnly annotation lowers the burden.

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 carry the essential purpose, transport endpoint, and return shape with no filler. The list/filter action is front-loaded, and every phrase 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?

The description plus fully documented schema gives an agent the endpoint, response shape, and pagination mechanism, which is sufficient for a read-only collection listing. It could be even stronger with an explicit pointer to get_customer for single-customer needs, but nothing essential 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 every parameter already has a meaningful description in the schema. The tool description adds no additional parameter semantics beyond the high-level 'filter' notion.

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: it lists and filters customers with cursor pagination. This clearly distinguishes it from singular tools like get_customer and from list tools for other resources like list_plans or list_entities.

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 tool is for listing or filtering customers and for paginated collection access, but it never explicitly says when to prefer it over get_customer or other list variants. The usage context 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 declare readOnlyHint=true, and the description adds that this is a paginated list call returning { list, next_cursor }. This goes beyond the annotation by clarifying the response shape and pagination behavior without contradicting it.

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 deliver the core action, scope, API endpoint, and return shape with no filler. 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?

For a list operation with a rich schema and readonly annotation, the description is nearly sufficient. It states the resource, pagination, and return format, though it does not explicitly guide the agent between this and related list/get tools.

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

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

Schema coverage is 100%, so all seven parameters are described in the input schema. The description only refers generically to 'optional filters', adding no parameter-specific semantics beyond what the schema already provides.

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

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

The description uses a specific verb ('List') and resource ('a customer's entities'), and even identifies the exact API endpoint. This clearly separates it from sibling list tools such as list_customers and get_entity.

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 first sentence establishes the intended use case: listing entities belonging to a customer, with pagination and filters. It does not explicitly name alternatives or exclusions, so it falls short of a 5, but the context is clear enough for selection among siblings.

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 already covers the safety profile. The description adds the HTTP endpoint and the response envelope ({ list }), which is useful context, but it does not disclose pagination, limits, ordering, or what a feature object contains. No contradiction with 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?

Three short sentences, each earning its place: purpose, endpoint, return shape. The most decision-relevant 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?

For a zero-parameter read-only list tool, the description covers purpose, scope, endpoint, and response wrapper. It stops short of describing item structure or pagination, but the output schema is absent and a sibling get_feature exists for details.

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 input schema has zero parameters, so the baseline is 4. The description's 'current environment' phrase clarifies the implicit scope even though there is nothing to configure at call time.

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

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

The description uses a specific verb and resource ('List all features in the current environment'), and the 'all' scope separates it from get_feature and other list_* siblings. Adding the Autumn API endpoint reinforces the tool's identity.

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

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

The phrase 'List all features' implies use when you want the complete feature set, but the description never contrasts it with get_feature or states when not to use it. Alternatives are only discoverable via sibling names, not by explicit 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?

The description adds useful behavioral context beyond the readOnlyHint annotation, including cursor pagination behavior and the response shape { list, next_cursor }. It does not contradict the annotation and clarifies the stateful pagination pattern.

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 deliver the core purpose, API endpoint, pagination model, and return shape without redundancy. The most important information is front-loaded and 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?

Given the readOnly annotation, full parameter documentation in the schema, and the description's inclusion of the endpoint and response format, nothing essential is missing for an agent to invoke this tool 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%, and each parameter is already documented with meaningful descriptions. The description only adds a high-level 'optional filters' phrase without explaining individual parameters, which is acceptable but not additive beyond the schema.

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

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

The description states a specific verb and resource, 'List invoices', and provides the exact API endpoint. It clearly distinguishes this tool from sibling tools like list_customers and list_entities by targeting invoices specifically.

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 clearly indicates this is the tool for listing invoices with pagination and filters, giving an agent the context needed to select it. It does not explicitly name alternatives or exclusions, but the object type is unambiguous among the siblings.

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 some value beyond the annotations by revealing the API endpoint and the return shape ({ list }), but it does not disclose pagination, limits, or any ordering/filtering behavior, which would be genuinely useful context 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?

A single terse sentence that front-loads the core purpose and appends the endpoint and return format, with no filler. Every clause carries information an agent can act on.

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 a 100%-covered schema, no required parameters, and annotations supplying the read-only safety profile, the description covers the essential contract: what it lists, the endpoint, and the response shape. It is adequately complete for a simple collection endpoint, missing only optional niceties like pagination details.

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

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

Schema description coverage is 100%, so all four parameters (entity_id, customer_id, all_versions, include_archived) are already fully documented by the schema. The description adds no parameter-specific meaning beyond the { list } return note, which fits the baseline-3 expectation for high schema coverage.

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 a clear resource ('plans (products)') scoped to the current environment, and names the underlying API endpoint (POST /v1/plans.list). This clearly differentiates it from siblings like get_plan (singular retrieval) and attach_plan (mutation), so an agent can tell it apart without opening the schema.

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

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

The description says 'List all plans,' which implicitly positions this as the batch/collection operation distinct from get_plan and attach_plan among the siblings. However, it never explicitly states when to prefer this over the alternatives or when not to use it, so the routing guidance is implied 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?

It explicitly flags the operation as 'MUTATES' and says it creates a Stripe billing-portal session, adding useful behavioral context beyond the destructiveHint annotation. It also states the return shape, though it does not cover authorization requirements or other side effects such as portal-session expiry.

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

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

The description is two sentences with no filler. It front-loads the mutation warning, states the tool's purpose, gives the API endpoint, and describes the response, all concisely.

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 tool with one required parameter and no output schema, the description is largely complete: it explains the action, the API call, and the returned values. Minor gaps include not mentioning portal behavior after redirect or any prerequisite relationship with a Stripe account, but these are not critical for invocation.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description mentions the returned customer_id and url but does not add new meaning to return_url or configuration_id beyond what the schema provides.

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

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

The description names a specific action ('creates a Stripe billing-portal session') and the resource ('for a customer to manage their subscription'), making the tool's function immediately clear. It also distinguishes the tool from the many get/list siblings by emphasizing that it is a mutating operation.

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 supplies clear context: this tool is for letting a customer manage their subscription via Stripe's billing portal. It does not explicitly name alternatives or exclusion criteria, but the purpose is specific enough that an agent can infer when to choose it.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces that with 'WITHOUT charging or changing anything' and 'Read-only', adding the key behavioral consequence of no charge. This goes beyond the bare annotation by specificying the practical side-effect-free nature and the preview-only intent. No contradiction with annotations exists.

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

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

The description is one tight sentence that front-loads what the tool does and its key side-effect-free property, then appends the endpoint for reference. Every word earns its place, and the formatting makes the critical information immediately visible.

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 preview call, the description covers purpose, safety, and the general outcome ('cost/effect'). With no output schema, it could arguably say a bit more about what the preview returns, but the core guidance for correct invocation—no side effects, preview-only—is complete. The nested customize and feature_quantities parameters are documented in the schema, so the description does not need to repeat them.

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 parameters are already well-documented. The description does not add parameter-specific detail, but the baseline of 3 applies because schema carries the burden. It loosely ties customer_id and plan_id to the 'attaching a plan to a customer' idea but offers no additional semantic value.

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 opens with the specific verb 'Preview' and the resource 'cost/effect of attaching a plan to a customer', making the operation unmistakable. It explicitly contrasts with the mutating attach_plan sibling by saying 'WITHOUT charging or changing anything', so an agent can tell this apart at a glance.

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 'WITHOUT charging or changing anything' and 'Read-only' clearly signal this tool is for inspection before a real action, which implies use when the agent wants to evaluate impact without side effects. It does not explicitly name attach_plan as the alternative for actually changing something, but the sibling list plus the contrast is strong enough to guide selection.

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

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

Annotations already declare destructiveHint=true, and the description goes beyond that by explaining the actual billing consequence: 'deducts/credits a feature balance'. This adds meaningful behavioral context for a mutation tool. The description is consistent with the annotation and adds the either/or key constraint, though it doesn't discuss reversibility or retry 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?

The description is only two sentences, yet every part carries load: mutation status, balance effect, parameter exclusivity, and the underlying API endpoint. No filler or redundant restatement of the tool name. It is front-loaded with the most important behavioral signal.

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 destructive 8-parameter tool with no output schema, the description supplies the critical side-effect and the one genuinely ambiguous invocation rule, while the schema covers all parameter details. It could add more on prerequisites, idempotency usage, or postconditions, but an agent can correctly invoke the tool with the information provided.

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?

Input schema coverage is 100%, so the schema already fully describes all eight parameters including value, timestamp, entity_id, and idempotencyKey. The description adds a useful cross-parameter rule for feature_id/event_name and the credit/debit interpretation of value, but most parameter semantics are already carried by the schema. This is a solid 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 opens with 'MUTATES Autumn billing data — records a usage event (deducts/credits a feature balance)', which names a concrete verb, resource, and effect. This clearly distinguishes the tool from the many read/list siblings while also identifying the specific billing operation. The endpoint reference reinforces what the tool does.

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

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

The description gives a helpful parameter-selection rule ('Provide EITHER feature_id OR event_name') and implies it is the tool for usage events, but it never explicitly contrasts track_usage with siblings such as autumn_request or states when not to use it. Usage context is implied rather than formally differentiated from alternatives.

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 mark destructiveHint=true, and the description reinforces this with 'MUTATES'. It adds meaningful behavioral context with 'Only provided fields change', making the partial-update semantics explicit and reassuring agents that unspecified fields are left untouched. This goes beyond what the annotation alone conveys.

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

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

The description is two sentences with no filler. The mutation signal and partial-update behavior are front-loaded, and the endpoint reference provides useful context without bloating the text.

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

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

For a mutation tool with a destructive hint and no output schema, the description provides the essential behavioral context: mutation, partial update, and endpoint. The full parameter schema compensates for the absence of parameter-level prose. It lacks explicit alternative routing, but what is present is sufficient for an agent to invoke the tool correctly in most cases.

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 input schema already documents every parameter. The description adds the general semantic that only provided fields change, which is useful but does not deepen understanding of individual parameters such as stripe_id, fingerprint, or new_customer_id 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?

The description states a specific action ('partially updates a customer') on a specific resource ('Autumn billing data'), making the tool's purpose unambiguous. It distinguishes itself from sibling read tools like get_customer and list_customers by emphasizing mutation, and from creation tools by saying 'partially updates' rather than creates.

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 does not say when to use this tool versus alternatives such as get_customer, list_customers, or get_or_create_customer. The mutation cue is clear, but there is no explicit guidance on selecting update_customer over sibling tools, nor are any exclusions or prerequisites mentioned.

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