OpenFile

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

Annotations already declare destructiveHint=true and non-idempotent, and the description corroborates by saying it 'replaces' the existing image, so the agent knows prior content is overwritten. It also discloses two traits not in the annotations: the operation is blocked once the attorney has filed, and it drives a status transition back to review.

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

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

Two tight sentences with no filler, and the core action plus its replacement semantics are front-loaded. The second sentence is slightly elliptical about what exactly 'sends back for review' means, 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 five-parameter mutation with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies the missing pieces: what is overwritten, the filing-state gate, and the resulting status change. An agent has enough to call 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?

Schema description coverage is 100%, so all five parameters (id, name, token, content_type, content_base64) are already documented, including the 3 MB limit and the enum of accepted image types. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('adds or replaces the image showing the mark in use'), and even disambiguates the legal term 'specimen' into plain language. It is clearly distinct from every sibling (no other tool touches specimen images), though it never names a sibling to contrast with.

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

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

'until the attorney has filed' implies a timing precondition, and 'sends a filing that needed changes back for review' implies the tool is used on filings that were returned for correction. However, neither is framed as an explicit when-to-use rule, and no alternative tool is named.

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, open-world, idempotent, and non-destructive behavior. The description adds useful return-content context—brand, legal owner, and mark ownership—but does not mention reliability, scraping limitations, or what happens when ownership cannot be determined.

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?

It is a single compact sentence with no wasted words, and the input source is front-loaded before the returned information. The fragmentary style is terse but effective.

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

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

With no output schema, the description does communicate the main return concepts, and all three parameters are documented in the schema. However, it omits when to use this over read_site and does not characterize open-world lookup behavior beyond the annotation.

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

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

Schema description coverage is 100%, so the schema already explains site, brand, and owner overrides. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 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 resource extraction task: from a site/app-store link it returns the brand, legal owner, and USPTO mark ownership. A verb is implied rather than explicit, and it does not distinguish itself from the sibling read_site, but the output-oriented purpose is 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 implies usage when a website or app-store link is available, but gives no explicit when-to-use guidance or exclusions. The sibling read_site likely overlaps, yet the description never explains when to choose check_site 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?

The description adds substantial behavior beyond the annotations: it returns review_url, requires owner review/signature before external submission, reports missing items via issues, and gives a token to preserve. These details are important for a draft-creating mutation and do not contradict the annotations, though it does not address auth or rate-limit behavior.

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

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

The description is four short sentences with no waste. The core action and return value are front-loaded, followed by the gating behavior and token-retention note.

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 nested create-draft tool with no required fields and no output schema, the description covers the essential return values (review_url, issues, token) and the external-submission gate. It is close to complete, missing only explicit permission or error-behavior context.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters in detail. The description adds that every field is optional and that issues lists what remains, but it does not add parameter-level semantics beyond that.

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

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

The description states a specific verb and resource: it saves a draft trademark application and returns a review_url. That is clear enough to distinguish it from read-only siblings like get_application or check_site, though it does not explicitly name update_application or quote_application as alternatives.

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 draft-only workflow is implied by 'Saves a draft' and by the note that nothing reaches the attorney or USPTO until the owner signs. However, there is no explicit guidance on when to use this versus quote_application, screen_mark, or update_application, so the agent must infer the selection logic.

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 give the generic destructive/openWorld/idempotent profile; the description adds real context the agent could not infer: nothing is filed or charged before the owner signs, incomplete input is tolerated because 'issues lists what's left', and the response carries a review_url plus a token that must be retained. It does not explain whether repeated calls create duplicate drafts (idempotentHint=false), a meaningful gap for a create 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?

Four short sentences, zero waste, front-loaded with the action and the essential safety fact (nothing filed or charged). Each sentence contributes something an agent needs: outcome, gate, validation behavior, and token retention.

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 20-parameter create tool with no output schema, the description covers the return shape (review_url plus token) and the partial-input behavior well. But it never says what the token is used for or which tool consumes it, and it doesn't address duplicate-draft risk despite idempotentHint=false — gaps an agent needs to close before a second call.

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

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

Schema coverage is 100%, so the schema already documents all 20 parameters including the enum and conditional fields. The description adds only cross-cutting semantics (all fields optional, validation surfaced via 'issues') rather than per-parameter meaning, which matches the baseline 3.

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?

Names a specific verb and resource ('Saves a draft company formation') plus the immediate outcome ('returns review_url for the owner, who checks it and signs'). The draft-versus-filing framing implicitly separates it from filing/quoting flows, but no sibling is named explicitly (e.g., quote_formation, create_application, update_formation), so it stops at 4.

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 workflow is implied ('owner checks it and signs the authorization', 'Every field is optional; issues lists what's left'), which tells the agent this is the entry point that produces a reviewable draft. However, there is no explicit when-to-use versus quote_formation or create_application, nor any stated precondition for calling 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 establish that this is a safe, read-only, idempotent operation, so the description's main added value is noting that the result includes the draft, missing fields, and the signed filing. It does not discuss authentication sensitivity, token secrecy, rate limits, or response structure, but it does add some return-context beyond 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?

It is a single short sentence with no wasted words, but it is a sentence fragment that is front-loaded with unclear return-content hints rather than the tool's primary purpose. It is concise but cryptic rather than efficiently structured.

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

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

For a simple read-only tool with two fully documented parameters and complete safety annotations, the essentials are covered elsewhere. However, the description does not clearly state the retrieval purpose or when to choose it over related tools, and without an output schema it should more explicitly frame what the agent will receive.

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 both the id and token parameters are already fully documented in the input schema. The description adds no parameter-level meaning, which is acceptable given the complete schema but does not exceed the baseline.

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

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

The description hints at what the tool returns ('a draft, what's still missing, and the filing') but never states a clear verb or resource, so it does not clearly say 'retrieve an application.' It is vague rather than tautological, but an agent must infer the action from the tool name and title.

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

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

There is no guidance on when to use this tool versus siblings like get_filing or get_formation, nor any stated prerequisites or exclusions. The description only describes expected content, leaving usage entirely implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description contributes one genuinely useful behavioral fact — the USPTO serial number and attorney note only exist once the filing is actually filed, so responses are state-dependent — but says nothing about failure modes for bad tokens or unfiled records.

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

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

A single short clause with no padding, but it is a sentence fragment with no verb and no leading statement of the operation. Conciseness is fine; front-loading clarity is not.

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?

Annotations supply the safety profile, the schema fully documents both parameters, and with no output schema the description usefully enumerates the returned fields. For a two-parameter read tool, that is sufficient 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?

Schema coverage is 100% and both parameters are documented there, including where the secret token comes from. The description adds no parameter-level meaning beyond the schema, which is the expected baseline here.

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 a noun phrase listing what is returned (status, attorney note, USPTO serial number) rather than a verb stating the operation, so the agent must infer 'retrieve' from the name. It adds concrete content that distinguishes it from list/search siblings, but it never differentiates from the close sibling get_application, which reads like the same subject at a different stage.

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?

No statement of when to use this versus get_application, get_order, or get_filing_type, which all appear to operate on the same filing/application domain. The implicit prerequisite (having the secret token) is only discoverable from the schema, not the description.

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 readOnly, idempotency, and non-destructiveness. The description adds a meaningful behavioral note about availability status, but doesn't cover return format, rate limits, or auth requirements.

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

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

Two sentences with no wasted words, and the core purpose is front-loaded. Slight vagueness in 'fields it needs' keeps it 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?

Given no output schema and moderate complexity, the description covers the key return elements and a state caveat. It could be more complete about what 'fields it needs' includes or the full range of availability values.

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

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

Schema coverage is 100%, so parameter definitions are already clear. The description only reiterates 'for a number of classes' and doesn't add 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 states a specific verb and resource: retrieving one filing type with explanation, fields, and fees. It distinguishes from the sibling list_filing_types by saying 'One filing', though not explicitly.

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?

No explicit guidance on when to use this tool versus alternatives like list_filing_types or get_pricing. It only mentions a state caveat ('availability not_open means it can't be placed yet'), not usage conditions.

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, non-destructive, closed-world behavior. The description adds useful domain context about formation lifecycle states (draft vs. signed) and missing-items reporting, but says nothing about permissions, errors, or rate limits; with annotations covering the safety profile, a 3 is appropriate.

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?

It is a single short sentence with no filler, but it is a cryptic fragment that omits the action verb. Brevity comes at the cost of clarity, so it only partially earns its place.

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

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

For a simple two-parameter read with full schema coverage, annotations, and no output schema, the description should at least state the retrieval action and clarify return contents. It lists return components but leaves the operation itself ambiguous.

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

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

Schema coverage is 100%, and both id and token are documented in the schema, including where the token comes from. The description adds no syntax or meaning beyond that, 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 description is a fragment that lists payload elements (draft formation, missing items, signed order) rather than stating an action. It tells the agent the resource is a formation and hints at lifecycle states, which somewhat distinguishes it from get_order, but it never says it retrieves anything.

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

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

There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as get_order, update_formation, or create_formation. The name implies a read, but the description provides no routing help.

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, closed-world behavior, so safety is fully covered. The description adds some return-content context (status, remaining actions, file number) but, with no output schema present, it leaves the shape and meaning of those fields underspecified.

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

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

A single front-loaded sentence with no filler; it states the return content immediately. It is slightly compressed to the point that 'a signed formation's status' momentarily reads as being about a formation rather than an order.

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

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

For a simple two-parameter read tool with no output schema, the description gives a partial picture of the return value but doesn't explain what the status values mean or what the 'owner still has to do' field contains. Adequate, but not complete enough to fully substitute for the missing 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 100%, so the id and token parameters are already documented, including where the token comes from. The description adds no additional parameter guidance, which matches the baseline 3 when the schema does the work.

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 the resource (a signed formation order) and the exact information returned: status, outstanding owner actions, and state file number. It is clear what the tool does, but it doesn't explicitly differentiate itself from the nearby get_formation sibling, so an agent must infer the boundary.

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

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

There is no statement of when to call this tool versus get_formation, get_application, or the other retrieval siblings. The only implied usage is 'fetch an order', with no prerequisites or exclusions called out.

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 no behavioral traits or operational constraints beyond what the annotations already convey (e.g., readOnlyHint). It only describes the resource content, offering no insight into its operational 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 definition is extremely concise and efficiently covers the three key areas of pricing information in a single, direct sentence.

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 parameter-less tool, it is highly complete regarding *what* information is available. A marginal deduction is given because financial pricing tools often require context on currency or update frequency, which 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?

Since the input schema has zero parameters, the description provides all necessary context by explicitly defining the scope of the pricing data included (packages and fees), which is maximal semantic value for a parameter-less 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?

The description clearly identifies the subjects of the pricing information (Formation packages, trademark package, and USPTO fees). It is highly specific about the domain of the data, though it does not explicitly state *how* these relate to the other quote 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 definition provides almost no guidance on when to use this tool. Given the existence of multiple 'quote' sibling tools, the agent is left to infer if this general pricing tool should be used instead of a specific quote tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the content scope (the four rule categories), with nothing about behavior on an invalid state code or any lookup constraints. With annotations carrying the burden, this is adequate but thin.

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

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

A single noun-phrase sentence with zero filler, front-loading the scope ('One state's') and then the payload. Every clause names a distinct category of returned data.

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

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

With no output schema, the description does the work of enumerating return fields, which it handles well. Slight gaps remain: 'annual report' is ambiguous (requirements vs. due date vs. fee), and there is no hint about response shape or whether the four categories are always present for every state.

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% — the code parameter is documented as a two-letter state code with an example (`WY`). The description adds nothing beyond that: it does not say what happens for unknown codes or direct the agent to list_states for valid values. 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?

Names a specific resource (one state's registration requirements) and enumerates the exact content returned: filing fees, annual report, accepted name endings, publication rules. The singularity implicitly separates it from the sibling list_states, though no verb ('retrieve') is stated and the distinction is never made 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?

Usage is only implied: an agent infers this is the lookup to run when it needs one state's filing requirements, presumably during formation or application planning. There is no statement of when to prefer it over list_states, no prerequisites, and no note that the code should come from list_states.

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 and openWorldHint=false, so safety is covered. The description adds genuine domain context the annotations cannot convey: the wording is ID-Manual-styled and using it avoids the USPTO free-form surcharge. It does not say whether the result is exhaustive, ordered, or how many classes come back.

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

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

Three short sentences, but the front-loaded clause leads with a qualifier ('most') instead of the action, so the agent has to infer the operation from the tool name. The second and third sentences both restate the same benefit (good wording / no surcharge) and could be merged.

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 parameters and no output schema, the description carries the whole burden of telling the agent what comes back, and it never does — no mention of class numbers, class headings, counts, or how the wording list relates to a class selection step. For a trivial zero-arg lookup this is survivable but leaves a real 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Nothing in the description misdescribes inputs.

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 references 'Nice classes' and 'ID Manual style wording' but never states plainly that the tool returns a list of trademark classes; the head noun is 'the classes small businesses file in most', which reads as a curated subset rather than a full enumeration. The verb of the tool (list) is missing, and the sentence's emphasis is on the surcharge benefit rather than on what the call produces.

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?

No guidance on when to use this versus the obvious sibling 'suggest_classes', and no hint about which to call first when picking a class for an application. The only usage-ish signal is an indirect benefit ('avoids the USPTO free-form surcharge'), which explains value but not selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing the shape of the payload (due timing, per-class cost, whether filing can be initiated here), but says nothing about result size, ordering, or whether the catalog is jurisdiction-scoped.

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

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

A single well-formed sentence that front-loads the resource and then lists the three returned attributes in the order an agent would care about them. No filler, no restatement of the title.

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

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

With no output schema, the description carries the burden of explaining returns, and it does name three fields. However, it omits the identifier an agent would need to pass to get_filing_type or create_application, and gives no hint about catalog breadth or how results should be consumed downstream.

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 no parameter semantics to document and the baseline of 4 applies. The description correctly implies a global, unfiltered catalog by saying "Everything that can be filed for a mark" with no scoping caveat.

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?

"Everything that can be filed for a mark" states the resource being enumerated and the three attributes returned (due dates, cost per class, startability), which is enough to separate it from get_filing_type. It never uses an explicit list/retrieve verb, so the enumerating nature is inferred from "Everything" 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?

There is no when-to-use guidance and no reference to the obvious alternative, get_filing_type, which presumably fetches one type by identifier. The agent must infer that this is the discovery call to run before create_application or get_filing_type.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful domain context about what each record carries (price, formation compatibility, ordering channel), but says nothing about ordering, pagination, or whether the list is tenant-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?

A single tight sentence with no filler, and the resource is front-loaded. It is a fragment rather than a complete clause, but every word 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?

With no output schema, the description must convey the return shape, and it names three attributes of each add-on. It omits how to identify a service when passing it to quote_formation or create_application, which is the key follow-up action, so it is adequate but not fully self-sufficient.

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 the baseline is 4 and there is nothing for the description to disambiguate. It correctly does not waste space on argument meaning.

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 the resource ('every add-on') and enumerates the three facts returned per item: price, formation eligibility, and whether the owner self-orders from the dashboard. That is specific enough to distinguish it from the pricing and class-listing siblings, though it never states the verb 'list' or explicitly contrasts with get_pricing.

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

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

There is no guidance on when to call this versus get_pricing, quote_formation, or suggest_alternatives, and no stated preconditions. The agent must infer from the returned fields that this is a catalog-discovery 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context absent from structured fields: fee_verified false means the fee is an estimate, which prevents an agent from presenting estimated fees as authoritative.

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

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

Two short sentences, zero filler, with the resource and its contents front-loaded and the caveat placed second. Every clause earns its place.

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

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

No output schema exists, and the description compensates by naming the return contents (states, LLC and corporation fees) and the meaning of the fee_verified flag. Only minor gaps remain, such as ordering or whether non-US jurisdictions appear.

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?

Zero parameters, so the baseline of 4 applies. The description correctly spends no words on arguments and instead describes the shape of the returned data.

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+resource (list every state) plus the payload it carries (LLC and corporation filing fees). It does not name the sibling get_state as the single-state alternative, so sibling differentiation is left to the name 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?

Usage is only implied: a no-arg enumeration tool whose purpose is self-evident. There is no explicit 'use this when' or pointer to get_state for a single state, though the note about fee_verified implicitly tells the agent how to interpret results rather than routing to another tool.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and 'Changes nothing' is consistent with that. The description adds useful behavioral context about what the tool returns: options, rules, and person-only steps. It does not explain the response structure beyond that conceptual list, so it adds some value but not rich operational detail.

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

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

The description is one long, comma-heavy sentence with a sprawling list of task domains. The core behavior is not front-loaded, and the enumeration crowds out the key facts about what the tool returns and how to call it.

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 one optional parameter, no output schema, and annotations covering safety, the description gives just enough to call the tool: it says what conceptual content comes back and that no change occurs. However, the domain enumeration is noisy and the description still leaves an agent uncertain about the exact response shape and when this planning tool should be preferred over the concrete sibling tools.

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

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

Schema coverage is 100%, so the schema already documents the single `task` parameter as a key or the person's own words. The description adds only the minor detail that omitting `task` returns the list. That is a small increment over the schema, consistent with the baseline 3 when the schema does the heavy lifting.

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

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

The description gestures at a planning/intake tool that returns the questions, options, rules, and person-only actions behind a task, and it enumerates task domains. But the opening phrase 'The questions behind anything a person does here' is vague and never says plainly that this tool plans or explains a task. An agent can infer the intent only after parsing the long enumeration.

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

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

It implies usage by saying 'leave it out for the list' when no task is supplied, and it distinguishes planning from the actual sibling operations such as create_application or get_order by focusing on 'the questions behind' them. It does not explicitly state when to call this instead of the many concrete sibling tools, so the guidance remains implied 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. 'Saves nothing' adds a useful non-persistence clarification, but the rest of the phrasing is too garbled to convey additional behavior such as fee breakdown or error conditions.

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?

It is short, but the brevity comes from under-specification and broken syntax rather than tight phrasing. The one substantive clause is obscured, so no sentence earns its place cleanly.

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 needs to explain what the quote returns (e.g., per-class and government fee breakdown). It hints at 'every fee... with the government's marked' but does not make the return content or structure legible.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the surcharge for free-form class wording. The description adds nothing 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?

The description gestures at computing fees across a number of classes, but never states a verb like 'calculate' or 'quote' and is grammatically broken ('with the government's marked'). An agent must infer the tool's function from the name and the schema rather than from the sentence.

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

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

There is no statement of when to use this versus quote_formation, get_pricing, or list_classes. 'Saves nothing' weakly implies an ephemeral preview, but no explicit condition or alternative is named.

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 and destructiveHint=false, so 'Saves nothing' largely restates the safety profile. It does add one piece beyond the structured data: the response content includes state fees marked, which matters since there is no output schema. That is thin for a quote tool whose main output is a fee breakdown.

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

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

Three short fragments, front-loaded with the outcome and followed by prerequisites and the no-persistence note; nothing is wasted. The telegraphic style ('with the state's marked') costs a little clarity, which keeps it off 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 20-parameter tool with nested objects and no output schema, the description covers only three inputs and says nothing about conditional requirements (shares for corporations, management and members for LLCs, purpose for nonprofits, county for publication states). The per-parameter schema descriptions compensate substantially, but an agent gets no high-level map of which combinations produce a valid, complete quote.

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

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

Schema description coverage is 100% and each of the 20 parameters is individually documented, so the schema carries the burden and the baseline is 3. The description singles out entity/state/package as required, which adds prioritization but actually conflicts with the schema's empty required list, mildly risking confusion about what is truly mandatory.

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 outcome: it returns every fee for a formation with the state's portion flagged. That is a concrete verb-less but unambiguous purpose, clearly a quote rather than a filing. It does not name the sibling it replaces (quote_application) so an agent must infer the difference from the formation-vs-application resource wording.

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?

'Needs entity, state and package' gives the minimum inputs and 'Saves nothing' implies this is the pre-commit preview before create_formation, so the usage context is inferable. However, no alternative is named and no when-not condition is given, leaving the agent to reason about quote_formation vs quote_application on its own.

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, closed-world, so safety is covered. The description adds genuinely new information by stating the return format is Markdown, but says nothing about missing-slug behavior or page size.

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

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

A single front-loaded sentence with zero filler; every clause (resource, format, key) carries 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 one-parameter read tool with full annotation coverage and a well-documented schema, the description covers what the tool returns and how it is keyed. Only edge-case behavior (unknown slug) is unaddressed, which is minor.

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 already explains the slug format and the omit-for-overview behavior. The description's 'by its slug' adds no syntax or format detail beyond the schema, 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 ('one docs page') plus the output format ('Markdown') and the lookup key ('by its slug'). It implicitly contrasts with the sibling search_docs (one page vs. search) but never names it, so 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 phrase 'by its slug' implies you need a slug, and the schema notes the slug can be omitted for the overview. However, there is no explicit when-to-use vs. search_docs, and no guidance on what to do when the slug is unknown.

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, openWorld, idempotent and non-destructive, so the safety profile is covered. The description adds two things the annotations cannot: that every returned value carries its source quote, and that page text is untrusted so results are suggestions requiring human confirmation — a genuinely useful trust/provenance caveat. It stops short of covering failure modes such as unreachable sites or rate limits.

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

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

Two short sentences, zero waste, with the return contract front-loaded and the trust caveat packaged into the second sentence. Nothing is repeated from the title or schema.

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 one parameter, no output schema and full annotation coverage, the description carries the remaining burden well: it tells the agent what comes back and how much to trust it. The gap is sibling routing and any indication of what happens when a site cannot be read, which matters for an openWorld read.

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

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

Schema coverage is 100% and the single parameter already documents that it accepts a website or an App Store/Google Play link. The description adds no syntax, normalization, or URL-format detail beyond that, so the baseline 3 applies — the schema does all the parameter work.

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 resource (a website) and enumerates exactly what will be returned: owner, address, what's sold, each with supporting quotes. An agent can tell this is an extraction/read tool rather than a mutation. It does not, however, distinguish itself from the sibling check_site, which sounds like an adjacent read on the same resource.

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

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

There is no explicit statement of when to reach for this tool versus check_site, read_doc, or search_docs, and no prerequisite or exclusion is given. The only routing signal is implicit in the phrase 'every value is a suggestion for the person to confirm', which hints at early-stage research rather than verified data but never says so or names the 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the check is instant/offline and, critically, cannot see other people's marks — flagging the false-negative limitation. It stops short of saying what the response contains.

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

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

Three short sentences, no filler, with the core purpose and the scanned grounds front-loaded before the scope caveat. 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 two-parameter read-only tool with full schema coverage, the description gives enough to call it correctly. Without an output schema, it could have said what a verdict looks like (flags vs. pass/fail) or pointed to suggest_alternatives as the next step — a minor gap.

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

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

Both parameters are documented in the schema at 100% coverage, so the schema carries the load. The description adds no syntax, format, or tips for the optional 'description' field beyond what the schema already says. Baseline 3 is appropriate here.

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 concrete verb and resource (checks a mark) and enumerates the exact refusal grounds examined: descriptive, generic, surname, place name, famous brand. The line "It can't see other people's marks" implicitly separates it from search_marks, though no sibling is named explicitly.

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 a pre-filing sanity check, and the closing sentence hints at scope boundaries. There is no explicit when-to-use, no named alternative (e.g. suggest_alternatives, search_marks), and no statement of prerequisites or follow-up actions.

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, closed-world behavior, so the safety profile is covered. The description adds that results are ranked 'best sections' with links, which is useful. It says nothing about result count, ranking basis, or what happens when nothing matches.

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

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

Two short sentences with zero waste: the capability and its return are front-loaded, and the usage cue follows immediately. Nothing redundant with the title.

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

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

For a one-parameter read tool with full schema coverage and rich annotations, this covers what it does, what comes back, and when to reach for it. Only the empty-result and ranking-depth behavior remain unaddressed, which is minor here.

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 already ships two concrete example queries, so the schema does the heavy lifting. The description adds no query syntax or phrasing guidance beyond what the schema provides.

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

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

States a specific verb and resource ('Searches OpenFile's docs') and adds the return shape ('best sections with a link to each'), which distinguishes it from the sibling read_doc. It doesn't explicitly name read_doc or search_marks, so sibling differentiation is implied 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?

'Use it when you're not sure how something works' gives a clear triggering condition for an exploratory query. It stops short of the natural pairing – search first, then follow the link with read_doc – and offers no 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 already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: a successful lookup returns checked:true, and failures surface as an error rather than a misleading empty result — critical for the agent not to misinterpret silence as 'no marks found'. The only weakness is that "checked" is an output field with no surrounding explanation.

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

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

Three short sentences, front-loaded with the core action and followed by the error-semantics caveat and scope limit. Every sentence carries weight; 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?

With full schema coverage, rich annotations, and no output schema required, the agent has enough to call correctly: modes, scope, and failure behavior are all addressed. The dangling reference to a checked output field is the only loose end.

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

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

Schema coverage is 100%, so all three parameters are already well documented in the schema, including the mark/owner listing behavior. The description reinforces the two modes but adds no syntax, format, or constraint detail (e.g., how classes affects sorting) beyond what the schema provides.

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

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

"Searches live USPTO records for marks with this name, or lists an owner's marks" states a specific verb and resource and names both operating modes. It doesn't differentiate from close siblings like screen_mark or suggest_alternatives, but the purpose is 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 implies each mode's trigger (name search vs owner listing) and adds a scope constraint ("Federal records only"), giving the agent context on when this applies. However, it gives no explicit when-not guidance or pointers to alternatives such as screen_mark or suggest_alternatives for related tasks.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is the provenance claim: every returned name has passed the refusal screen and a USPTO search. That is a substantive, non-obvious quality guarantee an agent could not derive from the structured fields. It stops short of saying how many suggestions come back or whether the USPTO search is live.

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 clipped sentences, zero waste, with the differentiating detail (passed screening and USPTO search) up front. It is arguably over-compressed rather than padded, which is the better failure mode here.

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 100% schema coverage and full annotations, the remaining burden on the description is the return shape, and it only half-delivers: it says 'names' but not how many, in what form, or whether they are ranked. No output schema exists to 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?

Schema description coverage is 100%, with all four parameters documented in the schema itself (mark, classes, reasons, description). The description adds no syntax, format, or interaction detail beyond that, so the baseline of 3 applies.

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

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

The description identifies the output as alternative names for a risky mark, which is specific enough to distinguish it from search_marks or screen_mark. However, it is written as a noun phrase about the return value rather than stating the action ('suggests replacement marks'), and it never names the siblings it competes with.

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

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

There is no explicit when-to-use guidance and no alternatives named. The phrase 'risky mark' plus the required 'mark' parameter hint that this follows a failed screen_mark, but the agent must infer that routing decision on its own.

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?

While annotations confirm it is a read-only operation, the description provides essential behavioral context by stating 'results are suggestions to confirm with the person,' which prevents the AI agent from treating the output as definitive facts.

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 definition is perfectly sized and front-loaded. It is broken into two concise sentences where every word contributes to defining the scope or the behavior of the 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 effectively addresses the nature of the results, clarifying they are preliminary suggestions rather than final answers, which is the most important contextual information missing from the structured 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?

Since schema description coverage is 100%, the baseline score is 3. The description adds minor value by specifying the input should be 'a plain description of the business' and defines what the mark represents.

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

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

The description clearly states the action (suggest) and the resource (classes, goods, and services wording), making it highly specific. This clearly differentiates it from siblings like 'list_classes' or 'get_application'.

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 usage is implied—use it when you have a plain description of the business. However, it does not explicitly guide when to use it over related tools or under what business conditions it should be invoked.

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

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

Annotations already declare destructive=true and idempotent=true; the description adds genuine value on top by disclosing partial-update semantics ("the fields you send" change, others are untouched) and a hard failure boundary after signing. It still doesn't say whether the token is rotated or what the call returns, which matters for a destructive mutation.

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

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

Two short sentences, both load-bearing: the first defines the mutation semantics, the second the failure condition. Nothing is wasted and the core behavior is front-loaded.

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

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

For an 11-parameter destructive legal-filing mutation with nested objects and no output schema, the description omits consequences the agent would want: whether changing classes affects pricing, whether the token survives, and what comes back. Adequate but thin against the tool's complexity.

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%, including nested owner fields and enum meanings, so the schema already carries the parameter burden. The description only reinforces partial-update behavior and adds no per-parameter detail beyond it — baseline 3 is correct.

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?

Names a specific verb (changes) and a specific resource scope (fields on a draft application), and the word "draft" separates it from create_application and get_application. It does not name a sibling alternative outright, but the partial-update framing is clear enough to select it correctly.

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?

"Fails once the owner has signed" is an explicit precondition that tells the agent when this tool will not work, which is more than most mutation tools offer. No alternative is named for the post-signing case (there is no obvious sibling), 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 declare destructive=true and idempotent=true; the description adds two pieces of context those hints cannot express — that only the submitted fields are changed (partial update, not a full replace) and that the operation is gated on the formation still being an unsigned draft. It does not explain what a destructive update overwrites or what the response contains, so it is strong but not exhaustive.

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 operation and followed by the hard constraint. Nothing is wasted and no sentence merely restates the tool name.

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 22-parameter nested mutation with no output schema, the description covers the lifecycle gate but leaves the return value and failure modes other than the signature lock unstated. Given the schema documents every field, the remaining gap is moderate rather than critical.

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% across all 22 parameters, with conditional rules (basic-only ein/agreement, corporations-only shares/par_value, LLC-only management) already documented in the schema. The description adds no field-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("changes the fields you send on a draft formation") plus the scope that matters most: it only applies to drafts and stops working after owner signature. It does not name siblings such as create_formation or get_formation, but the operation is unambiguous against them.

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?

"on a draft formation" and "Fails once the owner has signed" give a clear precondition and an explicit exclusion, which is real when-to-use guidance. No alternative tool is named for the post-signature case, so it stops short of a full routing rule.

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