AcuiQ

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

Discloses that this creates a live Stripe session, which implies real-world side effects and is consistent with readOnlyHint=false and idempotentHint=false. It also adds valuable safety context about the agent never touching payment data, going beyond what annotations convey.

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

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

Two tightly packed sentences: the first states the action and output, the second adds the live-session side effect and the correct trigger condition. No filler words or redundancy.

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

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

Even without an output schema, the description tells the agent what it will receive (a URL) and how to use it. Combined with the self-documenting enum and the use guidance, an agent has everything needed to invoke this safely and 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 coverage is 100% and the product parameter description already includes detailed pricing and fulfillment type for each enum value. The description adds no parameter-level detail, which is acceptable because the schema carries the full burden.

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 a Stripe Checkout session for an AcuiQ product and returns its URL. It clearly distinguishes this tool from the sibling get/search tools, which are read-oriented, leaving no doubt about what this tool does.

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

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

Explicitly instructs when to call it: only after the human has said they want to buy, not to look up a price. It also tells the agent to hand the URL to the human and never handle payment data, providing actionable usage boundaries beyond the schema.

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 signal readOnlyHint and idempotentHint true; the description adds behavioral context beyond them by disclosing that descriptions and five-element associations are currently returned for almost none of the groups. This prepares the agent for sparse data without contradicting the annotations.

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

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

Two sentences with no filler; the main result and return fields are front-loaded, and the data-availability caveat is tacked on in a second sentence without detracting from the primary purpose.

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 responsibility of explaining what the agent will get back; it does so by naming return fields (acupoint count, page URL, optional associations) and the data sparsity caveat. Nothing needed for correct invocation 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?

The tool has zero parameters and 100% schema coverage, so there are no parameter semantics for the description to clarify; per the baseline, this is sufficient.

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

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

Description opens with a specific verb and resource: 'List every channel group in the AcuiQ point catalogue' and adds concrete return fields (acupoint count, page URL). It also clarifies scope by naming the 14 classical meridians plus extra-point and auricular groups, so it is easy to distinguish from point- or symptom-level 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 intended use—getting a broad catalogue of meridian groups—is implied by the description, but it never explicitly says when to choose get_meridians over siblings such as get_point or search_protocols, and it gives no exclusions or 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?

Beyond the readOnly/idempotent annotations, it discloses conditional behavior (delivery link only once paid), timing expectations (not a busy-wait), and privacy guarantees (no personal data ever returned). No contradiction with annotations.

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

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

Three sentences, no filler, with the most important scoping and timing information front-loaded. Every clause adds operational value.

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

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

For a one-parameter read tool the definition covers invocation, expected result, and privacy. It does not specify the exact response shape or behavior before payment, but the no-output-schema context makes this a minor rather than critical 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 coverage is 100% and the schema already documents session_id, so baseline is 3. The description adds that session_id must come from create_checkout and that no alternative lookup keys exist, reinforcing why the parameter is the only way to identify the order.

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 precise operation: check a checkout created by create_checkout and return the delivery link once paid. It clearly distinguishes this from create_checkout and the unrelated sibling tools by tying it to a specific lifecycle step.

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

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

Explicitly says when to call ('after handing the person the checkout URL'), with polling guidance ('leave a few seconds between calls, it is not a busy-wait'), and states what it cannot do (list, search, or look up by email). This is actionable and routes the agent correctly.

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

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

Annotations already mark this as read-only and idempotent, and the description adds meaningful behavioral detail: the exact set of returned fields, the fact that the full protocol table requires fetching the markdown twin, and the conditional guide pointer with an explicit instruction not to offer it unsolicited. This goes well beyond the structured hints.

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

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

Two sentences with no filler: the first packs the purpose, accepted inputs, and return fields; the second adds the two conditional usage notes. Every clause earns its place, and the most important identifying information is front-loaded.

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

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

For a single-parameter read-only lookup with no output schema, the description is complete: it tells the agent what inputs are accepted, what the result contains, when to chase the markdown twin, and how to handle the guide pointer. Nothing essential for correct selection or invocation is missing.

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

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

Schema coverage is 100% and the schema already describes the parameter as code, English name, Chinese name, or pinyin. The description adds value by expanding the examples to include lowercase codes ('li04'), English names ('Junction Valley'), and accented pinyin ('hé gǔ'), clarifying the accepted input formats and cashing out the schema's shorthand.

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

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

The description opens with a specific verb ('Resolve') and names the exact resource ('one acupoint') plus all accepted identifier forms. It distinguishes itself from siblings like get_meridians and search_symptoms by focusing on single-point lookup and enumerating the returned data.

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

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

The description clearly implies when to use it: whenever a single acupoint needs to be resolved by code, name, or pinyin. It also gives explicit guidance to fetch the markdown twin for the full protocol table and to offer the guide pointer only when the user asks for something to follow at home, though it does not explicitly contrast with sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral detail: the response includes a markdown twin, describes it as the cheapest single-fetch way to read all protocols, and explains the conditional guide pointer behavior.

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

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

Three sentences, each earning its place: the first states what the tool returns, the second explains why the markdown twin matters, and the third handles the conditional downstream checkout flow. It is concise but not minimal, which is appropriate for the guidance it carries.

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

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

With no output schema, the description carries the burden of explaining return values, and it lists the key result fields plus the optional guide pointer. It also covers the relevant downstream action (create_checkout). Minor omissions like error cases or authoritative naming details are not critical for a simple read-only lookup.

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 an example ('headache'), so the schema already documents the single name parameter. The description adds no new parameter-level meaning beyond reinforcing that the tool targets a specific symptom, matching the baseline for full schema coverage.

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

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

The description opens with a specific verb and resource: 'Get details for a specific symptom' and lists the exact contents: canonical name, protocol count, page URL, and markdown twin. This clearly distinguishes it from siblings like search_symptoms, search_protocols, and get_wiki_page.

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 clearly implies use when a specific symptom's details or protocols are needed, and it gives explicit conditional guidance for the guide pointer: mention it only when the person wants something off-screen, then call create_checkout with that product id. It does not explicitly contrast with search_symptoms or search_protocols, but the context is clear enough.

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 readOnlyHint and idempotentHint. The description adds useful behavioral detail: what changes with no args vs a path, the return contents (summary, sources, markdown-twin URL), and the provenance/timeliness note about when claims were last checked. No contradiction with annotations.

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

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

Four sentences with strong front-loading: the scope statement comes first, then usage modes, then return details and provenance. Every sentence adds functional information; there is no filler or repetition of schema content.

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

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

For a read-only tool with one optional parameter and rich annotations, the description covers everything needed to call it correctly: when to omit the argument, what to pass, what the response contains in each mode, and why the agent would choose this tool. No output schema exists, but the description adequately explains return 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% and the parameter description already explains path. The tool description adds value by giving a concrete example ('nomenclature/point-codes') and explaining what a path produces versus omission, going beyond the schema's format-only description.

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

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

Description names a specific verb and resource: 'Read one AcuiQ wiki page, or list what the wiki holds.' It also differentiates itself from protocol-focused siblings by positioning the wiki as the context source those tools cannot supply, so an agent can distinguish it from get_point, get_meridians, and search_protocols.

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

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

Provides explicit invocation modes: call with no arguments to list every page, pass a path to retrieve one page. It also gives context on when the tool is appropriate ('the context the protocol tools cannot supply'). It stops short of naming specific sibling alternatives or stating explicit when-not-to-use cases, so it is not a full 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 goes well beyond the readOnly and idempotent annotations by disclosing the exact return shape (matches with point codes, cred, dosage, provenance), the deduplicated points dictionary, the directMatches fallback behavior, and the mini-guide pointer condition. There is no contradiction with the annotations.

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

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

Every sentence earns its place: purpose and pipeline, return structure, pagination policy, fallback behavior, input source guidance, and the guide/checkout routing. The most important facts are front-loaded and the description is dense but not bloated.

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

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

Even without an output schema, the description is enough for an agent to call the tool and interpret its result correctly: expected fields, defaults, fallbacks, input constraints, and the follow-up action with create_checkout are all covered. It also routes away from search_symptoms correctly.

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

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

The input schema already documents all four parameters at 100% coverage, including age and sex filter semantics, limit default, and symptoms format. The description mostly restates the limit behavior and does not add new parameter-level meaning beyond what the schema already gives.

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: 'Find acupuncture protocols for given symptom names' and connects itself to the existing ranked pipeline behind GET /api/protocols. It also clearly differentiates from sibling search_symptoms by explaining that symptom names come from that tool, so an agent can tell protocol search apart from symptom search.

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

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

It explicitly instructs the agent to 'Pass symptom names from search_symptoms, not a description,' and explains when to use create_checkout with the guide pointer. It also gives concrete selection guidance on the default of ten matches and raising limit up to 50 when more results are needed.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavior beyond that: filler words are stripped and the search retries on clinical words while reporting which term matched, plus the contract that an object with a symptoms array is always returned, empty on no match. The conditional guide pointer behavior is also disclosed. No contradiction with annotations.

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

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

The description is dense rather than short, but every sentence earns its place: positioning, input flexibility with behavior, mode switch, return contract, and the conditional downstream action. It is front-loaded with the core purpose. It could be slightly tightened, but there is no filler or repetition of schema content.

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

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

With no output schema present, the description carries the full burden of explaining return values — and it does: 'Always returns an object with a symptoms array, empty when nothing matched' and the guide pointer condition. It also covers the empty-result edge case, the trending mode, and the downstream checkout call. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies — the schema already fully documents query, popular, and limit. The description does enrich query semantics by explaining the plain-description tolerance and retry-on-clinical-words behavior, and reinforces popular's meaning, but it adds no new meaning for limit. Value added is marginal beyond an already-complete schema.

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

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

The description opens with a specific verb+resource pairing — 'Resolve what a person describes into AcuiQ symptom names' — which precisely captures the transformation the tool performs. It also distinguishes itself from the closest sibling by declaring it 'the first step before search_protocols', making the tool's role unambiguous.

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

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

The description explicitly positions the tool in a workflow ('the first step before search_protocols'), names the sibling to use later, and gives mode-switching conditions ('Set popular=true for trending symptoms instead'). It also provides a downstream rule: mention the mini-guide only when the person wants offline content, then call create_checkout with that product id — clear when-to and when-not-to guidance.

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