corply

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

The description adds rich behavioral context beyond annotations: it records assertions rather than verified facts, returns a refreshed get_company_briefing result, requests supporting documents, supports idempotent retries but rejects same-key-different-input reuse, and explicitly states the action does not file, pay, sign, invite, or verify. It also confirms the save is reversible and that no extra confirmation is needed.

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 contains substantial redundant and generic boilerplate, such as repeating the prerequisite sentence and adding generic idempotency and confirmation-boundary policy blocks. It is much longer than necessary and buries the core tool-specific behavior under repetitive guidance.

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

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

For an 8-parameter, no-output-schema tool with minimal annotations, the description covers the action's purpose, prerequisites, return value, idempotency semantics, safety profile, and follow-up document requests. It is functionally complete for an agent to select and invoke the 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 only 13%, so the description must compensate. It explains the roles of assertedName, jurisdiction, entityType, formationDate, fileNumber, companyId, and idempotencyKey, including idempotency-key reuse restrictions. The only parameter not clearly covered is _corply_context, though it has a schema description and the description references context_engineering.

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 a specific verb and resource: 'Attach an already-existing company without creating a Corply formation.' It clearly states what data is recorded and that these are 'founder assertions—not verified facts,' distinguishing it from formation and verification-oriented 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?

The description provides explicit prerequisites: active company-manager access, explicit companyId when multiple companies exist, stable idempotencyKey, and authenticated organization access. It does not name alternative sibling tools or state when not to use them, but the purpose and prerequisites make the intended context clear.

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 it does not sign, file, charge, or mutate cap-table records, which is a behavioral constraint beyond annotations. It also mentions 'no additional confirmation is needed'. However, it doesn't clearly state that it modifies the case status or what side effects occur. The mention of 'attorney approval' is ambiguous.

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 lengthy and repetitive, with many redundant phrases like 'requires the exact current expectedStatus' and 'stable idempotency key' paraphrased multiple times. The inclusion of unusual terms like 'context_engineering' and 'actual_tool_output' further reduces clarity. It could be condensed to a few clear sentences.

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 provides some preconditions (authenticated active organization access) and mentions idempotency but lacks information about the return value or expected outcomes. There is no output schema, so the agent doesn't know what the tool returns. The mention of 'confirmation boundary' hints at behavior but overall context is incomplete.

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

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

Only _corply_context has a schema description; others like caseId, reason, companyId, nextStatus, expectedStatus, and idempotencyKey lack explanations. The description references expectedStatus and idempotencyKey but not the others. The enum values for statuses are not explained. Overall parameter semantics are poorly covered.

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 'advance' and resource 'corporate action case', but the verbose wording about 'explicit durable state graph' and 'actual_tool_output' adds confusion. It does distinguish from sibling create/list/get tools by implying a state transition, though it's not entirely clear.

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

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

It mentions requirements like matching expectedStatus and using an idempotency key, which are usage constraints. However, it doesn't explicitly compare to alternative tools or specify when to use this vs. other transition tools. The guidance is implicit rather than explicit.

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

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

Beyond the annotations, the description discloses major effects: it supersedes frozen legal documents, reopens intake, requires regeneration and fresh signatures, deep-merges partial data, and returns server-authoritative output. It also warns against state-recovery calls and addresses idempotency, which is essential for a destructive 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?

The core effect is front-loaded, but the latter half contains generic guardrails ('Canonicality', 'Idempotency', 'Confirmation boundary') that could be trimmed or folded into the prerequisites. Still, for a destructive tool, the repetition is not disqualifying.

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 high-stakes destructive mutation with no output schema, the description covers prerequisites, user-confirmation requirements, return shape, canonicality, and idempotency. An agent has enough context to decide whether and how to call it.

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

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

With 67% schema coverage, the schema carries most parameter documentation, but the description adds meaningful behavior: 'Partial data still deep-merges over stored answers' clarifies how the main data parameter is applied. This goes beyond the schema's property definitions.

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 opening sentence names a specific action ('apply confirmed answer changes') and a precise resource ('frozen, pre-submission formation'), and the second sentence distinguishes it from ordinary save/validate flows by listing the superseding, reopening, and regeneration consequences. This makes the tool's unique role clear without needing to read sibling names.

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 an explicit gate: 'Use only after the founder explicitly confirms that consequence' and repeats it as a confirmation boundary. It does not name alternative tools, but for a destructive action the when-to-use condition is clear.

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?

With only minimal annotations, the description carries the behavioral burden and does so well. It discloses that the tool records an immutable reference only, does not assert underlying events occurred, forbids sensitive data in metadata, instructs trusting returned output over a state-recovery call, and explains idempotency and confirmation expectations. This adds substantial context beyond the annotation defaults.

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 first sentence is strong and front-loaded, and the section labels create structure. However, the description includes boilerplate phrases that don't fully apply, such as 'plus every prerequisite stated above' when none were stated, and a confirmation-boundary list that mentions 'read' for what is a write/append operation.

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 9 parameters, nested objects, no output schema, and very low schema description coverage. The description covers safety and idempotency but omits required parameter semantics, expected reference format, evidence type meaning, and what the caller receives in return. This is not complete enough for an agent to call the tool confidently without additional inference.

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 only 11%, so the description must compensate by explaining the many required parameters. It only meaningfully addresses metadata restrictions and indirectly references idempotencyKey and contentHash. It does not explain reference, evidenceType, title, caseId, companyId, or how the hash should be computed/used.

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 a specific verb and resource: 'Append hash-backed evidence to one exact company-scoped corporate-action case.' This clearly identifies the operation and differentiates it from sibling tools like create_corporate_action_case, upload_operating_evidence, and submit_operating_fact_evidence by scoping it to a corporate-action case.

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 the tool is for adding evidence to an existing corporate-action case, and it gives operational guidance around prerequisites, canonicality, idempotency, and confirmation. However, it never explicitly says when to choose this tool over alternatives, and the 'prerequisite stated above' phrase refers to nothing concrete.

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?

Discloses important hidden behaviors beyond annotations: the ~8-second per-call wait, the gateway killing long-held requests, retryAfterSeconds on 'pending', and the fact that returned outputs should be trusted rather than supplemented with state-recovery calls. This materially helps an agent invoke it correctly even though annotations already mark it non-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?

The description is longer than average and includes generic boilerplate about canonicality, idempotency, and confirmation boundaries, but the core operational content is front-loaded and each status-handling branch earns its place. The length is justified by the polling complexity.

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 polling tool with no output schema, the description fully explains the statuses, loop behavior, timeout, prerequisites, and coordination with sibling tools. An agent has enough context to use it correctly in a multi-step formation workflow without needing to infer return shapes or failure modes.

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 67%, with formationId left undocumented. The description reinforces maxWaitSeconds' ceiling via the gateway note but adds little for formationId beyond the obvious 'incorporation' context. It does not fully compensate for the undocumented required parameter, but it does not mislead either.

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-resource pair ('Wait for the incorporation payment') and precisely defines its return value as one of four statuses. It clearly differentiates from siblings like request_payment and get_payment_pipeline_status by framing this as the blocking/polling step.

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 instructs the agent to call in a loop until 'paid', names the exact sibling tools that must not be called before that point, and gives per-status next actions ('expired' → request_payment, 'unpaid' → request_payment). This is model usage 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?

Annotation contradiction: the description calls this operation 'this read' in the confirmation boundary, while the annotations set readOnlyHint to false. Under the rubric, a direct contradiction with annotations requires a score of 1. The description otherwise adds useful timing and canonicality context, but the contradiction dominates.

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 tool-specific content is well organized and front-loaded with statuses and loop instructions. However, the final three sentences (canonicality, idempotency, confirmation boundary) are generic boilerplate that adds vagueness and length without tool-specific precision.

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 polling tool with no output schema, the description fully covers return values, retry logic, timeout behavior, and the sibling tool to call on failure. It loses a point because phrases like 'every prerequisite stated above' are undefined and formationId semantics are not explained.

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 67%, so the schema already documents maxWaitSeconds and _corply_context; the description adds the ~8-second gateway ceiling and retryAfterSeconds context. However, the required formationId parameter is left undocumented in both the schema and description, and _corply_context usage is not elaborated beyond its schema description.

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 (Wait) and resource ($350 lifetime registered-agent upgrade), and enumerates the return statuses. It also names sibling request_registered_agent_upgrade, making the distinction between the wait action and the request action 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?

Provides an explicit control flow: loop until 'lifetime', call request_registered_agent_upgrade again on 'expired', and call it first on 'unpaid'. The ~8-second wait bound and retryAfterSeconds hint further clarify how to use the tool in practice.

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, the description discloses external-provider dependencies, caching behavior ('Previously rejected names return false without another provider call'), and the advisory/non-blocking nature of results. It also states prerequisites and the confirmation boundary. This adds substantive behavioral context above what readOnlyHint/openWorldHint/destructiveHint alone 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?

The core description is front-loaded and clear, but it is buried in generic boilerplate: 'Canonicality', 'Idempotency', 'Confirmation boundary', and 'plus every prerequisite stated above' add little tool-specific value and make the description unnecessarily long. The repeated generic instructions violate the 'every sentence earns its place' standard.

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 is complete enough for an agent to call the tool correctly: it explains the provider call, the return values, caching, prerequisites, and how to treat results. It also tells the agent not to add recovery calls. Minor gaps remain around the exact output structure, but with no output schema present the description still covers the essential behavior.

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

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

With only 25% schema coverage, the description compensates well: it explains selectedName ('Pass the currently saved selectedName exactly') and similarNames ('up to five supplied alternatives', 'preserve the desired alternative order'). formationId is implicitly tied to 'the formation's saved company name', and _corply_context is already described in the schema. The key semantics are covered despite the low 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?

The description opens with a specific verb and resource: 'Check the formation's saved company name and up to five supplied alternatives through OpenSOSData.' It clearly distinguishes the tool from siblings by naming its exact scope and external provider, and it explains the output semantics (true/false/null) which further pins down 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 context on when to use the tool: it is advisory, never blocks document generation, and the mandatory Delaware check is explicitly handled elsewhere ('Corply operations performs the mandatory Delaware check immediately before filing'). It also instructs the agent to trust the returned output rather than adding a state-recovery call. It does not name a specific sibling alternative, but the usage boundary is clear.

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=true, openWorldHint=false, destructiveHint=false), the description discloses zero provider calls, zero charges, canonicality ('reads current server state and does not manufacture company facts'), idempotency, the full refusal set (drifted manifests, duplicate identifiers, mismatches, contradictions), and a confirmation boundary. No contradiction with annotations: the disclosed 'reversible save' is explicitly framed and consistent with the no-external-side-effects meaning of readOnlyHint.

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 long but dense and well-structured with labeled sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) and a front-loaded purpose statement. Minor redundancies such as 'plus every prerequisite stated above' and the generic confirmation-boundary laundry list keep it from a perfect score.

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 3-parameter tool with deeply nested schemas, no output schema, and a compliance-heavy domain, the description covers purpose, failure/refusal modes, side-effect profile, idempotency, prerequisites, and sequencing. The main gap is that, with no output schema present, the description never states the result/return shape, and it leans on unstated context through 'every prerequisite stated above.'

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?

Top-level schema description coverage is only 33% (only _corply_context is described), so the description must compensate — and it does: it clarifies that inputs contain environment-variable NAMES only, never Paddle IDs, API keys, webhook secrets, bank/card data, or customer data, and that product/price/entitlement keys and the SaaS category are agent-derived rather than founder-supplied. It does not name the three top-level parameters explicitly, but the semantics it adds materially shape how the manifest and products should be populated.

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: 'Validate and deterministically add the founder-approved fixed-price SaaS subscription catalog to an integrity-hashed Corply Pay manifest.' It goes beyond a generic statement by enumerating what the tool refuses and naming the successor call (create_payment_integration_bundle), which differentiates it from the 50+ siblings.

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

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

The description gives clear context for when to call it — after a founder-approved fixed-price SaaS catalog exists — states a prerequisite ('authenticated active organization access'), and routes the agent to the next call (create_payment_integration_bundle). It lacks an explicit when-not-to-use contrast with siblings such as create_payment_project or verify_payment_integration, and the phrase 'every prerequisite stated above' is vague.

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, it discloses that the action is non-destructive to the cap table, idempotent, and requires no additional confirmation. The phrase 'this read' is slightly misleading for a create operation, but it does not contradict readOnlyHint=false and the description generally adds useful behavioral 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?

The first sentence is strong, but the rest is padded with generic boilerplate about prerequisites, canonicality, idempotency, and confirmation boundaries. Several sentences read like reusable policy text rather than tool-specific guidance, making the description longer than its unique informational content justifies.

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, complex nested parameters, and sparse annotations, the description still leaves important gaps: it does not explain the intake object, the meaning of actionKind, the expected return shape, or the _corply_context parameter. It gestures at returned actual_tool_output and context_engineering but does not describe them sufficiently.

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 only 14%, so the description must compensate for undocumented parameters. It explains policyVersion, companyId, and idempotencyKey, but leaves actionKind, title, intake, and _corply_context semantically unexplained despite them being required or structurally significant.

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 a specific verb and resource: 'Create an attorney-review draft case for one canonical one-time corporate action.' It also clarifies what the tool does not do (does not provide legal advice, sign documents, file anything, mutate the cap table), which distinguishes it from downstream transactional 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?

The description gives clear context: this records an intake case only and should be used with an exact companyId and stable idempotency key. It states exclusions ('does not ... issue/cancel/transfer shares') but does not name alternative sibling tools or explicitly say when to use them instead.

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 readOnlyHint/destructiveHint annotations, the description adds meaningful behavioral detail: 'Makes zero provider/network calls, writes no files itself, never overwrites existing files, and never handles credential values.' It also explicitly states idempotency, canonicality, and the verify-exact manifest constraint, giving the agent a complete side-effect profile. There is no contradiction with the annotations.

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

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

The description is dense and long, but it is front-loaded with the core purpose and safety guarantees before moving into workflow. It follows a logical order: purpose, constraints, required agent steps, prerequisites, canonicality, idempotency, and confirmation boundary. Some policy-heavy phrasing could be tightened, but nearly every sentence adds an operational 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 complex tool with no output schema, the description covers the plan contents, side-effect guarantees, prerequisite auth, verification loop, and repeatability, which is quite complete. It falls short only in explaining the exact return shape and the roles of _corply_context and includeExamplePricingPage, though the rich manifest schema partially compensates.

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

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

With only 33% schema description coverage, the description needed to compensate by explaining _corply_context and includeExamplePricingPage, but it does not. It references 'a valid catalog manifest' and says the manifest must be verify-exact, yet it never clarifies the two non-manifest parameters. The nested manifest schema itself carries useful descriptions, but the low-coverage parameters remain unexplained.

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 a concrete verb+resource: 'Generate a reviewable repository patch plan from a valid catalog manifest' and enumerates exactly what the plan contains. This clearly distinguishes it from sibling create_payment_project or create_payment_route_draft tools because it emphasizes plan generation and explicitly states it writes no files itself.

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 strong workflow guidance: prerequisites, the calling agent's mandatory steps, the follow-up call to verify_payment_integration, and the instruction not to execute afterPublishCommand prematurely. It does not explicitly name alternative sibling tools or when not to use this one, but the context and step sequence are clear enough for correct invocation.

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?

Even with readOnlyHint=true, the description adds substantial context: it makes zero provider calls, stores no hosted state, creates no Paddle account/catalog, charges nothing, accepts no secret values, is idempotent, reads current server state, and the hash is not an approval/signature. This goes well beyond the annotations and clarifies exactly what side effects do not occur.

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 long but well front-loaded with scope and prerequisites, and nearly every clause adds safety or workflow value. The 'Confirmation boundary' sentence is somewhat overwrought and the prerequisite text is slightly redundant, but the labeled sections make the dense information navigable.

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 11-parameter tool with no output schema, the description covers effects, idempotency, prerequisites, and next steps well. However, it never describes the shape of the returned project/hash/manifest, which the agent needs to commit the manifest, and it leaves several required inputs unexplained. The workflow context is strong, but the output contract is too vague for a draft-generation 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 description coverage is only 18%, so the description needed to compensate for undocumented parameters, but it only refers to inputs generically. It adds that projectKey and inputs determine the deterministic result and that secret values should not be passed, but it does not explain key required parameters like businessModel, billingModel, customerType, or targetCountries beyond their enum names.

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 by naming the exact scope (Legacy Paddle path only) and a precise action: generate an integrity-hashed sandbox-only manifest after prepare_revenue_launch reports sandbox_build_ready. It also names the next workflow step, configure_payment_catalog, making the tool's role unambiguous among many payment siblings.

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

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

It states explicit when-to-use conditions: legacy Paddle path, after prepare_revenue_launch returns sandbox_build_ready, and with authenticated active organization access. It does not explicitly name alternative tools, but the 'Legacy Paddle path only' restriction and the 'Next call' pointer provide strong routing.

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

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

The description goes well beyond the annotations, which only say readOnlyHint=false and destructiveHint=false. It discloses that the save is reversible, makes zero provider calls, creates no external account, activates nothing, moves no money, and is idempotent via exact replay. These are concrete behavioral details an agent needs before invoking the 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 first two sentences are high-value and front-loaded, but the description includes generic boilerplate sections like Canonicality, Idempotency, and Confirmation boundary. The confirmation-boundary sentence in particular lists many unrelated action types and does not earn its place for this specific tool.

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 covers prerequisites, exact idempotent behavior, side effects, next-step guidance, and what remains out of scope. Since there is no output schema, mentioning that the agent should trust returned actual_tool_output and context_engineering is helpful, though it does not describe the draft's return payload in detail.

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 only 20%, and the description partially compensates by naming the accepted categories: company, route key, USD, and idempotency key, while explicitly excluding credentials, provider IDs, bank/card data, and production settings. However, it does not explain individual parameters such as routeKey semantics, companyId optionality, or the _corply_context object 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?

The description opens with a specific verb and resource: 'Create or exactly replay one local sandbox merchant-route draft for Corply's own payment pipeline.' It clearly separates this draft-creation action from activation, provider onboarding, and live enablement, and the 'local sandbox' qualifier distinguishes it from production-oriented sibling 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?

The description states clear usage context: this is for a sandbox merchant-route draft only, cannot accept production settings, requires authenticated active organization access, and should be followed by get_payment_pipeline_status. It also lists actions that are NOT this tool's job. However, it does not explicitly name alternative creation/onboarding sibling tools for direct comparison.

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?

Discloses immutability of generated documents, automatic 83(b) execution under advance authorization, the supersession cascade triggered by editing a generated application, and the idempotency rule about retry keys. No contradiction with annotations: readOnlyHint=false matches the creation behavior, and destructiveHint=false is not contradicted because the supersession effect belongs to an editing flow rather than to this generation action itself.

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?

Every sentence carries information and the core concept is front-loaded, but roughly 300 words are packed into one unbroken paragraph blending five distinct topics: phase outputs, confirmation boundary, supersession, prerequisites, and idempotency. The density reduces scannability even though there is no wasted prose.

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 multi-phase document-generation tool with no output schema and only minimal boolean annotations, the description covers the critical operational facts: phase-dependent outputs, confirmation boundary, idempotency rule, prerequisite, and canonicality. It stops short of describing the return payload or failure behavior when formation status is outside ready/formed, which would be needed for a 5.

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 already documents _corply_context ('Echo context_engineering.context_session from the prior Corply result'), but formationId has no schema description and the tool description never names either parameter. The description adds indirect meaning by framing the formation lifecycle the parameter refers to (status phases, checkpoint confirmation, context_engineering echoing), but the agent must infer how these map onto formationId and _corply_context.

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 pair ('immutable generation' of formation documents) and differentiates by phase: status 'ready' yields only the Certificate of Incorporation, while 'formed' yields Bylaws, RSPAs, an unsigned SS-4, and an automatic 83(b) Election. This clearly separates it from siblings like save_application, submit_for_formation, and sign_bundle based on what it produces and when.

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 when-to-call conditions tied to formation status ('ready' vs 'formed') and explicitly carves out the automatic 83(b) retry that requires no new approval, while declaring 'confirm before creating immutable legal documents' for all other cases. It also names the prerequisite (authenticated active organization access) and instructs the agent to trust actual_tool_output rather than adding a state-recovery call.

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 readOnlyHint and destructiveHint annotations, the description adds substantial behavioral detail: it never reads or returns SSNs, identity documents, provider credentials, or KYC payloads; handoff URL access is restricted by membership role; it reads canonical server state and does not manufacture facts; it is idempotent; and no confirmation is required. This is strong, non-redundant transparency.

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 main use is front-loaded, but the description becomes bloated with generic boilerplate. 'Prerequisite: authenticated active organization access plus every prerequisite stated above' is vague and circular, and the 'Confirmation boundary' sentence lists many unrelated action categories, making the description longer than needed without adding tool-specific precision.

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?

There is no output schema, and the description only names broad return categories without explaining their structure or how to interpret them. More importantly, it omits parameter semantics entirely, so an agent cannot confidently determine which identifiers to supply. The behavioral and authorization context is strong, but the input side of the tool is under-specified.

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 only 33%, and the description does not compensate for the undocumented companyId and applicationId parameters. It never explains whether one or both are needed, which ID is required for the bank-onboarding context, or how _corply_context should be used. The description is entirely about outputs and behaviors, not input semantics.

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

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

The description clearly names a specific verb-resource pair ('get bank onboarding status') and lists concrete return categories: durable Mercury prefill handoff, in-flight/reconciliation state, or direct Mercury fallback. It lacks explicit sibling differentiation, though 'First tool for opening a company bank account' provides some separation from start_bank_onboarding and reconcile_bank_onboarding.

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 useful usage context: it is the first tool to use for opening a bank account and requires authenticated active organization access plus membership prerequisites. However, it does not explicitly state when to prefer this over siblings like get_status, start_bank_onboarding, or reconcile_bank_onboarding, nor does it mention 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 mark it read-only and non-destructive, so the bar is lower. The description adds genuinely useful behavioral context: auto-seeding with founder common stock, canonicality (reads current server state), idempotency, and no confirmation needed. These disclosures go beyond the structured annotations without contradicting them.

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 opening sentence is efficient and informative, but the rest of the description is padded with generic boilerplate. The prerequisite sentence is broken and references nonexistent content, and the confirmation-boundary sentence lists many unrelated categories, adding noise rather than value.

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 getter, the description covers the main return contents well, which compensates for the lack of an output schema. However, it leaves parameter semantics ambiguous, references nonexistent prerequisites, and does not clarify how companyId or _corply_context should be supplied. This is adequate but not complete.

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

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

Schema description coverage is only 50%, with companyId lacking any schema description, so the description needs to compensate. It only vaguely implies companyId identifies the company via "the company's live cap table." It does not explain the parameter's format, optionality, or relationship to _corply_context, and it ignores the context object entirely.

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 a specific verb and resource: "Return the company's live cap table," then enumerates the exact fields returned (holder, security type, shares, price paid, computed ownership %, total shares issued). This clearly distinguishes it from siblings like import_cap_table and leaves no ambiguity about 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 implies this is the tool to use when you need the current cap table, and it notes a prerequisite of authenticated active organization access. However, it does not explicitly state when to use this over alternatives, nor does it mention any exclusions. The phrase "plus every prerequisite stated above" is circular because no concrete prerequisites are actually listed above 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?

Even with annotations present, the description adds meaningful behavioral context: no external side effect, possible internal materialization of a canonical plan, no confirmation required, canonicality guidance, and idempotency/retry instructions. These go beyond the raw annotations and help an agent predict side effects. No contradiction with annotations detected.

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 verbose and repetitive. 'Prerequisite' appears twice with overlapping meaning, and the confirmation boundary, canonicality, and idempotency paragraphs read like generic boilerplate pasted in. It front-loads the use cases well, but many sentences do not earn their 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 covers return content, prerequisites, side-effect profile, and retry behavior, which is helpful given no output schema. However, it does not explain itemLimit/questionLimit semantics or what the returned context_engineering/actual_tool_output structure looks like, leaving the definition incomplete for a tool with four parameters and no output schema.

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

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

Schema description coverage is only 25%, so the description must do significant work to explain parameters. It mentions companyId's role for multi-company disambiguation, but itemLimit and questionLimit are left entirely unexplained. This is a notable gap for an agent deciding how to invoke the tool correctly.

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 tool's purpose: broad company briefing, disambiguation, and a founder asking what matters next. It enumerates the returned content areas and distinguishes itself from goal-specific tools, which helps an agent separate it from siblings like get_org, get_status, and resolve_company_plan.

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 explicit trigger conditions ('broad company briefing, company disambiguation, or a founder asking what matters next') and a negative guidance ('not a prerequisite for a goal-specific tool'). It also provides actionable instruction for multiple companies: pass companyId and never guess. It could still name concrete sibling alternatives, but the guidance is sufficient.

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 explicitly states idempotency ('safe to repeat'), read-only nature ('reads current server state'), and the absence of side effects ('no additional confirmation needed'). These details go beyond the readOnlyHint annotation, providing thorough behavioral disclosure.

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 a single dense paragraph with many clauses, but it is structured with periods separating key points (prerequisite, canonicality, etc.). It is not overly long, but some phrases are repetitive (e.g., 'every prerequisite stated above') and could be trimmed for clarity.

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 outlines what the response will contain (workflow, blockers, etc.) and covers behavioral guarantees. It lacks explicit mention of error scenarios or response format, but given the read-only nature and the presence of a companion list tool, the coverage is adequate.

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 provides descriptions only for _corply_context; caseId and companyId are left to self-explanatory names. The description adds minimal semantic value beyond the schema, leaving the purpose of the required IDs inferable but not explicitly explained.

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 that it retrieves a single company-scoped corporate-action case and lists the exact content (workflow, blockers, attorney gate, next step). This is specific and distinct from the sibling 'list_corporate_action_cases' which returns multiple cases.

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 for fetching a single case by ID, and the company-scoping hint clarifies the need for companyId. However, it does not explicitly contrast with list or other alternative tools, so the guidance is serviceable but not fully 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?

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it reads current server state, does not manufacture company facts, is safe to repeat, and requires no additional confirmation. These traits are not fully inferable from annotations alone.

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 first two sentences are crisp and front-loaded with purpose and tool selection. However, the trailing 'Prerequisite' and 'Confirmation boundary' sentences include boilerplate-like phrasing and an irrelevant list of confirmation categories, adding noise rather than earning their 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 read-only tool with no required parameters, the description provides enough context to select and invoke it correctly: purpose, prerequisite, alternative, idempotency, and confirmation posture. The main gap is that no output schema exists and the description does not detail the exact return shape, though 'organization and company identities' gives reasonable guidance.

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

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

Schema description coverage is 100%, and the single optional _corply_context parameter is already documented in the schema. The tool description adds no parameter-level meaning beyond what the schema provides, 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 states a specific verb and resource: a 'compatibility read returning the caller's organization and company identities.' It also differentiates itself from get_company_briefing, so an agent can distinguish the two 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?

It explicitly says to prefer get_company_briefing for company-specific work, giving a clear alternative and condition. It also states the prerequisite of authenticated active organization access, though the phrase 'plus every prerequisite stated above' is confusing since nothing precedes 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 destructiveHint=false, and the description adds substantial context beyond them: what it never returns (provider credentials, hosted payment tokens, bank/card data, customer data), that it makes zero provider calls and moves no money, that it is idempotent and safe to repeat, that it reads current server state without manufacturing facts, and that no confirmation is needed. This is rich behavioral disclosure that materially helps an agent predict side effects, and it aligns with — rather than contradicts — the annotations.

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

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

The description is front-loaded with the canonical purpose and organized into logical clauses (returns, exclusions, usage, prerequisite, canonicality, idempotency, confirmation boundary). However, it carries bloat: the confirmation-boundary sentence is a long templated enumeration ('reversible save, explicit fact/evidence record, link preparation, plan refresh...') that could be shortened, and the 'plus every prerequisite stated above' phrase dangles awkwardly. It is structured and mostly earns its length, but not every sentence is tight.

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 carries the burden of explaining return values — and it does, listing route info, lifecycle counts, totals, state, reconciliation state, and blockers. It also covers exclusions, side-effect safety, preconditions, idempotency, and confirmation requirements, which is strong for a read-only status tool of moderate complexity. Remaining gaps are minor: no error-condition disclosure and the vague 'prerequisites stated above' reference, so it falls just short of fully complete.

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

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

Schema description coverage is only 33% (only _corply_context is described in the schema), so the description must compensate. It does so only implicitly: 'for one company' clues companyId and 'recent payment state' hints at recentPaymentLimit, but it never explicitly explains what recentPaymentLimit — the sole required parameter — controls (e.g., number of recent payments returned) or the role of companyId in scoping. The description adds marginal meaning but does not fill the coverage gap for the most important parameter.

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 a specific verb and resource ('Canonical read for Corply's own payment pipeline') and enumerates exactly what it returns: merchant routes, lifecycle counts, gross settled/refunded/paid-out totals, recent payment state, reconciliation state, and blockers for one company. It also explicitly differentiates itself from the legacy Paddle integration planner, so an agent can distinguish it from siblings like reconcile_payment_route, await_payment, and verify_payment_integration without inspecting 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 gives an explicit selection condition ('Use this instead of the legacy Paddle integration planner when the founder wants Corply-controlled payment portals') and states a prerequisite ('authenticated active organization access'). It does not exhaustively enumerate when not to use it versus the other payment siblings, and the reference to 'every prerequisite stated above' is a dangling citation since no prerequisites are actually listed above — a minor gap in an otherwise actionable routing statement.

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 readOnlyHint/openWorldHint/destructiveHint annotations, the description discloses canonicality ('reads current server state and does not manufacture company facts'), idempotency ('safe to repeat'), and a confirmation boundary stating no additional confirmation is needed. 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?

The first sentence is dense and informative, but the description is padded with vague boilerplate such as 'plus every prerequisite stated above' and an overly broad 'Confirmation boundary' sentence listing unrelated categories. This adds confusion rather than value, and the labels (Canonicality, Idempotency, Confirmation boundary) make it feel systematic while containing filler.

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

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

For a read tool with no output schema, the description lists the return contents, notes the latest-formation fallback, and covers auth, canonicality, idempotency, and confirmation expectations. It is mostly complete, though exact parameter requirements and response structure are left implicit.

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 only 33% and the description does not explain companyId or formationId beyond the phrase 'or its latest formation' hinting formationId is optional. The _corply_context parameter is left entirely to the schema. The description does not compensate for the undocumented parameters.

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 action and resource: 'Return the formation status for a company (or its latest formation)' and enumerates the exact payload components (founder-facing checklist, payment block, pendingSignatures, awaitingOthers, postIncorp tasks, webDashboardUrl, nextStep). This makes it clearly distinguishable from broad siblings like get_company_briefing or get_payment_pipeline_status.

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 prerequisite ('authenticated active organization access') and a strong interpretive instruction ('trust nextStep over your own inference'), but does not name alternatives or state when not to use this tool versus sibling read tools. Usage context is implied by the formation-status scope rather than explicitly contrasted.

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 annotations already flag destructiveHint, and the description goes much further by disclosing that the tool is one-way, replaces the entire existing cap table, and is restricted to owners/founders. It also adds canonicality, idempotency, and confirmation-boundary guidance not present in the schema or annotations.

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

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

Front-loaded with purpose and the destructive consequence, then organized with labeled operational constraints. Some boilerplate, such as 'plus every prerequisite stated above,' is vague, but the description remains efficient, dense, and scannable.

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 import with no output schema, the description covers the critical workflow, permissions, confirmation boundary, and idempotency. Missing details like csv content/format and companyId semantics are a gap, but the core risks and the preview-then-confirm pattern are fully disclosed.

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 only 33%, so the description must compensate, but it only partially does. It explains confirm (preview vs replace) and implies source via 'Carta/Pulley CSV', but csv, companyId, and exact source behavior remain largely unexplained.

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 (Import), resource (cap table), source format (Carta/Pulley CSV), and the one-way consequence. It clearly differentiates this from read-style siblings like get_cap_table by positioning it as the write/replace path.

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?

Provides an explicit call sequence: call with confirm:false first to preview, then confirm to replace. It also restricts usage to owner/founder and requires fresh user confirmation. It does not explicitly name an alternative like get_cap_table, but the workflow is clear enough that an agent knows how to invoke it safely.

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: it discloses the prerequisite payment flow, the compatibility-action behavior, that sign links are only displayed on email failure, the idempotency/retry policy, and the confirmation boundary. These are meaningful behavioral details not inferable from annotations alone.

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

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

Front-loaded with the core action, but it becomes bloated with generic boilerplate about canonicality, idempotency, and confirmation boundaries. These add operational context but are not tool-specific enough to fully earn their length.

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 prerequisites, exclusions, retry behavior, confirmation requirements, and expected side effects. It does not describe the success/failure return shape beyond email failures, and with no output schema this is a notable gap, but overall the agent has enough context to invoke it safely.

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

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

Schema coverage is only 50%; formationId has no description in the schema and the description never explains what formationId should reference. The _corply_context property is documented in the schema, but the most important identifier parameter is left to inference.

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: it emails each other listed founder's pending review-and-sign link after documents are generated. It also explicitly distinguishes itself from invite_member, making its scope unambiguous.

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?

Provides explicit prerequisites (fee paid, docs generated, lead asks), explicit exclusions (never creates/refreshes membership invitations), and names the alternative tool (invite_member) with timing guidance. This is exemplary routing guidance.

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

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

Annotations already mark this as destructive and non-read-only, and the description adds meaningful behavioral context: the invitee joins via their own Corply session, the invitation is independent of other workflows, and the tool has canonicality/idempotency caveats. It does not contradict the annotations.

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

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

The description is front-loaded with the core purpose, and the labeled sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) are structured and readable. Some phrasing is generic, but no sentence is pure 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?

The description covers prerequisites, confirmation, side-effect independence, and operational guidance. However, with no output schema and several parameters left semantically unexplained, the agent still lacks enough context to be fully confident about return behavior and role/companyId usage.

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 only 25%, so the description has a responsibility to clarify parameters. It mentions the email mechanism but does not explain role semantics, the optional companyId, or how _corply_context should be populated 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?

The description states a clear action and resource: 'Invite a cofounder to this organization by email.' It is specific about the delivery mechanism, but it does not differentiate from the sibling tool invite_cofounders, and it mentions only cofounder while the role parameter supports founder, counsel, advisor, observer, and cofounder.

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 explicit use conditions: call only after explicit founder confirmation, require authenticated active organization access, and note that membership is independent of name checks, documents, payment, and signatures. It does not, however, explain when to choose this tool over invite_cofounders or redeem_invite.

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, the description adds valuable behavioral context: it never reads another company's cases, reads current server state, does not manufacture facts, is safe to repeat, and requires no additional confirmation. These details help an agent anticipate privacy and side-effect 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 first sentence is useful and front-loaded, but the rest is bloated with templated boilerplate. 'Canonicality', 'Idempotency', and 'Confirmation boundary' add redundant or generic content, and 'every prerequisite stated above' is an empty reference. The description would be stronger if trimmed to the first two sentences.

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

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

For a read-only list tool, the description conveys core purpose and safety, but with no output schema it leaves return shape, pagination behavior, and the meaning of 'attorney-gated next-step context' unexplained. An agent can call it, but may not fully know what a successful result will contain.

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 adds meaning for companyId ('one exact company') and status ('optionally filtered by status'), but it does not explain limit or _corply_context. The input schema provides decent coverage for those through defaults, constraints, and the _corply_context description, but the low schema description coverage means the tool description itself only partially compensates.

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 durable corporate-action cases for one exact company', and notes the optional status filter. This clearly distinguishes it from sibling tools like get_corporate_action_case and create_corporate_action_case.

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 prerequisite ('authenticated active organization access') and states the read-only scope, but it does not name alternatives or provide when-to-use versus when-not-to-use guidance. The 'every prerequisite stated above' phrase is vague and references nothing actually stated above.

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; the description goes further by disclosing that revocations are retained as audit tombstones, that the tool is canonical and should not trigger state-recovery calls, and that retries require checking idempotency first. This meaningfully characterizes the effects beyond the structured 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?

The first sentence front-loads the purpose and subsequent clauses are dense but purposeful. A small deduction for the dangling phrase 'every prerequisite stated above' and for boilerplate-like Canonicality/Idempotency sentences that could be sharper.

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, conditionally-required 9-parameter tool, the description covers authorization, prerequisites, audit behavior, retry safety, and confirmation boundaries, and points at actual_tool_output/context_engineering so the agent knows what to trust. No output schema exists, but the critical invocation context is present; action-specific parameter requirements are left to the schema.

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

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

Schema coverage is high (89%) and every parameter is documented in the schema, so the baseline applies; the description reinforces concepts like narrowest subject/class and the 90-day cap but adds little technical 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?

The description opens with a specific verb-resource pair: owner/operator-only grant or revocation of one person's expiring access to one restricted operating-data class. This clearly identifies the action domain and distinguishes it from the many fact/evidence recording siblings.

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

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

It gives concrete operating rules: use the narrowest subject and class, state a business purpose, cap access at 90 days, revoke when engagement ends, and get fresh user confirmation. It does not name sibling alternatives or explicit exclusion conditions, so it stops short of a perfect routing guide.

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 important behavior beyond the sparse annotations: Corply verifies the task, the status becomes 'pending review', and only founder-assigned tasks are accepted. It also advises trusting actual_tool_output instead of adding a state-recovery call. The idempotency and confirmation-boundary boilerplate adds some context, though it is generic rather than tool-specific.

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 opening sentences are front-loaded and clear, but the final three sentences about canonicality, idempotency, and confirmation boundary are generic boilerplate that likely applies to many tools. The phrase 'plus every prerequisite stated above' is vague because no such prerequisites were actually listed. The description is longer than it needs to be.

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 no output schema, it usefully explains the status transition, scope, prerequisites, and retry guidance. However, it omits stepKey semantics, what a successful or failed response looks like, and how to handle an already-reported or already-verified task. The vague prerequisite sentence weakens overall completeness.

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 only describes _corply_context; stepKey and note have no schema descriptions, and schema coverage is only 33%. The description clarifies that the note is optional and that the call reports a task as done, but it never explains that stepKey is the task identifier or where the caller should obtain it. With low schema coverage, the description does not compensate enough.

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 first sentence states a specific verb ('report as done'), a specific resource ('post-incorporation tasks'), and provides an example. It also scopes the tool to founder-assigned tasks, which helps distinguish it from sibling record/operating tools, though it does not explicitly name an alternative.

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

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

The description gives clear context: use it for your own post-incorporation tasks, and 'only works for tasks assigned to the founder' acts as an exclusion. It also states the authenticated active organization prerequisite. However, it does not explicitly compare against siblings like record_existing_completion or transition_operating_work_item, so it stops 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?

Annotations indicate mutation and destructiveness, and the description adds meaningful behavioral context: trust the returned actual_tool_output instead of adding a state-recovery call, follow retry/idempotency rules, and require fresh user confirmation before invoking. This goes well beyond the annotation flags and provides safety-relevant guidance.

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 core purpose is front-loaded in the first sentence, and the remaining guidance is clearly labeled with Prerequisite, Canonicality, Idempotency, and Confirmation boundary. The line 'plus every prerequisite stated above' is vague, but overall the description is compact and scannable.

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, no-output-schema tool, the description provides prerequisites, confirmation requirements, retry guidance, and output-trust behavior. It lacks explicit sibling comparison and a precise definition of formationId, but the essential operational context is present.

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 low at 33%, with only _corply_context documented. The description implies the email belongs to the cofounder being nudged, but it never explicitly maps formationId or explains its role in the operation, so it only partially compensates for the schema 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?

Description states a specific action ('Re-send the signature reminder email'), a specific target ('a cofounder who hasn't signed yet'), and a clear condition ('Only when the lead asks'). This clearly differentiates it from siblings like request_signature or invite_cofounders.

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 usage conditions: only when the lead asks, only with fresh explicit confirmation, and only with authenticated active organization access. It does not explicitly name alternative sibling tools or spell out negative cases beyond 'hasn't signed yet', so it stops slightly short of full routing 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?

Despite minimal annotations, the description richly discloses behavior: the link is short-lived, one-time, reversible, refreshable without confirmation, and Corply never stores the TIN as a database field. It also explains canonicality, idempotency, and confirmation-boundary expectations, giving an agent a strong sense of side effects and operational constraints beyond what annotations provide.

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 core purpose and safety constraints are front-loaded and clearly written. However, the last three sentences about canonicality, idempotency, and confirmation boundary are generic boilerplate that adds length without tool-specific detail. The structure is acceptable but not tight.

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 tool with no output schema and minimal annotations, the description covers a lot: lifecycle, TIN privacy, storage behavior, prerequisites, and a note to trust the returned actual_tool_output. Still, it fails to explain the required formationId parameter and the shape of the returned output, leaving an agent to infer important 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 coverage is only 33%, and the required formationId has no description in either the schema or the tool description. founderId and _corply_context are also not explained in the description. The phrase 'that founder' and 'their exact signed 83(b) election' hints at the parameters but never maps them to the actual input names, leaving a significant 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?

The description names a specific verb and resource: 'Create a short-lived, one-time external-browser link for the taxpayer to enter the SSN/ITIN.' This clearly identifies the tool's narrow purpose and distinguishes it from sibling tools like request_signature and generate_documents.

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 an explicit usage condition: 'Use only after that founder has signed,' and adds firm privacy constraints like 'Never ask for, accept, repeat, or place a TIN in chat.' It also states the prerequisite of authenticated active organization access. It does not explicitly contrast against sibling tools, but the task is unique enough that the context is clear.

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=true, openWorldHint=false, destructiveHint=false), the description adds important behavioral guarantees: 'Makes zero provider calls and no writes; never requests credentials, identity documents, bank/card data, or acceptance of terms.' It also discloses idempotency ('safe to repeat'), canonicality ('reads current server state and does not manufacture company facts'), and the confirmation boundary, all without contradicting the annotations.

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

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

The description is dense and front-loaded with the most important scoping information, and nearly every sentence carries operational value. It loses a point because it includes some boilerplate redundancy, such as 'plus every prerequisite stated above' and a generic confirmation boundary paragraph that could be trimmed without losing meaning.

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

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

For a tool with 10 parameters, a nested repository object, and no output schema, the description covers purpose, usage boundaries, prerequisites, behavior, and idempotency quite thoroughly. It is slightly incomplete on what the returned commercial facts look like structurally, though it does say the tool 'returns only the commercial facts that genuinely need founder input.'

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 very low at about 10%, so the description must compensate. It does add meaningful guidance for the repository object by requiring the agent to inspect 'framework, package manager, app/source root, and test/build commands' itself, and it explains companyId usage with 'pass an exact companyId from get_company_briefing.' However, some required commercial fields like businessModel, billingModel, customerType, and targetCountries are only implicitly covered by the overall classification purpose rather than explained directly.

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 leads with a precise scope: 'LEGACY PADDLE SUBSCRIPTION MIGRATION ONLY' and then states the tool's function: 'classifies whether the older fixed-price SaaS subscription Paddle merchant-of-record path fits, and returns only the commercial facts that genuinely need founder input.' It also names the sibling alternative, get_payment_pipeline_status, making the purpose and differentiation 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?

The description gives an explicit when-to-use and when-not-to-use rule: use for legacy Paddle subscription migration, but for a new Corply-controlled portal call get_payment_pipeline_status instead. It also instructs the agent to inspect repository metadata itself rather than asking the founder, requires an exact companyId from get_company_briefing when multiple companies exist, and warns not to bypass unsupported business models.

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 goes well beyond the annotations by explaining canonicality ('reads current server state and does not manufacture company facts'), idempotency ('safe to repeat'), and the confirmation boundary. These are meaningful behavioral traits that help an agent decide how to invoke the tool, and they fully align with the readOnlyHint=true annotation.

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

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

The main action is front-loaded in the first sentence, which is good. However, later sentences are boilerplate-heavy and confusing, such as 'Prerequisite: authenticated active organization access plus every prerequisite stated above' — there are no prerequisites stated above in this description. The confirmation boundary sentence is also verbose and could be streamlined.

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 and only 33% parameter schema coverage, the description should explain what the tool returns and how the parameters behave. It does not mention result format, pagination, or semantics of query/includeGlobal. The behavioral notes help but leave key operational details missing for an agent to use the tool confidently.

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 only 33% — query and includeGlobal are undocumented in the schema. The description does not explain what 'query' expects, what includeGlobal controls, or how the search results are shaped. Only _corply_context receives schema-level documentation, so the description fails to compensate for the low 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 and resource: 'Search the organization's context memory + Corply reference KB for relevant facts.' This clearly identifies recall as a retrieval tool. It doesn't explicitly compare against sibling tools, but the read/search semantics naturally distinguish it from write-oriented siblings like remember and record_operating_fact.

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?

Provides clear context: use when you need facts from the organization's context memory or Corply reference KB. The prerequisite and read-only framing further clarify the usage case. However, it does not mention exclusions or explicitly point to alternative tools, leaving some inference to the agent.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the concrete side effect: 'This action creates an auditable reconciliation record.' It also explains canonicality, idempotency expectations, and instructs the agent to trust the returned actual_tool_output and context_engineering instead of adding a state-recovery 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?

The description is front-loaded with the core purpose and call condition, then organized into labeled Canonicality, Idempotency, and Confirmation boundary sections. It is dense and mostly non-redundant, though phrases like 'plus every prerequisite stated above' add little and the wording is somewhat jargon-heavy.

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 covers prerequisites, provider evidence, side effects, idempotency, confirmation requirements, and the two schema branches—strong coverage for a tool with no output schema. It stops short of describing the returned payload or success/failure indicators, but it does tell the agent to trust the returned actual_tool_output.

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 document each field individually, but it maps the two schema branches to the two allowed provider-confirmation states: exact onboardingDataId/signup link versus no active application/retry safe. This gives meaningful semantics to the resolution consts and the handoffUrl/providerApplicationId pair that the bare schema properties do not convey.

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

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

The description opens with 'Owner/operator recovery for one uncertain Mercury onboarding attempt,' giving a specific verb, resource, and scope. This clearly separates it from status-read siblings like get_bank_onboarding_status and domain-different siblings like reconcile_payment_route, while also stating that the action 'creates an auditable reconciliation record.'

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 explicit call conditions: 'Call only after Mercury directly confirms either the exact onboardingDataId and mercury.com signup link, or that no active application remains and a corrected retry is safe.' It also gives a hard prerequisite, a confirmation boundary requiring fresh explicit user confirmation, and a warning never to invent provider evidence—leaving little ambiguity about when invocation is permitted.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false): discloses the provider-side read-only nature, that no sensitive data is exposed, that no money moves, that the run is hash-bound and recorded, and the subtle first-run anchoring rule with fail-closed variance behavior. The recording side effect is consistent with readOnlyHint=false; 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?

The core purpose is well front-loaded in the first sentence, but roughly half the description is generic boilerplate (Canonicality, Idempotency, Confirmation boundary) that appears to be appended across many tools, including the self-referential 'plus every prerequisite stated above' and the enumerated confirmation-boundary categories. It is informative but padded.

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 side effects, safety constraints, the anchoring rule, prerequisites, and retry guidance well. However, with no output schema, it never describes the shape of the returned reconciliation result, and it omits how to source the routeId (e.g., from route-draft or onboarding tools). Gaps remain for a tool that records state and can fail readiness.

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 only 33% (only _corply_context is described in-schema), so the description must compensate. It partially helps for routeId via 'route-scoped platform-cash postings', but companyId receives no explanation anywhere, and the description never addresses _corply_context or how to obtain a valid routeId. Compensation is incomplete.

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 multi-step operation: read the active Moov sandbox wallet balance, compare against Corply route-scoped postings, and record a hash-bound reconciliation run. It clearly distinguishes this from sibling tools like run_sandbox_payment_probe and reconcile_bank_onboarding by explicitly noting it makes provider reads only, moves no money, and exposes no account/credential data.

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?

Provides clear tool-specific context: the first run may only anchor a pre-existing balance before any payment/journal activity, later variance fails readiness closed, and authenticated active organization access is a prerequisite. The canonicality note adds an explicit exclusion ('trust the returned output... instead of adding a state-recovery call'), though it never names alternative sibling tools directly.

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 are sparse (all three hints false), so the description carries the burden, and it delivers: review routing ('routes the immutable claim to automatic, operator, or professional review'), the critical no-auto-completion behavior, idempotency retry guidance, canonicality advice ('trust the returned actual_tool_output ... instead of adding a state-recovery call'), and prerequisites. However, there is an internal tension: the claim is called 'immutable' yet the confirmation-boundary boilerplate classifies the action as a 'reversible save,' and 'plus every prerequisite stated above' is a vacuous reference to prerequisites that are never actually listed.

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 first two sentences front-load the essential semantics efficiently, but roughly half the description is templated boilerplate: the 'Canonicality,' 'Idempotency,' and 'Confirmation boundary' paragraphs read like generic footer text, with the confirmation boundary listing unrelated action categories ('read, reversible save, ... link preparation, plan refresh'). The prerequisite line is nearly tautological ('plus every prerequisite stated above'). The useful content is padded by filler that could be trimmed without losing 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?

For a complex 13-parameter, 11-required tool with nested objects and no output schema, the description covers intent, the most important behavioral caveat (evidence submission does not mark work complete), review routing, retry semantics, and trust guidance for the returned output. It is incomplete on the return payload (what the 'returned review' structurally contains), on constructing evidence/source objects, and on the role of _corply_context, which is only described in the schema. Strong for its complexity class, but not exhaustive.

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

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

With schema description coverage at only 8%, the description must compensate, and it partially does: it explains the composite key semantics ('pins rule/version/subject/occurrence'), the role of the idempotency key ('durable idempotency key'), and attestation ('explicit attestation'). But the complex nested parameters — source, evidence items, professional, provenance, claimedOutcome — receive no semantic gloss, and the relationship between claimedOutcome and the subsequent review flow is only hinted at. The description adds meaning for roughly a third of the parameters while the rest rely on self-documenting schema structure.

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 opening sentence states a specific verb, resource, and scope: 'Record evidence that the company completed one exact materialized work occurrence outside Corply.' It further pins down exactly what the command locks ('rule/version/subject/occurrence') and explicitly separates itself from completion-marking tools with 'This tool never marks the work completed merely because evidence was submitted.' An agent can distinguish it from siblings like transition_operating_work_item or record_operating_fact without opening their 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 gives explicit when-not guidance: 'use the normal fact and work-transition tools only after the returned review and remaining evidence/outcome gaps are resolved,' which maps directly to sibling tool categories. It also states the prerequisite condition (authenticated active organization access) and clarifies that this tool records evidence for work completed outside Corply, implying it is not for originating work. The routing-to-review behavior further tells the agent what to expect.

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 spartan annotations (all false), the description reveals atomicity, rejection of scalar writes, evidence-first-call behavior, idempotency handling, and confidence in the returned actual_tool_output over state-recovery calls. It also frames the operation as a reversible save within the confirmation-boundary note, giving the agent useful behavioral 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?

The description is long and padded with generic template lines such as 'authenticated active organization access plus every prerequisite stated above' when no prerequisites were actually stated, and the broad 'Confirmation boundary' enumeration. The core purpose is front-loaded, but several sentences are wordy or self-referential, so not 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 19-parameter tool with no output schema, the description covers the staging/promotion and evidence workflow, idempotency, and canonicality, which is substantial. Still, it omits the concrete return shape, when each confirmationKind is required, and the meaning of several validity/lifecycle parameters, leaving an agent to infer important call 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 coverage is only 53%, so the description must add semantic weight; it does clarify the retry contract ('identical source and validity inputs') and the meaning of evidence-gated candidates. But it leaves many parameters unexplained (provenance, trustLevel, effectiveFrom/To, itemLimit, questionLimit, _corply_context), so it only partially compensates for the schema 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?

The opening sentence names a specific operation, 'atomically stage or promote one event occurrence's stable ID and mutable anchor fact,' which is not merely a restatement of the tool name and clearly distinguishes it from scalar fact writes. The phrase 'scalar writes are rejected' further differentiates it from sibling record_operating_fact and evidence 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?

It explicitly instructs 'Use this for every fact named by an event rule,' establishing the primary invocation context, and describes the evidence-gated retry flow with identical source and validity inputs. However, it never names an alternative or states when not to use this tool, so it lacks explicit exclusions.

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, so the description carries the burden — and it delivers richly: canonicality behavior (trust actual_tool_output, don't add a state-recovery call), idempotency guidance (retry key or inspect refreshed state), the evidence-is-not-completion semantic, prerequisites, and an explicit confirmation boundary describing the operation as a reversible save. Nothing contradicts the annotations; 'reversible save' is consistent with destructiveHint=false.

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 long (~200 words) but every sentence earns its place: purpose, sibling routing, role constraints, prerequisites, canonicality, idempotency, and confirmation boundary. It is front-loaded with the core action before moving to constraints. The final confirmation-boundary sentence is a bit of a category dump and could be tightened, which keeps this from a 5.

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 14-parameter tool with nested objects, role-based restrictions, no output schema, and many siblings, the description covers selection, invocation workflow, prerequisites, retry semantics, and output handling. Since no output schema exists, the canonicality statement ('trust the returned actual_tool_output and context_engineering') partially compensates for not describing the return shape, though explicit output structure would make it fully complete.

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

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

Schema description coverage is 71% and most parameters (filePath, fileHash, factId, covers, workItemId, companyId, itemLimit, professional, _corply_context) already carry solid descriptions in the schema itself. The description adds workflow-level meaning beyond the schema by tying filePath/fileHash to the server-returned values from upload_operating_evidence and linking evidence ids to work-item transitions. It does not enumerate every parameter, but the schema does the heavy lifting, so the baseline 3 applies.

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

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

The opening sentence names a specific verb and resource — 'Record a company-owned evidence artifact' — and adds the secondary behavior of freshly resolving the plan. It explicitly differentiates from upload_operating_evidence and submit_operating_fact_evidence by naming them and explaining when each applies. The phrase 'freshly resolve the plan' is slightly ambiguous (re-resolve vs. update) but the overall purpose is clear and distinct from record_operating_event and record_operating_fact.

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 explicit routing: new files go through upload_operating_evidence first, founder-uploaded documents go through submit_operating_fact_evidence for operator review, and evidence ids attach when transitioning a work item. It also states exclusions ('A guidance link or model assertion is never professional evidence') and role constraints (only operators may directly promote an evidence-confirmed fact, professional determinations require named reviewer credentials). This is exemplary when-to-use guidance with named 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?

Beyond the sparse annotations, the description discloses canonicality rules, confirmation/evidence requirements, the danger of treating non-promoted candidates as true, backend action semantics, idempotency/retry behavior, and prerequisites. It also warns against inferring restricted facts. No contradiction with readOnlyHint=false or destructiveHint=false.

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 purpose and uses labeled sections for prerequisites, canonicality, idempotency, and confirmation. Some phrases are boilerplate or vague ('every prerequisite stated above', the long confirmation-boundary list), which slightly dilutes focus.

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 18 parameters, nested objects, no output schema, and basic annotations, the description covers the main behavioral contract and references returned actual_tool_output and context_engineering. It leaves some operational detail to the schema, but the core invocation semantics are adequately addressed.

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 56%, and the description adds policy-level context relevant to sourceType and confirmationKind (evidence, professional determination, non-promoted candidates). However, it adds little per-parameter meaning for time windows, confidence/trustLevel, evidenceEventIds, or _corply_context, so the burden is only partially compensated.

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 opening sentence clearly states a concrete action ('Record ... fact') and the resource scope ('company or subject fact'), plus the side effect of resolving the plan. It does not explicitly name sibling tools such as record_operating_event or record_operating_evidence, so the differentiator is implicit rather than stated.

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

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

The description provides clear context for when recording is appropriate, explicit exclusions for restricted facts without evidence, and a confirmation boundary ('no additional confirmation is needed'). It does not explicitly contrast alternatives like submit_operating_fact_evidence, so the when-to-use versus alternatives guidance is partial.

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 meaningful behavioral context beyond the annotations: joining switches the active organization and best-effort emails other members. It also covers the destructive nature implicitly by emphasizing fresh confirmation and idempotency checks. This aligns with destructiveHint=true and readOnlyHint=false, with no contradiction.

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 uses labeled sections for prerequisites, canonicality, idempotency, and confirmation. However, confirmation is stated twice ('Ask the user to confirm first' and 'Confirmation boundary'), and the phrase 'plus every prerequisite stated above' is vague and adds little. The boilerplate sections make it longer than necessary.

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, state-changing join operation with no output schema, the description covers the key contextual needs: user confirmation, active-organization switching, email side effects, prerequisites, and retry/idempotency guidance. It does not detail failure modes or the exact output shape, but it tells the agent to trust actual_tool_output and context_engineering, which mitigates that gap.

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

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

The schema coverage is only 50%; the required joinCode parameter has no schema description, but the tool description clarifies it as an 'invite join code' and shows it maps to a company via the confirmation message. The optional _corply_context is already well-described in the schema. Still, joinCode lacks format, length, or validation details, so the description only partially compensates.

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 a clear action and resource: 'Join an organization with an invite join code.' This distinguishes it from sibling tools like invite_cofounders and invite_member, which handle the opposite side of the invitation flow. The verb 'join' combined with 'invite join code' makes the tool's role unambiguous.

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 important invocation conditions, such as requiring user confirmation first and authenticated active organization access. However, it never explicitly explains when to choose this tool over alternatives or when not to use it. The usage context is implied by the purpose, but no exclusions or sibling comparisons are provided.

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 substantial behavioral detail beyond the annotations: it makes provider reads only, never changes the provider account, activates the sandbox route only when all required provider facts are ready, moves no money, and cannot enable production. It also addresses idempotency and canonicality, telling the agent to trust the returned output rather than adding a state-recovery call. These details significantly exceed what the sparse annotations provide.

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 core behavior is front-loaded in the first sentence, but the description then adds lengthy generic boilerplate about prerequisites, canonicality, idempotency, and confirmation boundaries. Several sentences are not tool-specific and read like templated policy text, making the description heavier than necessary without adding commensurate value.

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 covers the main safety and side-effect boundaries and mentions the returned actual_tool_output, but it lacks an output schema and does not describe the expected result shape or failure conditions. It also leaves companyId and routeId semantics unexplained. For a tool with moderate complexity and no output schema, this is adequate but not fully complete.

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

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

Schema description coverage is only 33%, and the description does not compensate by explaining the semantics of routeId or companyId. It says 'for one Corply route' and mentions a server-only route connection, but it never maps those concepts to specific parameters. The _corply_context parameter is documented in the schema, but the core identifiers are left underspecified.

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 verb/resource: it reads the hosted Moov sandbox onboarding invite, capability statuses, default wallet, and payout-bank method for one Corply route, then converges the server-only route connection. It also disambiguates itself by stating it never changes the provider account, moves no money, and cannot enable production, which separates it from related payment-route tools. This is specific enough for an agent to understand the tool's core function.

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 usage context: it requires authenticated active organization access and all stated prerequisites, and it explains when no extra confirmation is needed. It does not explicitly name sibling alternatives or say 'use X instead of Y,' but it does imply boundaries such as not accepting chat-supplied credentials and not enabling production, which helps an agent decide when to invoke 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?

The description calls the operation 'this read' while annotations declare readOnlyHint=false, and the opening clause says it persists a fact—so the read-only label directly contradicts the annotation and the tool's actual write behavior. The canonicality/idempotency sentences add generic policy guidance, but the contradiction makes the behavioral signal unreliable.

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?

After the clear first sentence, the description expands into boilerplate about prerequisites, canonicality, idempotency, and confirmation boundaries that is not tool-specific and repeats generic policy terms. The text is longer than needed for the actual content it conveys.

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 tool with no output schema and only two sparse annotations, the definition should explain what happens after persistence, how to interpret actual_tool_output/context_engineering, and how this relates to sibling memory/operating-fact tools. The generic operational rules do not fill that gap.

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

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

The schema documents _corply_context but leaves 'text' with no description, so the main sentence usefully implies that text is the fact/decision to persist. It does not add detail about expected text format, length, or how _corply_context should be populated beyond the schema's own description.

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 first sentence states a specific action ('Persist') and a clear resource ('the organization's context memory'), so an agent can tell this writes durable knowledge rather than retrieving it. However, it does not distinguish 'remember' from strongly overlapping siblings like record_operating_fact or submit_operating_fact_evidence.

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 prerequisites and generic retry/confirmation rules but never states when to choose remember over recall, record_operating_fact, or other sibling tools. There are no concrete use-case conditions or exclusions, so an agent must infer applicability from the name and first sentence.

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 annotations, it discloses that the call creates or reuses an active Stripe checkout session, that switching tiers retires the old link, that no confirmation is needed to create the link, that only the lead founder pays once, and that Stripe stores the payment method with renewal/cancellation details. No contradiction with readOnlyHint=false and destructiveHint=false.

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 content is extremely dense and relevant, but it is delivered as one long paragraph with generic closing boilerplate (Canonicality/Idempotency/Confirmation boundary) that could be trimmed or bulleted. It is front-loaded with the core purpose but not concise.

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 payment-link tool with no output schema, it covers prerequisites, consent/disclosure duties, pricing, idempotency/re-call behavior, founder eligibility, and explicit output handling. An agent has everything needed to invoke it correctly.

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

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

Although schema coverage is 75%, the description adds substantial meaning: exact dollar amounts for registeredAgent values, the $350 upgrade path, promo-code restriction to year_one, renewal pricing for corplyMail, and the default-to-none consent rule. It also names the returned checkoutUrl, helping the agent interpret the output.

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 a specific verb and resource: 'prepare (or reuse) the checkout link' for the one-time incorporation fee, and positions it as mandatory before signing. It explicitly names a sibling (request_registered_agent_upgrade) so the agent can distinguish upgrade from initial 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 clearly states when the tool is required ('MANDATORY before any signing'), how to choose between tier options, and that the upgrade path is a separate sibling tool. It does not explicitly contrast request_payment with the many other payment-related siblings, but the mandatory-before-signing context is strong enough for correct 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?

Beyond the annotations, the description discloses return statuses, the checkout flow, the already_lifetime condition, idempotency behavior, and the fact that it reuses an open session. This is substantial behavioral context that helps an agent understand side effects and expectations.

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 essential information is front-loaded and clear, including price, timing, and return handling. However, the trailing canonicality, idempotency, and confirmation-boundary sentences read as generic boilerplate rather than tool-specific guidance, making the description longer and less focused than necessary.

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?

Despite lacking an output schema, the description fully explains both possible return shapes, the next step to poll, the prerequisite that incorporation fee must be paid, and the policy on confirmation. It provides enough context for an agent to call the tool and handle the result 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 schema documents _corply_context but not formationId, and the description never explicitly explains what formationId should be or how to obtain it. However, the tool name, the term 'formation fee,' and the parameter name make it reasonably inferable in context, so it is minimally viable but not strongly supported.

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: upgrading a company's registered agent from first-year to lifetime, including price and tier context. It clearly differentiates this from the related polling tool await_registered_agent_upgrade and from other company-related 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?

It explicitly says when to use the tool (after incorporation fee is paid, when founder has Essential tier) and what to do based on the response, including polling await_registered_agent_upgrade and not recharging if already_lifetime. It also states prerequisites and safe re-call behavior, leaving little 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?

Far exceeds the minimal annotations (readOnlyHint=false, destructiveHint=false). It discloses phase-dependent behavior, idempotency, that no cofounder email is sent, automatic 83(b) preparation, no confirmation needed, and the canonicality instruction to trust returned output rather than issue a state-recovery call. 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 a verbose wall of text with several layers of conditional behavior and ends in boilerplate-style Canonicality/Idempotency/Confirmation-boundary paragraphs. Nearly every sentence carries information, but the prose is convoluted and poorly structured; the same content could be delivered in half the length.

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?

Exceptionally complete for a complex, phase-aware action with no output schema: it covers prerequisites, before/after-acceptance behavior, what is returned (signing bundle + reviewUrl presented as markdown), when NOT to call, retry rules, and confirmation boundaries. Nothing an agent needs 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 50% — formationId is undocumented. The description never defines formationId explicitly, but its surrounding context (incorporation fee, Delaware acceptance, founder bundles) makes the parameter's referent clear. The _corply_context param is covered by the schema, and the description's canonicality/context_engineering mention reinforces it. Modest added value, borderline compensation.

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 conveys a specific action — preparing a phase-aware signature bundle and returning it to the caller — and explicitly separates itself from external-messaging siblings by naming invite_cofounders and nudge_signer. However, the core purpose is never crisply stated ('requests a signature') and must be extracted from dense procedural prose, so some inference is required.

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?

Excellent routing guidance: it states the hard precondition (incorporation fee paid, request_payment → await_payment), a firm exclusion ('must never become a second human signature request' after acceptance), and directs external messages to invite_cofounders or nudge_signer. Prerequisites, idempotent-retry behavior, and the confirmation boundary are all 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?

The description goes well beyond the sparse annotations by disclosing determinism, the always-running lifecycle, the prohibition on inferring protected facts, idempotency/retry behavior, and confirmation boundaries. This is rich behavioral context that an agent needs and that annotations alone do not provide.

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 core purpose is front-loaded, but the description is long and includes a confusing phrase: 'plus every prerequisite stated above' when no explicit prerequisite list appears above it. The content is largely useful, but it would benefit from tighter structure such as bullets.

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?

There is no output schema, and the description does not clearly specify the response shape beyond 'returned questions' and 'actual_tool_output and context_engineering.' It covers many behavioral constraints well, but the concrete output contract and side-effect profile remain somewhat underspecified.

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 parameters. The description does not add meaningful parameter-level detail beyond what is in the input schema, so the baseline score 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 names a specific action ('resolve and materialize') and a specific resource ('the company's current operating graph'), so an agent can tell this is not a simple status or payment tool. However, it does not explicitly differentiate itself from sibling tools such as get_company_briefing or get_status, so it stops short of a 5.

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

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

The description provides contextual constraints such as 'never report globally done' and 'trust the returned actual_tool_output instead of adding a state-recovery call,' which gives some usage guidance. But it never states when to choose this tool over sibling alternatives, so the usage conditions remain mostly implied.

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

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

The description goes well beyond the minimal annotations by explaining test-mode-only behavior, the durable create-and-authorize pipeline, inability to prove settlement, canonicality expectations, idempotency retry guidance, and the fact that no additional confirmation is needed after pre-authorization. This is substantial behavioral context beyond readOnlyHint/destructiveHint/openWorldHint.

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 opening is front-loaded with the action and prerequisites, but the description contains a large amount of generic boilerplate, especially the confirmation-boundary sentence listing unrelated categories like 'read, reversible save, explicit fact/evidence record, link preparation, plan refresh.' Several statements repeat the same point about prerequisites and confirmation, so not 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 complex, state-changing tool with no output schema, the description is quite complete: it covers prerequisites, behavior, limitations, canonicality, idempotency, and confirmation policy. The main gaps are lack of explicit companyId semantics, no mention of what the actual_tool_output contains, and no direct differentiation from the payout probe sibling.

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 only 20%, so the description carries most of the burden for parameter meaning. It usefully explains routeId as an active route, idempotencyKey as an exact key, and confirmation as the founder-confirmed sandbox charge, but companyId is left unexplained and _corply_context relies on the schema description. Core required parameters are reasonably covered, but optional parameter semantics are incomplete.

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 action: create or replay a server-priced diagnostic order and send the card-payment source through the durable create-and-authorize pipeline in Moov sandbox. It also disambiguates from production payment tools by emphasizing test-mode-only money movement. However, it does not explicitly contrast with the sibling run_sandbox_payout_probe, so some sibling differentiation is left to inference.

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 strong when-to-use guidance: after fresh founder confirmation of the exact USD 1.00 charge, with an active route, fresh zero-variance reconciliation, server-held probe configuration, and an exact idempotency key. It also states a clear boundary: it cannot charge live money, enable production, or prove settlement. It does not explicitly name alternatives such as run_sandbox_payout_probe or when not to use this tool in favor of another.

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, openWorldHint=true, destructiveHint=false. The description adds rich behavioral context: test-mode only, the scheduled worker records the after-the-fact payout fee, canonicality guidance to trust returned output, idempotency handling, and a confirmation-boundary policy. This goes well beyond the structured 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?

The description is long but well-fragmented with labels like Prerequisite, Canonicality, Idempotency, and Confirmation boundary. The core action is front-loaded. Some boilerplate phrases are generic, but they earn their place for an agent needing operational guidance on retries and confirmations.

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?

There is no output schema, so the description should clarify return behavior; it only says to trust actual_tool_output. It covers side effects, prerequisites, and limitations thoroughly, but omits the purpose of the optional companyId parameter and gives no detail about the returned output structure. For a complex money-movement tool, these gaps matter.

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 only 20%, so the description must compensate. It clarifies that no amount, currency, provider ID, wallet, bank/card data, or destination are accepted and that paymentKey and an active route are required. However, it does not explain companyId, the confirmation constant, or _corply_context, leaving significant parameter meaning unresolved.

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 action: send one cent from a settled diagnostic payment via Corply's durable payout command to a server-resolved verified ACH bank. It names the exact resource, amount, mode, and route, and distinguishes the payout purpose from sibling tools like run_sandbox_payment_probe.

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 clear usage context: only after fresh founder confirmation, only in Moov sandbox, and only with an exact paymentKey, active route, zero-variance reconciliation, and verified bank. It explicitly excludes live-money usage, though it does not name the alternative tool to use when these conditions are not met.

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?

Discloses that saves are reversible, that 83(b) defaults apply and must not be re-asked, that frozen packets are refused, and that the return value includes standardConfiguration/nextStep. Annotations only mark readOnly/destructive false, leaving the description to carry safety and failure behavior; it does so thoroughly.

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?

Core operation, merge semantics, 83(b) handling, refusal case, and return shape come first in dense, efficient prose. The later canonicality/idempotency/confirmation paragraphs are somewhat boilerplate, but still relevant and not padded.

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?

This is a complex tool with 3 parameters and deeply nested data, no output schema, and important failure/confirmation behavior. The description covers return value, error/refusal case, confirmation boundary, idempotency, prerequisites, and canonical backend behavior. Nothing material is missing for an agent to decide and invoke 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 schema already documents companyId, _corply_context, and many nested fields. The description adds meaningful intent beyond the schema: partial payloads merge, 83(b) fields should be omitted, and the returned configuration should be used over generic capitalization advice. With 67% schema coverage, this is solid but not exhaustive per-parameter enrichment.

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 operation ('Deep-merge upsert') and the exact resource ('structured formation application for a company'), with incremental-save semantics that separate it from one-shot submission. It explicitly names amend_frozen_application as the alternative for frozen packets, so an agent can distinguish it from siblings.

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

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

Provides explicit when-to-use behavior (incremental partial saves merge safely, no confirmation needed) and a when-not-to condition: frozen legal packets must go through amend_frozen_application after founder confirmation. Also gives a prerequisite (authenticated active organization access).

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?

Although annotations already mark the tool as destructive and non-read-only, the description adds substantial behavioral context: the consent must be fresh and affirmative, the opaque bundleId prevents stale documents, prior consent cannot be reused, an 83(b) election may be executed automatically, and the returned TIN link must be opened without asking for the TIN in chat. It also covers canonicality, idempotency, and confirmation boundaries.

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 long and dense, but each labeled section serves a purpose for a legally sensitive, destructive action. It is front-loaded with the core purpose and caller gate, followed by safety and operational instructions. Minor redundancy exists between 'fresh affirmative act' and the final 'fresh, explicit user confirmation' boundary, but the overall structure aids an agent's parsing.

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 tool's complexity, legal sensitivity, 5 parameters, and absence of an output schema, the description is unusually complete. It covers purpose, caller eligibility, prerequisites, return behavior, automatic 83(b) handling, TIN-link handling, canonicality, idempotency, and the confirmation boundary. An agent has the operational context needed to invoke this tool correctly and safely.

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

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

Schema description coverage is low at 20%, so the description must compensate. It does add meaning for bundleId ('exact server-issued bundle returned by get_status or request_signature'), esignConsent ('one fresh affirmative act'), and signedLegalName ('only the live signer may call it'). However, formationId is never explained, leaving a meaningful gap for an otherwise verbose description.

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 a specific verb and resource: 'Record one binding ESIGN/UETA consent' for 'the exact server-issued bundle returned by get_status or request_signature.' This clearly identifies the action, object, and provenance, and differentiates it from sibling tools like request_signature and prepare_83b_tin_input.

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 explicit caller gates: only the live signer may call it, after reviewing every listed document and providing one fresh affirmative act. It also states when not to use it, such as never reusing prior-session consent or signing for an absent cofounder, and describes an automatic 83(b) exception. This is strong when/when-not guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description correctly treats it as a mutating/state-creating operation. The description adds critical context beyond annotations: it must not request prohibited data (SSN, identity image, raw formation document, Mercury credentials, legal name/EIN override), it should never create a new idempotency key after a timeout, it invokes a canonical shared backend action and should trust the returned actual_tool_output, and it requires explicit user confirmation before calling. This gives the agent clear behavioral boundaries that annotations alone would not 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?

The description is relatively dense and front-loaded with the core action, and it covers a lot of safety-critical guidance in a compact space. However, it is long and somewhat repetitive with appended boilerplate-style sections ('Canonicality', 'Idempotency', 'Confirmation boundary') that could be tightened or integrated more cleanly. It earns its place but is close to the edge of over-specification.

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 complexity of an 11-parameter tool with nested objects and no output schema, the description covers the most decision-critical behaviors: preflight status check, confirmation requirement, what not to send, idempotency handling, and trusting the actual output. It does not describe the returned signup link structure or what happens after a rejected application, but it provides enough for an agent to invoke the tool correctly in most scenarios. A small gap is that the many nested parameter groups are not explained at all, so the agent must infer acceptable values from the schema alone.

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 only 9%, and the description does not enumerate the 11 parameters or explain the nested objects (about, formationDetails, businessLegalAddress, etc.). However, the description names the key required parameters (inviteEmail, beneficialOwners, founderAuthorizedDataSharing, idempotencyKey) and gives substantial semantic guidance on idempotencyKey reuse, and clarifies that founderAuthorizedDataSharing must reflect fresh founder confirmation. This partially compensates for the schema gaps, but the large nested objects remain undocumented in the description, so it does not fully 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?

The opening sentence states a specific verb ('Create'), the resource ('one consented Mercury partner prefill'), and the return artifact ('founder-only signup link'). This clearly distinguishes it from siblings like get_bank_onboarding_status (status check) and start_payment_route_onboarding (different onboarding domain), and the description explicitly names get_bank_onboarding_status as a prerequisite rather than confusing it with this action.

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 explicitly instructs to call get_bank_onboarding_status first, requires fresh founder confirmation before calling, specifies the prerequisite of authenticated active organization access, and states that data is loaded server-side (so the agent should not request company facts from the user). It names the alternative workflow implicitly by telling the agent when to use status checks as a precursor, and clearly states the flow ownership and not to invent idempotency keys.

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 are minimal (readOnlyHint false, openWorldHint true, destructiveHint false). The description adds substantial behavioral detail beyond them: it makes an idempotent provider call after a durable local claim, never receives identity documents or bank/card data, activates no route, moves no money, and requires no additional confirmation. This is rich, non-contradictory transparency.

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 opening sentence is strong and labeled sections aid navigation. However, the latter paragraphs contain generic policy boilerplate such as canonicality and confirmation-boundary phrasing that is only loosely tool-specific. It is informative but not tightly edited.

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 covers purpose, side effects, prerequisites, and follow-up tooling. But it does not specify the response shape beyond 'return the onboardingLink', and it omits the optional companyId and _corply_context parameters. Given the absence of an output schema and low parameter coverage, meaningful gaps remain.

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 only 25% (just _corply_context). The description loosely maps to routeId as 'one existing Corply payment route' and idempotencyKey as an idempotent call with a retry key, but it never names companyId or _corply_context or explains how to populate them. With such low coverage, the description needed to compensate far more.

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 is explicit and specific: 'Create or recover the secure hosted Moov sandbox onboarding link for one existing Corply payment route.' It names the verb, the resource, and scope, and differentiates from pipeline-status and refresh siblings by stating what it does not do: it activates no route, moves no money, and never receives sensitive data.

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 clear contextual guidance: prerequisites are stated, the returned onboardingLink should be given to the founder, and get_payment_pipeline_status should be called after completion. It also tells the agent not to add a state-recovery call. However, it does not explicitly contrast this tool with the sibling refresh_payment_route_onboarding, so it stops 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?

Beyond the destructiveHint/openWorldHint annotations, it discloses real-world side effects: submission to a human filing pipeline, best-effort notification to the organization, and emailing signed docs to founders. It also gives idempotency and retry guidance ('inspect refreshed state before retrying') and warns against state-recovery calls, which is valuable behavioral context for a mutating 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 dense but well-labeled; the critical prerequisite and side-effect information comes first. The Canonicality/Idempotency/Confirmation-boundary sections add some boilerplate-style jargon, but each conveys operational guidance that earns its place for a destructive tool.

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 tool with no output schema, it covers prerequisites, side effects, jurisdictional exclusion, confirmation requirements, and retry behavior. It is less complete on return-value semantics and parameter mapping, but those are partially covered by the context_engineering note and are not fatal to correct 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?

The description never names or explains formationId or _corply_context. Schema coverage is only 50% — _corply_context has a brief echo description, but formationId has none — and the prose does not compensate by explicitly mapping 'fully-signed formation' to the required parameter. The agent must infer that formationId identifies the signed formation.

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 concrete action — handing a fully-signed formation to the human filing pipeline — and specifies the follow-on side effects of notifying the organization and emailing founders. It also explicitly scopes the tool by saying 'Does NOT file with Delaware,' which distinguishes it from submission-type 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?

It clearly states when this tool is appropriate: the incorporation fee must be paid first via request_payment → await_payment, and the formation must be fully signed. The confirmation boundary ('obtain fresh, explicit user confirmation before calling') is strong usage guidance. It stops short of naming a specific alternative for non-Delaware or unsigned cases, but the exclusions are mostly implied.

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

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

It goes well beyond the three boolean annotations by disclosing that submission stages rather than canonicalizes, that resolvers keep asking until operator approval, and that retries should follow idempotency rules or state inspection. The 'read, reversible save' phrase is imprecise, but it does not contradict the annotations.

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

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

The opening two sentences are focused, but the tail includes generic boilerplate on Canonicality, Idempotency, and Confirmation boundary that is mostly not tool-specific and the 'every prerequisite stated above' line adds no information. It reads as a templated block rather than tight, purpose-built guidance.

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

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

For a complex 11-parameter tool with no output schema and sparse parameter descriptions, this is insufficient. It tells the agent what the operation means but not how to populate the majority of parameters or interpret the result.

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

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

With only 9% schema description coverage and 11 parameters, the description must compensate, but it only explains filePath/fileHash. It does not clarify factKey, value, sourceReference, sourceObservedAt, title, idempotencyKey, companyId, subjectId, or _corply_context.

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 verb and resource ('submit ... document for an evidence-confirmed operating fact') and states the outcome: a staged typed assertion, bound immutable artifact, and operator-review claim. It does not explicitly contrast with siblings like record_operating_fact or record_operating_evidence, so it stops short of full differentiation.

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 clearly states one important precondition ('filePath/fileHash must come from upload_operating_evidence') and explains that the fact is not canonical until approved. However, it never says when to choose this over similar sibling tools or 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 only say destructiveHint=true/readOnlyHint=false, and the description adds substantial operational behavior: completion is gated on evidence coverage and non-waivable requirement classes, the canonicality note instructs the agent to trust actual_tool_output and avoid an extra state-recovery call, and the idempotency/confirmation guidance shapes invocation behavior. This is exactly the kind of context beyond annotations that agents need for a destructive 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?

The description is long (~130 words) but densely informative, with labeled segments (Prerequisite:, Canonicality:, Idempotency:, Confirmation boundary:) that make it scannable for an agent. Core purpose is front-loaded in the first sentence and each labeled block carries distinct guidance. Minor circularity in 'plus every prerequisite stated above' and overall length prevent a 5.

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 10-parameter tool with no output schema, the description covers purpose, side effects, gating constraints, non-waivable requirement classes, prerequisites, retry semantics, canonicality, and the confirmation boundary. The main gap is that it acknowledges the return values ('actual_tool_output and context_engineering') without describing their structure, and the output shape is only inferable from the itemLimit/questionLimit schema descriptions.

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

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

With schema coverage at 50%, the description partially compensates: it ties workItemId to the target occurrence, 'attached company evidence' maps to evidenceEventIds, the retry-key remark maps to idempotencyKey, and context_engineering maps to _corply_context. But it adds nothing about toStatus semantics, reason, companyId disambiguation, or the limit parameters, leaving those to the schema alone. The partial compensation warrants a middle score.

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 first sentence names a specific verb ('transition'), a specific resource ('materialized work occurrence' identified by workItemId), and a distinctive side effect ('then freshly resolve the company plan'), which separates it from siblings like record_operating_event or mark_task_done. The term 'materialized work occurrence' is jargon that slightly obscures what the resource actually is, 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?

Provides explicit contextual constraints: a stated prerequisite (authenticated active organization access plus completion preconditions), a confirmation boundary ('obtain fresh, explicit user confirmation before calling'), and retry guidance tied to idempotency. However, it never names alternatives or states when NOT to use this tool versus siblings such as record_operating_evidence or resolve_company_plan, so the guidance is context-rich but lacks exclusions.

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 are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the burden. It adds useful behavioral context: the tool returns a server-computed SHA-256, stores bytes in a canonical private prefix, and is described as a 'reversible save' requiring no additional confirmation. It also gives operational advice to 'trust the returned actual_tool_output and context_engineering instead of adding a state-recovery call.' These details go beyond the annotations and help the agent predict side effects, though generic boilerplate weakens precision.

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 first two sentences are tight and front-loaded with purpose and usage. However, the trailing sections (Prerequisite, Canonicality, Idempotency, Confirmation boundary) contain generic, boilerplate language that is not tool-specific and consumes many words. Phrases like 'plus every prerequisite stated above' and 'this read, reversible save, explicit fact/evidence record, link preparation, plan refresh...' are vague and dilute the clarity. The structure is organized but not maximally efficient.

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 5 parameters and no output schema, the description covers the critical flow: upload exact bytes, receive SHA-256, then feed into record_operating_evidence. It mentions the active-company scope, a large-file alternative, and prerequisites. It does not explain fileName/contentType semantics, error handling, or _corply_context details, but for the intended use case the description is sufficiently complete to allow correct invocation and downstream action.

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 60%, with descriptions only for companyId and dataBase64. The description reinforces dataBase64 semantics ('actual base64 file bytes', 'never invent bytes from a description') and mentions the active-company scope, which clarifies companyId. However, it adds nothing about fileName, contentType, or _corply_context, so the remaining 40% of parameters remain under-documented. The description adds some value but does not fully compensate for the 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?

The description states a specific action ('Store exact caller-supplied evidence bytes'), a specific resource ('the active company's private canonical evidence prefix'), and a concrete outcome ('return the server-computed SHA-256 needed by record_operating_evidence'). It clearly differentiates from sibling tools by naming the dependent tool and the return value, leaving no ambiguity about what this 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?

Explicit when-to-use guidance is present: 'Use only when the client has supplied the actual base64 file bytes; never invent bytes from a description.' It also identifies an alternative path for large files: 'Browser/desktop clients should use POST /operating/evidence/upload for files larger than the MCP limit.' This gives the agent a clear decision boundary and names a distinct alternative.

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, the description discloses important behavioral traits: this invokes a shared backend action, should not be followed by a state-recovery call, has idempotency obligations, and does not require additional confirmation. These details meaningfully help an agent predict side effects and post-call behavior, beyond what readOnlyHint/destructiveHint provide.

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 core action is front-loaded and the description is organized into scannable labeled sections like Prerequisite, Canonicality, Idempotency, and Confirmation boundary. Some phrases are boilerplate or vague ('plus every prerequisite stated above'), adding minor noise, but the overall structure remains efficient.

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 mutation with no output schema, the description covers the key operational context: subject identity, where to record facts, prerequisite auth, output trust, idempotency, and confirmation. It leaves detailed parameter semantics to the schema and does not fully explain plan-resolution mechanics, but it is sufficiently complete for correct 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?

Input schema coverage is 70%, and the schema already documents companyId, externalKey, linkedUserId, attributes, itemLimit, and questionLimit. The description adds useful guidance about stable externalKey and that attributes must not hold decision facts, but it does not compensate for the remaining undocumented parameters. This is adequate but not exceptional.

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 a specific verb-resource pair: 'Create or update one durable company-owned subject', and enumerates ten subject types, making the tool's scope immediately clear. It also differentiates itself from record_operating_fact by explicitly routing decision facts to that sibling, so an agent can distinguish it from nearby 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?

It gives explicit routing guidance: 'Use a stable externalKey' and 'store decision facts through record_operating_fact, not opaque attributes.' It also provides prerequisites and idempotency/confirmation guidance. However, it does not explicitly state when not to use this tool in favor of other operating tools, leaving some inference to the agent.

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

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

Annotations already indicate it's not read-only, and the description additionally discloses it involves a 'reversible save' and promotes state to 'ready', plus canonicality and retry guidance. This adds value beyond annotations, but the disclosure is partially templated and doesn't fully describe side effects 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?

The first sentence is concise, but it's followed by three sentences of generic boilerplate about canonicality, idempotency, and confirmation boundaries that appear unrelated to this specific tool. These add noise and dilute the useful 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 tool with only one required parameter and no output schema, the description covers the key outcomes: validationIssues distinguishing absent vs invalid, promotion to 'ready', and return of canonical nextStep. The retry and canonicality guidance, while generic, still aids correct invocation.

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