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

Annotations only declare openWorldHint; they do not declare readOnly or destructive behavior. The description signals that this tool can change access and enumerates add/remove modes, but it omits permission requirements, reversibility, immediate effect, and other mutation side effects, leaving a significant gap for an access-control mutation tool.

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

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

The description is two tight sentences, front-loads purpose, then maps the action values without repetition. Every phrase contributes to selecting the right action.

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 fully described schema and no output schema, the description covers the core use and action modes. However, for a tool that can change app access, it does not state authorization requirements or the consequences of changing the list, leaving meaningful context 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 coverage is 100%, so the baseline is 3. The description adds real meaning for the action enum: show is default, everyone means company-wide, only means named people plus owner, and add/remove operate on that list, which is more than the schema's 'What to do'.

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?

It states a specific resource and pair of operations ('Shows or changes who can open the app') and enumerates the action modes. It does not name or differentiate from siblings such as roles or get_app_rules, so it stops short of 5.

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

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

It explains what each action value does, including show as default and the difference between everyone and only. It gives no explicit when-to-use/when-not guidance versus sibling tools, so the agent must infer tool 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 and openWorldHint, yet the description adds high-value specifics: exactly what gets destroyed (database, files, secrets), that it is irreversible, and that human intent must be confirmed first. That is real disclosure beyond the annotation flags.

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 carrying distinct load: consequence, irreversibility, invocation gate. The blast-radius statement is front-loaded where an agent will see it first.

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 two-param tool with no output schema, the description covers consequence, irreversibility, and the confirmation contract. It does not state what happens if the app is absent or how the directory parameter interacts with app resolution, but those are 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 coverage is 100%, so baseline is 3, but the description adds a semantic constraint the schema omits: the confirm value must be the app name sourced from teamonly.json. That turns a generic string param into a verified identity check.

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 ('Deletes the live app') and immediately scopes the blast radius ('with its database, files and secrets'). No sibling tool competes with this operation, and the destructive scope is unmistakable.

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 an explicit precondition — 'Only call this when the person asked for it' — plus how to satisfy the confirmation parameter. No alternatives are named, but among the siblings none performs a delete, so there is little to disambiguate against.

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 openWorldHint, so the description does the behavioral work: it discloses the expected duration (up to a minute), the required company login, and that a not-signed-in result carries a remediation pointer. It omits what happens to a prior deployment or what a failure result looks like.

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

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

Three short sentences, front-loaded with what happens and where it lands, then timing, then the failure path. 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?

With no output schema, the description responsibly sketches the result shape for the auth failure case, but says nothing about success output or partial-failure behaviour. Adequate for a single-parameter deploy tool with slight 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?

The schema documents the single directory parameter fully (absolute path, the teamonly.json marker, default behaviour), at 100% coverage. The description only names the parameter in passing and adds no meaning beyond it, so baseline 3 applies.

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

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

States a specific verb (builds) plus the concrete effect (puts it online at a templated URL) and the access model (behind the company login). An agent can tell this apart from status, logs, or delete_app 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?

Explicitly routes the not-signed-in case to the sign_in sibling, which is real conditional guidance. It does not say when NOT to deploy (e.g. after incomplete setup, or when a deploy is already running), so it falls short of full when/when-not coverage.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real value beyond that by disclosing the subject matter of the returned content, so the agent knows what questions the document can answer. It does not describe the return shape (single document? sections?) or length, which keeps it at a 4.

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

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

One sentence plus a one-clause imperative, with the purpose front-loaded and the topic list serving the concrete job of telling the agent what it can learn. Nothing is repeated from the title or annotations.

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

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

For a zero-parameter, read-only documentation fetch with no output schema, the description supplies everything needed to decide and call: what it returns, what it covers, and when to invoke it. No meaningful gap remains.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly implies a parameterless call by framing the tool as a document to be read rather than a query.

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 resource (the rules for writing a TeamOnly app) and enumerates the topics covered — supported stack, signed-in person, database, files, secrets, email, scheduled jobs, roles. That enumeration makes it unmistakable against siblings like deploy, init, or roles, which each cover one narrow slice.

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?

"Read this before writing or changing app code" gives a clear triggering condition and implicitly sequences it ahead of init/deploy. It stops short of stating when not to call it (e.g. when only inspecting a deployed app) or naming siblings as alternatives, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose the key side effects: file/app creation in an empty folder and, notably, mutation of an existing project by adding teamonly.json and tool-specific instruction files. It does not say whether existing files are overwritten, whether the operation is idempotent, or whether auth/trial state is required.

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

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

Three short sentences, front-loaded with the primary empty-folder behavior, then the existing-app behavior, then the template-list affordance. Nothing is padded or redundant.

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

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

For a mutating setup tool with no annotations and no output schema, the description covers what gets created but omits prerequisites (the sibling tools sign_in/start_trial/subscribe suggest an account or trial gate) and what the success/failure result looks like. Adequate but with a material gap for a first-run bootstrap command.

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 baseline is 3, but the description adds real semantics: leaving 'template' out is a discovery mode that lists available templates, and the 'template' values named in the description correspond to the schema's list. It adds little for 'directory' beyond what the schema already says.

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

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

States a specific verb+resource ('creates a starter app') and covers the second mode ('adds teamonly.json and the TeamOnly instructions'), which cleanly separates it from siblings like get_app_rules or deploy. It never names a sibling to contrast with, so differentiation is implicit rather than explicit.

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

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

Gives clear usage conditions based on folder state: empty folder vs. a folder with an existing app, and notes that omitting 'template' returns the template list. It does not say where this fits in the overall flow (e.g., before deploy, or whether sign_in/start_trial is required first).

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 is consistent with a passive capture tool. The description adds genuinely useful behavior the annotations don't cover: capture is time-boxed to a few seconds and requires the user to interact with the app during the window, which shapes how an agent should sequence the call.

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, front-loaded with what is captured and returned, followed by the one operational instruction that matters. 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 compensates by naming the three categories of returned data. It leaves out volume/truncation behavior and whether an empty capture is possible, minor gaps for a read-only capture 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?

Schema coverage is 100%, so both parameters are already documented with defaults and ranges. The description only hints at the duration via 'a few seconds' and says nothing extra about the directory/workspace scoping, so baseline 3 applies.

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

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

The description states a specific verb ('collects') and enumerates the resource contents (requests, console.log output, errors) plus the time-bounded scope. It clearly is not get_app_rules or status, though it never names a sibling to contrast 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?

It gives actionable operational context: ask the person to open the app or trigger the problem while it runs, and that it only captures a few seconds. It stops short of saying when to prefer another diagnostic tool such as get_app_rules or status.

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 discloses that add and remove change roles for people, which is useful beyond the sparse openWorldHint annotation. But with no readOnlyHint or destructiveHint available, it does not describe permission requirements, reversibility, side effects on existing role assignments, or what happens when changing roles.

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 short and front-loaded, stating the tool's purpose before the action details. Every sentence contributes, though the second sentence is somewhat compressed and could be clearer about how add/remove relate to emails.

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

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

For a four-parameter tool with no output schema and sparse annotations, the description covers the core action semantics but does not explain what "show" returns, what form the role data takes, or what confirmation or effects occur after add/remove. It is adequate but leaves meaningful gaps.

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

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

Schema description coverage is 100%, so the schema already documents the parameters. The description adds a small amount of meaning by clarifying the default action and giving role examples, but it does not explain the directory or emails parameters 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 clearly states a specific verb and resource: it shows or changes the roles people have inside the app, with examples like approver and finance. It does not explicitly distinguish itself from sibling tools such as access or get_app_rules, so it falls short of a 5.

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

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

The description names the available actions and notes that "show" is the default, which implies how to use the tool. However, it does not say when to choose this tool over alternatives like access or get_app_rules, nor does it state when not to use 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 openWorldHint and idempotentHint, so the description's added value is the consumption path (ctx.secrets.get(NAME)) and the naming convention, both useful context. It stops short of saying what happens when a name already exists (overwrite vs. error) or whether a redeploy is needed for a running app to pick up the new value.

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

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

Four short sentences, each carrying distinct information: what it does, how the app reads the value, the naming rule, and the security instruction. The core action is front-loaded with zero filler.

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

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

For a simple three-parameter tool with no output schema, the description covers purpose, naming, consumption, and the sourcing rule. The remaining gap is lifecycle behavior: whether the secret is available to an already-running deployment or requires a redeploy, and what happens on a name collision.

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 baseline is 3, but the description adds a normative constraint the schema lacks: names must be UPPER_SNAKE_CASE, not merely exemplified as OPENAI_API_KEY. It says nothing extra about the directory parameter beyond what the schema already documents.

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 (saves a secret) with concrete examples of what a secret is (API key, password) and the scope (for the deployed app). No sibling tool covers secrets, so there is nothing to disambiguate against, and an agent can act on this immediately.

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 explicit operational guidance: ask the person for the value and never hardcode it in code, which tells the agent how to source the input rather than guessing. It does not name alternatives or when-not-to-use, but no sibling covers this capability.

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 provide openWorldHint=true, so the description carries most of the behavioral burden. It discloses the key side effect, that TeamOnly emails a 6-digit code, and explains the two-step interaction and new-company branch, though it does not mention code expiry or failure 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?

Three short sentences, front-loaded with the tool's action and the required first step, followed by the follow-up step and the start_trial branch. Every 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?

For a simple two-parameter sign-in tool with no output schema, the description covers the full interaction flow and the new-company fallback. It does not describe what a successful result looks like or how long codes last, which are minor omissions for this complexity level.

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 already 100%, so the schema documents both parameters. The description adds real meaning beyond the schema by explaining that "email" must be supplied first, that "code" arrives by email, and that the second call uses that code.

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 signs the user in to TeamOnly on this computer. It also distinguishes the two-step email/code flow and points to start_trial for new companies, so an agent can tell it apart from the onboarding 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?

It gives an explicit call sequence: call first with "email", ask the person for the emailed 6-digit code, then call again with "code". It also states when to switch to start_trial when the company is new, which is exactly the kind of when-to-use guidance an agent needs.

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 carry openWorldHint=true, so the description bears most of the disclosure burden. It does add valuable terms: 14-day duration, 1 builder, 3 apps, no card required. But it omits what the call returns, whether it is idempotent or errors on an existing trial, and what happens when the trial expires, which matters for a creation/mutation operation.

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

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

One compact sentence that front-loads the eligibility precondition before the action, with zero filler. Every clause (eligibility, prior sign-in, trial terms) carries actionable information.

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

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

With no output schema, the description should indicate what the agent gets back or what state changes on success/failure. It covers eligibility and trial terms well but leaves return value and post-call state unaddressed, so it is adequate rather than complete for a state-creating 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?

There is a single parameter with 100% schema description coverage ('The company's name'), so the schema already does the work. The description only implies the company must not already have TeamOnly, adding a precondition rather than new meaning about the parameter itself, so baseline 3 applies.

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

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

States a specific verb ('starts a free 14-day trial') and spells out the resulting entitlements (one builder, up to 3 apps, no card). It also names the precondition (company without TeamOnly, after sign_in verified the email), so an agent can distinguish it from subscribe. It does not explicitly contrast with the subscribe sibling, which keeps it from a 5.

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

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

Gives a clear trigger condition: only for a company that doesn't have TeamOnly yet, and only after sign_in has verified the email. This effectively routes the agent away from the paid-subscription path, though the alternative (subscribe) is not named explicitly and no exclusions or repeat-call behavior are stated.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's added value is scope and content: it explicitly says 'on this computer', so the agent knows this is local-machine state, not account-wide cloud data. It also discloses the payload fields, which is meaningful since there is no output schema. It stops short of noting whether multiple accounts or a signed-out state are possible.

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 sentence with the primary answer (who is signed in) front-loaded, followed by plan and app details. Every clause maps to a returned data category, so nothing 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?

With no output schema, the description does the work of documenting return values, and it covers all three groups (user, plan, apps) with their sub-fields. Annotations handle the safety profile. The only gap is edge-state behavior, such as what is returned when nobody is signed in or no apps exist.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; the description correctly implies no inputs are needed.

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

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

States a specific verb ('Shows') and enumerates exactly what is reported: signed-in user, company/plan with trial days, and per-app address, access, and last deploy time. This inventory of contents makes it clearly distinct from siblings like logs, get_app_rules, access, or subscribe without needing to open a schema.

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

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

There is no explicit when-to-use or when-not guidance and no named alternative. Usage is only implied by the phrase 'on this computer', which suggests a local environment check rather than a remote lookup, leaving the agent to infer the trigger condition.

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 carry openWorldHint=true, so the description bears the burden and delivers: it discloses that an external browser page is opened, that payment happens outside the tool, that a link is returned, and that the operation is two-phase and non-idempotent. This is exactly the non-obvious behavior an agent needs before invoking a billing tool.

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

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

Three sentences, each load-bearing: what it does, how the two-step flow works, and the plan menu. The critical behavioral fact (opens a payment page, call again to finish) is front-loaded before the pricing 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?

With no output schema, the description correctly states the return value (a payment link) and explains the resumption call. It omits edge cases such as what happens when a subscription already exists or whether the second call needs the same plan/company, which matters for a billing mutation.

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% but the schema descriptions are bare ("Plan", "The company's name"), so the description adds real value by mapping each enum value to price, seat count, and included features. The optional company parameter is never mentioned, leaving one small gap.

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 ("Starts paying for TeamOnly") plus the immediate side effect ("also ends a free trial"), which cleanly distinguishes it from the sibling start_trial. An agent can tell what this does and what it is not 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?

Gives an explicit sequencing rule that would otherwise cause failure: "The person pays there; call subscribe again afterwards to finish." The parenthetical about ending a free trial implies the relationship to start_trial, but it never names that sibling as the alternative, so it falls short of a full when/when-not statement.

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