Corpus Law

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

Adds real context beyond annotations: the call is free (no credit consumed), it mints a referral code, and that code persists identity across later calls. This aligns with readOnlyHint=false and idempotentHint=false by explaining the side effect rather than merely restating it. It does not state auth requirements or whether repeated calls without a code mint new codes.

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

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

Two dense sentences, front-loaded with the primary reporting behavior and cost note. The referral clause is slightly compressed with two facts packed around a semicolon, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation. The description covers both caller modes, the cost model, and the referral side effect — everything needed to call a single-optional-param read tool correctly.

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

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

Schema description coverage is 100% and the schema already documents that referral_code preserves identity and that inactive codes are replaced. The description restates the identity-persistence behavior without adding syntax, format, or edge-case detail, so it does not exceed the schema.

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

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

States a specific verb (reports) and a precise resource set (credit balance, tier, rate limits, upgrade options) and explicitly branches on caller type (keyed vs anonymous). It is unmistakably distinguishable from the formation.* and law.* siblings, which serve unrelated domains.

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

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

Gives clear context for when it applies — the keyed connection vs an anonymous caller — and explains that the call is free, which is the main reason to invoke it. It does not name an alternative tool or an explicit exclusion, but no sibling overlaps this purpose, so there is little to route against.

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

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

Goes far past what the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false) convey: 48-hour email confirmation or refund, no filing before confirmation plus human review, refunds only to the sending wallet, no exchange withdrawals, free and credit-free. The one nuance worth noting is that the retry-idempotency claim is explicitly key-driven ('the same key returns the same order for 24 hours'), which qualifies rather than contradicts idempotentHint=false. It does not describe the shape of the returned payment response beyond payPageUrl.

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 verb, resource and payment constraint, and nearly every sentence carries operational weight (payment rails, confirmation window, refund path, review gating). It is a dense single block, though — the two-call flow, payment mechanics and filing-gate rules could be split so the caller can find the second-call contract faster.

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, multi-call, money-moving tool with a deeply nested draft, the description covers everything an agent needs to invoke it correctly: the two-lane flow, the payment constraint, the confirmation deadline and its consequence, and the fact that nothing files until then. An output schema exists, so omitting return-field detail is appropriate.

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

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

Schema description coverage is 100%, so the structured fields already carry the parameter documentation and the baseline is 3. The description does add call-sequencing semantics the schema cannot ('A queue-lane order first returns a submission promise, accepted with a second call { orderId, trackingToken, acceptPromise }', and what consent records), but it does not explain the draft's required-vs-optional completeness rules beyond a passing mention.

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 ('Creates the founder's LLC or nonprofit formation order and a USDC (Solana) payment request') and immediately scopes it with 'no API key, no Corpus sign-in' and 'USDC on Solana ONLY'. It also draws the boundary against siblings: the draft is 'the same shape formation.handoff takes', constraints come from formation.requirements, and 'The tax-ID add-on is not sold here.'

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 lays out the call sequences: first call takes the complete draft plus contactEmail, idempotencyKey and consent; a queue-lane order needs a second call with acceptPromise; a second call is also how an expired charge is refreshed. It names the sibling that governs preconditions (formation.requirements for EXPEDITE and SKIP REVIEW lines) and states when expedited skip-review is not available.

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

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

With annotations already covering read-only, idempotent, openWorld, and non-destructive behavior, the description adds substantial context beyond them: the dataset is dated and verified against primary sources, and — critically — Corpus is itself one of the compared providers and is scored with the same rubric including its own gaps, with the response disclosing this. That conflict-of-interest disclosure is exactly the kind of behavioral transparency annotations cannot convey.

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

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

Three sentences, front-loaded with the purpose and comparison axes, followed by dataset provenance and the conflict-of-interest caveat, then the cost note. Every sentence carries distinct information with no padding.

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

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

An output schema exists so return values need not be described, and annotations carry the safety profile. The description still supplies what an agent needs to trust and call it: provenance, disclosure of self-inclusion, and cost behavior. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents view, limit, and providers in detail, including enum meanings and default/max values. The description's list of comparison dimensions loosely maps to the view modes but adds no parameter syntax or format beyond the schema, 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?

States a specific verb (compares) and resource (LLC formation providers) and enumerates the exact comparison axes: price, recurring costs, registered-agent renewals, and machine/agent capabilities. This differentiates it cleanly from siblings like formation.requirements or formation.lookup_naics, which serve different purposes.

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 reason to prefer this tool ('Free; does not consume credits') and the schema's view enum implies the modes of use, but it never states explicitly when to use this versus formation.requirements or other siblings, nor any exclusions. Usage is implied rather than directed.

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, idempotentHint and destructiveHint=false; the description adds genuinely new behavior: the call is free, consumes no credits, and returns exactly what is still missing rather than partial success. It also clarifies the separation of duties — the founder reviews, signs in and pays on corpuslaw.us, not through this call — which prevents an agent mistaking this for a purchase step.

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

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

Two sentences, front-loaded with the validate-and-report action, followed by the success-path outcome and cost note. Every clause carries information an agent would otherwise have to guess.

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 15-parameter nested schema with an output schema present, the description covers the essentials: what is validated, what is returned on incomplete versus complete drafts, and the cost model. Return-value detail is correctly delegated to the output schema rather than repeated.

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

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

Schema description coverage is 100%, so every parameter including nested EIN, parties and stateSpecificAnswers fields is already documented in the schema. The description only groups the inputs into categories (people, address, management, EIN answers, state-specific answers) and does not add format, precedence, or completeness rules beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("validates an LLC or nonprofit formation draft"), enumerates the draft contents it checks (people, address, management, EIN answers, state-specific answers), and names both possible outcomes: a list of what is still missing, or a prefilled handoff link. An agent can distinguish this from formation.checkout or formation.requirements on purpose alone.

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?

Clear context for when to call: you have a draft and want to know what is missing before handing off to the founder. The "free; does not consume credits" line implicitly separates it from the paid path, but it never names formation.checkout or formation.requirements as the alternative or states the condition that selects between them, so the alternative routing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds business-level context the annotations cannot convey — 'Free; does not consume credits' — which matters for an agent orchestrating a paid formation flow, plus the expected number of returned candidates. Return shape details are covered by the output schema.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the eligibility condition second. Every clause carries information an agent needs.

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

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

With an output schema present and rich annotations, the description covers purpose, cost, and the conditional requirement for the code. The only real gap is what to do with multiple candidates (e.g., how to choose among 2–6 results), which would help an agent chain into formation steps.

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

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

Schema description coverage is 100% and the single parameter is documented as 'What the business does, in plain words.' The description echoes this ('plain-English business description') without adding format, length, or quality guidance beyond the schema's 500-character limit. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Returns candidate NAICS industry codes') with an explicit input ('for a plain-English business description') and expected result cardinality ('typically 2–6'). It is clearly distinguishable from siblings like law.search or formation.requirements, which do not map descriptions to industry codes.

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 sentence 'A code is required for every LLC, and for nonprofits in AK, CT, LA, MS, TN, WV' tells the agent exactly when this lookup is mandatory, which is strong conditional context. It stops short of naming an alternative or stating when not to call it, so it falls short of a 5.

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

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

The description reconciles the surprising readOnlyHint=false annotation by disclosing the write side effect: 'Reading the chain also records a payment that just arrived.' It also surfaces the 48-hour founder email confirmation deadline and the credit cost, all of which are behavioral facts annotations don't 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?

Three sentences, front-loaded with state enumeration, then the side effect, then the cost. Nothing is repeated from the title and no sentence is 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?

An output schema exists, so return values need no explanation; the description still enumerates the states and the confirmation flag, and it covers the one non-obvious side effect and the cost. An agent has everything needed to call and interpret this correctly.

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

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

Schema description coverage is 100%; both parameters (orderId, trackingToken) are already documented as values returned by formation.checkout. The description adds no format, scoping, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Reports the USDC payment state of an LLC or nonprofit formation order') and enumerates the exact state values (awaiting, paid, expired, underpaid, held). It also ties the object back to the sibling 'formation.checkout' that creates the order, so an agent can distinguish status-checking from order creation.

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?

'created by formation.checkout' makes the dependency and the natural call sequence explicit, and 'Free; does not consume credits' tells the agent it is safe to poll. It stops short of saying when not to use it (e.g., for orders that never reached checkout) or how often to re-check.

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 cover read-only, idempotent, non-destructive behavior, so the description adds the genuinely new fact that the call is free and consumes no credits — a real cost signal for an agent planning call sequences. It also flags conditional availability ('when available') for the EIN add-on, warning the agent that a field may be absent. It stops short of describing caching, rate limits, or unsupported states.

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?

Single front-loaded sentence that opens with the verb and resource before listing outputs. It is dense but each clause (what is returned, pricing inclusion, EIN optionality, cost) adds information; the trailing 'Free; does not consume credits' is well-placed as a separate short sentence for emphasis.

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

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

With an output schema and full annotations present, the description need not explain return shape, and it correctly focuses on scope and cost. The remaining gap is that it never indicates which states are supported or what happens for an unsupported state code in an openWorld tool — a real risk given the state parameter is free-text.

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 entityType enum is fully documented, so the schema carries parameter meaning. The description only adds the scoping constraint that the state is a single state ('in one US state'), reinforcing that this is not a multi-state query, but contributes no format or validation detail 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?

Specific verb (Returns) plus precise resource (the intake checklist for forming an LLC or nonprofit in one US state) with the exact contents enumerated: required fields, state-specific questions, all-in pricing, EIN add-on. Clearly distinct from siblings like formation.compare or formation.checkout, which would be comparison or purchase rather than requirements retrieval.

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

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

Usage is only implied — an agent can infer this is the pre-formation lookup step, and 'Free; does not consume credits' hints it is the cheap first call before formation.checkout. But no explicit when-to-use, no named alternatives (e.g. formation.compare for multi-state, formation.checkout for purchase), and no prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so safety and repeatability are covered without the description. The description adds that the response carries the full official text, but says nothing about payload size, missing/invalid-id behavior, or latency that would matter for a single-node fetch.

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

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

One sentence, front-loaded with what is returned, followed by the input needed. No filler, no restatement of the title, and every clause carries 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 single-parameter read tool with an output schema that documents the return shape, this is complete: the description covers what comes back, how to obtain the id, and the annotations cover safety.

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

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

Schema description coverage is 100% and the single parameter's schema text ('Node UUID, as returned in law.search results') is duplicated nearly verbatim in the description. With the schema doing the heavy lifting and only one parameter, the baseline 3 applies.

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

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

States a specific verb (Returns), a precise resource (one legal provision), and the payload contents (full official text, citation, hierarchy), which cleanly separates it from law.search's list-result behavior. The clause 'by its node id (the UUID in search results)' implicitly anchors the agent to the search-then-fetch workflow with a sibling tool.

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

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

The mention of 'the UUID in search results' implies this tool is invoked after law.search, which is useful sequencing context. However, it never states when-not to use it, nor does it differentiate from the other law.* siblings such as law.list_coverage, leaving usage only 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?

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is fully covered. The description adds that results include counts, GIS status, and a 'placeholder flag' — the flag faintly hints at data-quality caveats — but most of this restates return contents the output schema already provides.

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

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

One front-loaded sentence with no filler. The trailing enumeration of return fields is slightly redundant given a dedicated output schema, which keeps it from a perfect score, but nothing is wasted.

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

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

For a simple zero-parameter read tool with an output schema and full annotation coverage, the description supplies enough to call it correctly. The only real omission is routing guidance relative to the sibling law.* tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema shows. Baseline 4 applies for a no-argument tool.

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

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

States a specific verb and resource ('Lists the covered jurisdictions') and immediately scopes it to federal/state/municipal. No sibling tool in the set (law.search, law.get_node) does coverage enumeration, so the agent can disambiguate without opening a schema.

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

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

The description never says when to call this versus law.search or law.get_node, nor that it is a discovery/metadata step preceding a search. Usage is only weakly implied by the tool name. No exclusions or prerequisites are given.

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 read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description still adds real context beyond them: results are ranked and include verbatim citations, headings, snippets and node ids, and jurisdiction scoping automatically expands to sub-jurisdictions. Missing only rate-limit/pagination behavior, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with what is searched and what comes back, then the scoping parameter. No filler or repetition.

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

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

With a full schema, an output schema, and rich annotations, the description covers purpose, result shape, and scoping adequately. It does not explain how to obtain valid jurisdiction codes itself (deferred to law.list_coverage via the schema) or how results feed into law.get_node, leaving a small integration gap.

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

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

Schema description coverage is 100%, so the schema already documents mode, limit, query and jurisdiction thoroughly; baseline is 3. The description's jurisdiction sentence largely restates the schema (including the sub-jurisdiction behavior), adding little new parameter 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?

Specific verb and resource: 'Searches US federal, state, and municipal law by topic or keyword', with concrete topical examples (permits, zoning, licensing) and a stated result shape (ranked provisions with citations). It implicitly separates itself from law.get_node by framing results as ranked provisions carrying node ids, but no sibling is named explicitly, 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 topical examples imply when the tool is appropriate (finding law by subject rather than fetching a known provision), but there is no explicit when-to-use, when-not, or routing to law.get_node / law.list_coverage. Usage is left to inference.

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