doola

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description goes well beyond by disclosing that it legally accepts Terms of Service on the user's behalf, that it creates a real Stripe checkout, the refusal code, and the prerequisite gate. It also tells the agent exactly how to quote the returned pricing fields (verbatim, never 'charged today'), which is behavioral context annotations cannot carry.

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 action and the safety gate, then the return-field quoting rules and the refusal condition — all operationally necessary. The Terms of Service link and the 'show and ask the user' instruction are repeated twice, minor redundancy in an otherwise dense 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?

Covers preprequisites, consent gating, refusal behavior, and how to use each returned field, so an agent can act correctly without further lookup. Return-value handling is spelled out even though an output schema exists, which is appropriate for a payment-related side effect.

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 operational meaning for termsAccepted by tying it to a user-confirmation workflow rather than just a boolean flag. It adds nothing for context/llm_model, but those are analytics-only and already self-documented.

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 action chain: accepts the Terms of Service on the user's behalf and creates the Stripe checkout for the formation, plus names the company being paid for. It is clearly separable from siblings by naming verify_payment for the returned session ID and start_formation as the prerequisite.

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 gating workflow: show the ToS link, ask the user, and only call with {termsAccepted: true} after they say yes. It also states the exact refusal condition (PRECONDITIONS_NOT_MET until start_formation has saved name, country, and company name), leaving nothing 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, openWorldHint=false, destructiveHint=false, so safe-read is established; the description adds genuinely new scope constraints — it only ever reads the *active* company and requires `switch_active_company` to change target. It doesn't mention auth/permission requirements or whether inactive/dissolved companies are visible, which is the remaining gap for a data-retrieval 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?

Front-loaded with the core purpose in the first clause, then field inventory, then usage cues and the sibling exclusion in the final sentences. The long parenthetical field list and the URL mirror reference are slightly padded, but each sentence carries routing or scoping 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 an output schema present, return values need no explanation, and annotations cover safety; the description supplies the active-company scoping and sibling routing that structured fields don't. The one omission an agent might want is whether inactive/other-company data is reachable without switching, which is only implied.

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 both parameters (`context`, `llm_model`) are analytics-only plumbing fully documented inline, so the schema carries the burden. The description contributes nothing about parameters, and none is really needed; 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 ("Returns the active company's full profile") and enumerates the concrete data returned: basic info fields, members, responsible party, addresses, name options, provisioned services. It explicitly names the sibling it is not — `get_company_onboarding_status` — and explains the distinction (derived routing vs. raw data), so an agent can differentiate without opening 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?

Gives concrete trigger utterances ("tell me about my company", "what's my EIN?", "who are the members?") plus an explicit exclusion against the nearest sibling. It also states a prerequisite path for the alternative case: call `switch_active_company` first to inspect a different company. When-to-use, when-not, and alternatives are all covered.

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 and openWorldHint, yet the description adds real operational context: implicit auth via bearer (no customerId argument), the derivation rule (steps complete when Company/Customer fields are populated), the effect of re-calling (rate limit), and an error-recovery protocol (error:true or inconsistent suggestedNextStep → wait ~10s and retry rather than redo steps). This is well past what annotations convey.

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 instruction and no filler, but the central 'do not call between steps' rule is stated twice (paragraph two and again in the 'only call AGAIN when…' paragraph), which costs a bit of length without adding 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?

Even though an output schema exists, the description explains the two fields that actually drive agent behavior (suggestedNextStep and the {tool, arguments} placeholder template in nextActionInput) and covers the failure path. Nothing an agent needs to act correctly on this response 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% and the only params are analytics-only (context, llm_model), so the schema carries that burden. The description adds the one non-obvious semantic point — no arguments are needed because customerId is derived from the bearer token — which prevents an agent from hunting for a customer identifier.

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 role — the canonical 'where am I?' entry point for formation/onboarding progress — and immediately disambiguates from the sibling formation tools by saying their responses already carry nextAction. An agent can tell instantly what this returns and why it differs from start_formation, save_company_details, or switch_active_company.

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?

Explicit when-to-call (once per session, right after OAuth), when NOT to call (between formation steps, with a stated reason: latency and rate-limit burn), and an exhaustive enumeration of the three re-call conditions. It also names the downstream alternative (start_formation) for the pre-formation case.

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 establish that this is a safe read-only operation, and the description adds crucial behavioral context: the entry with isActive true is the target of all other formation tools. That relationship is not captured by annotations or schema and materially affects how an agent should use the result.

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 front-loaded with the core purpose and then adds only high-value routing and active-company context. Every sentence contributes to correct tool selection or interpretation.

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 annotations covering safety, an output schema covering return values, and 100% parameter description coverage, the description supplies the remaining critical context about active-company semantics and sibling-tool routing. Nothing needed to call it 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 description coverage is 100%, and both parameters are optional analytics-only fields. The description does not add meaning beyond the schema, but the schema already carries the necessary semantics, so the baseline of 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 uses a specific verb and resource: returns every company the authenticated customer owns. It clearly distinguishes this inventory operation from sibling tools like switch_active_company and start_new_company.

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 explicitly names three triggering situations: the user asks which companies they have, wants to switch context, or is about to start a new formation. It also routes the agent to switch_active_company for changing the active company and start_new_company for creating a new one.

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 say readOnlyHint=false / destructiveHint=false; the description adds the crucial context of what the write actually does ('records the request for doola's team'), that it 'changes nothing on the customer's account', and that no new tools are returned despite an output schema existing. That is exactly the extra behavioral detail annotations cannot convey.

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 tight sentences ordered trigger → input → side effect → follow-up. Every sentence carries information an agent needs, and the invocation condition 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 two-parameter reporting tool with an output schema, the description covers everything needed: when to call, what to put in the required field, what the call does to the account, and what to tell the user afterward.

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 already spells out both `context` (including the PII prohibition) and `llm_model`. The description only restates that the goal and desired tool type go in `context`, so the baseline 3 applies since 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 states a specific action (record a request for a capability that doesn't exist) and explicitly positions it as the fallback when 'none of the other tools can do' what the user wants, which cleanly separates it from every sibling like start_formation or verify_payment.

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 trigger ('when the user wants something none of the other tools can do') and explicit post-conditions for how to proceed afterward ('tell the user this isn't available here and point them to the doola dashboard'), leaving nothing 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 flag destructiveHint=true and readOnlyHint=false; the description adds real value on top by disclosing the all-optional/partial-save semantics, the PRECONDITIONS_NOT_MET failure mode, and that the response carries a `missing` list plus nextAction/nextActionInput. It stops short of warning that `members` replaces the entire saved member set, which is the most consequential destructive behavior and matters most for a tool annotated destructive.

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, front-loaded with the resource, then behavior, then the gate. Every sentence carries distinct information — no restatement of the title and 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 10-parameter mutation with an output schema, the description covers purpose, incremental calling pattern, precondition gate, and error code, so an agent can call it correctly. The one omission is the destructive overwrite semantics of `members` and of re-saved fields, which the agent must learn from the schema rather than the description.

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

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

Schema description coverage is 100%, so the schema already explains enums, formats, and per-field constraints. The description contributes only the general framing that every field is optional and persisted as given; it adds no field-level meaning beyond what the schema states (e.g. industry must come from search_industries, members must total 100%).

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 (Saves) and a specific resource (the company's post-payment details), then enumerates exactly which fields belong to that bundle: industry/description, backup names, addresses, members with ownership, and the IRS responsible party. An agent can tell this apart from read-side siblings like get_company_info or get_company_onboarding_status 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 explicit calling cadence ('save each answer as soon as the user gives it'), an explicit precondition ('Refused with PRECONDITIONS_NOT_MET until verify_payment has confirmed payment'), and names the next-step driver in the response. This is when-to-use, prerequisite, and follow-on routing in one place.

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, destructiveHint=false and openWorldHint=false, so 'Read-only; takes no arguments' largely restates structured data. The genuine value-add is the verbatim-pass-through rule, which warns the agent not to paraphrase or normalize the returned value — a real failure mode. It does not describe the shape of the returned list, but the output schema covers that.

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, zero filler: purpose first, then the workflow, then the read-only note. Every sentence carries distinct information and the actionable instruction 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?

An output schema exists, so return-value detail is not required, and the description supplies the one thing the schema cannot: what to do with the results. Only minor gap is no hint about how large the list is or whether it is exhaustive, which affects how the agent should present candidates.

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 optional analytics parameters are fully documented in the schema, and the 0-required baseline applies. The description adds nothing about `context` or `llm_model`, and 'takes no arguments' is mildly imprecise given two optional params exist — though it correctly signals no substantive input is needed.

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

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

States a specific verb and resource ('Lists the industries a company can be filed under') with the scoping detail that this is the enumeration used for company filing. It is unmistakably distinct from save_company_details and the other siblings, which all deal with company records rather than the reference list.

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 multi-step usage pattern: match the user's business description against the list, offer 3-5 closest entries, and pass the chosen value verbatim as `industry` to save_company_details. The downstream sibling and the condition for calling it are both named, leaving nothing 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context on top: all fields optional, values saved as given (persistence semantics), partial-profile handling, and that the response's nextAction drives the next step. It stops short of covering repeated-invocation behavior (whether re-calling restarts or merges state), which matters for a 'start formation' mutation.

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 tight sentences with zero redundancy: purpose, call timing, safety constraint, and return routing, in that priority order. The most decision-relevant instruction ('call it as soon as you have an answer') 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-required-param mutation tool with full schema coverage, an output schema, and annotations, the description supplies everything an agent still needs: when to call, the empty-object case, the no-fabrication rule, and where the next step comes from. Nothing required to invoke it 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%, so every parameter is already documented in the schema, including the firstName/lastName pairing and the 'never invent' constraint on companyName. The description mostly restates those same constraints rather than adding syntax, format, or interaction rules beyond them. Baseline 3 is appropriate 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?

Opens with a specific verb and resource: 'Starts the user's Wyoming LLC formation', then enumerates exactly what gets persisted (legal name, country of residence, company name, formation state). It does not explicitly differentiate itself from siblings like submit_formation, start_new_company, or save_company_details, which is the only thing keeping 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 concrete call timing ('call it as soon as you have an answer') and a specific edge case ('call it with {} to set the state when nextAction says so'). It also states the conditional-save rule for the legal name. It never names an alternative sibling or says when NOT to use this tool, so 4 rather than 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the concrete side effects: an empty in-progress Company row is created, linked to the customer, and pinned as active. It also reassures that the previously active company is untouched and recoverable, which is exactly the state-change context an agent needs before a mutation.

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 tight sentences, front-loaded with the trigger condition before the mechanics and follow-on flow. Every clause carries distinct information (scope, side effect, next step, recovery path) with no restatement of the name or title.

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 state-mutating tool with an output schema, the description covers the trigger, the created state, the active-company side effect, and the next action. Return values are named only as needed ('the response names it') rather than re-specifying the schema, which is appropriate.

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 both parameters (context, llm_model) are optional analytics-only fields already documented in the schema. The description adds nothing about them, so baseline 3 applies — the schema does all the work and the description does not need to compensate.

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 (begin a brand-new Wyoming LLC formation) and scopes it explicitly to a second-or-further company, which separates it from the first-company formation path. It also names two siblings (list_companies, switch_active_company) so an agent can place it in the tool graph without opening 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?

Gives an explicit trigger ('call when the customer explicitly asks to form a SECOND (or further) company'), names the alternatives for viewing and switching companies, and prescribes the follow-on step ('follow the standard formation flow from its first step'). Nothing about when or when-not to call 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?

Annotations already declare destructive and openWorld, but the description adds the concrete stakes: the filing cannot be undone, external emails are dispatched to a third party for signing, and premature calls are rejected with a structured preconditions error. That is substantive context beyond the hints.

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 doing distinct work: what it does and its side effects, the precondition for calling, and the refusal behavior. The most important constraint (irreversibility) is front-loaded in sentence one and the hard gate follows immediately.

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 an irreversible, externally visible action, the description covers effect, side channels, gating condition, and error semantics; the output schema handles return values. Nothing an agent needs before invoking 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%, so all three parameters are already documented, including the exact meaning of userConfirmed. The description reinforces userConfirmed by tying it to the summary-table presentation, but adds nothing for context or llm_model. Baseline 3 is appropriate 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 chain: files the Wyoming LLC with the state via doola's registered agent and emails SS-4 and Form 8821 to the responsible party. The side effects alone distinguish it from siblings like start_formation or create_checkout_session, which prepare or pay rather than file.

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 gate: call ONLY after presenting a complete summary table and receiving an explicit 'submit' reply, with the {userConfirmed: true} flag. It also names the failure mode (PRECONDITIONS_NOT_MET with a `missing` list) so the agent knows what to expect if it calls early.

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?

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false) by disclosing that the switch is a process-local override, that it may be lost on a different MCP replica and should simply be re-invoked, and that unknown IDs are rejected. It also tells the agent the response mirrors get_company_onboarding_status, which is exactly the context a mutating tool needs.

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 sentences, front-loaded with the action and the trigger condition, then the ID constraint, then the return-shape and replica caveats. Every sentence carries information an agent needs at decision time.

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?

An output schema exists, and the description still explains that the response matches get_company_onboarding_status, telling the agent how to use the result to resume onboarding. Prerequisite sourcing, error behavior, and state lifetime are all covered for this stateful switch operation.

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 applies; the companyId constraint is already documented in the schema. The description repeats the list_companies provenance rule and adds the consequence ('unknown IDs are rejected'), which is useful but only marginally beyond the schema, and it says nothing about the analytics-only fields.

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 precise verb ('point the formation tools at') and resource ('a different company the customer already owns'), making the scope of the change unambiguous. It is clearly distinct from siblings like list_companies (discovery) and get_company_onboarding_status (status read).

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 to use it when the customer asks to manage/continue/inspect a specific company by name or ID, and routes to list_companies as the required source of IDs. It also covers the reconnect/replica retry case, though it never states when not to use it (e.g., when the company is already active).

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 declare readOnlyHint=false and openWorldHint=true, and the description goes further by disclosing the state side effect: a confirmed payment makes that company active and causes post-payment tools to write to it. It also surfaces the gating semantics tied to paymentStatus=Complete, which no annotation 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?

Four short sentences, front-loaded with the action, then the trigger, the gate, and the side effect. 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?

An output schema exists, so return values need no elaboration, yet the description still names the decisive paymentStatus value. For a payment-verification step with real state consequences, the agent has everything required to call it correctly and to sequence follow-up 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 description coverage is 100%, so the schema already documents all three parameters including the analytics fields. The description adds only the provenance of checkoutSessionId, which the schema itself already states, so a 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 ('Checks with Stripe whether the formation checkout was paid') and implicitly contrasts with create_checkout_session by consuming its output. An agent can distinguish it from sibling tools without inspecting 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 trigger ('once the user says they've paid'), the required input source (checkoutSessionId from create_checkout_session), and a hard exclusion ('Do NOT ask any post-payment question until it returns paymentStatus=Complete'). This is exactly the when/when-not 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.