AcuiQ

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

Annotations already signal this is a non-read-only, non-idempotent action. The description adds valuable context: it creates a live Stripe session, the agent never touches payment data, and the URL must be handed to the human. This goes beyond what annotations provide.

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

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

Three sentences, each earning its place: core action plus return value, human handoff safety instruction, and usage trigger. The most important information is front-loaded without unnecessary detail.

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

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

For a mutating tool with no output schema, the description adequately covers the return value, the real-world effect (live Stripe session), and the appropriate call condition. Product details are fully covered by the input schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, and the enum parameter already includes detailed pricing and delivery information. The description does not need to add parameter semantics and does not meaningfully do so, 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 states a specific action ('Create a Stripe Checkout session'), the exact resource ('for an AcuiQ product'), and the return value ('return its URL'). This clearly differentiates the tool from the read-only get/search sibling tools.

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

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

The description gives an explicit usage trigger: call it when the person has said they want to buy, and an explicit non-use: not to look up a price. It does not name a specific alternative tool, but the read-only sibling set makes the distinction clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: it reveals the returned fields, the grouping scheme, and that descriptions and five-element associations are currently sparse ('almost none').

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, each earning its place. The first sentence front-loads the main purpose and output fields; the second adds a relevant data-completeness caveat without 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?

For a no-parameter, no-output-schema listing tool, the description is complete: it identifies the resource, the exact scope, the returned fields, and the current data-quality limitation. An agent has enough information to invoke the tool and set correct expectations about results.

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 schema places no burden on the description. With 0 params, baseline is 4; the description also adds value by explaining what kind of data is returned even though there is nothing to parameterize.

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 ('List'), a specific resource ('every channel group in the AcuiQ point catalogue'), and the output contents (acupoint count, page URL). It also names the scope: 14 classical meridians plus extra-point and auricular groups, distinguishing it from point- or symptom-level siblings.

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

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

The context is clear: use this tool to get the full catalogue-level list of meridian groups rather than a single point or symptom detail. It does not explicitly name alternatives or exclusions, but the exhaustive 'every channel group' wording makes the intended use unambiguous relative to the 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 readOnly, idempotent, and openWorld hints, so the bar is lower. The description still adds meaningful behavioral context: it returns a link only once payment is confirmed, is not a busy-wait, requires the create_checkout session_id, and never returns personal data. This goes well 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?

Three sentences cover purpose, timing, polling behavior, source of the parameter, and privacy constraints with no filler. The main action is front-loaded and every sentence carries useful information.

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

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

For a simple one-parameter tool with rich annotations and no output schema, the description is complete: it identifies the parameter, the expected caller flow, the polling cadence, and what the tool returns. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already explains that session_id is the value returned by create_checkout and starts with 'cs_'. The description reinforces that the session_id is required and cannot be replaced by email or other lookup, but it does not add substantial 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: check a checkout created by create_checkout and return the delivery link once paid. It clearly distinguishes the tool from siblings like create_checkout and the unrelated get_* and search_* tools, and explicitly notes that orders cannot be listed, searched, or looked up by email.

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

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

It gives explicit guidance on when to call the tool: after handing the person the checkout URL. It also warns against using it as a busy-wait loop by recommending a few seconds between calls, and explains that the session_id must come from create_checkout. No alternatives are relevant, and the constraints are clearly stated.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the full return shape (location, cautions, meridian, co-selected points, URL, markdown twin) and reveals conditional behavior: a `guide` pointer appears only for the best-evidenced indication when a $5 mini-guide exists, with a rule for how to offer it. This is rich behavioral context beyond what annotations provide.

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

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

Three sentences with no filler: the first front-loads the core resolve-and-return behavior, the second gives a follow-up action, the third states a conditional rule. Every sentence earns its place and the example lists are dense but scannable.

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

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

For a single-parameter, read-only lookup with no output schema, the description is complete: it covers accepted inputs, return contents, the follow-up path (markdown twin), and the presentation rule for the optional guide pointer. An agent has everything needed to invoke it correctly and shape the response appropriately.

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

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

Schema coverage is 100%, so the baseline is 3, but the description extends the schema's terse examples ('LI4', 'Hegu', '合谷') with formats the schema omits: lowercase zero-padded codes ('li04'), an English-name example ('Junction Valley'), and tone-marked pinyin ('hé gǔ'). This meaningfully clarifies accepted input variations.

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

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

The description uses a specific verb ('Resolve') with a specific resource ('one acupoint') and enumerates the accepted identifier forms and the return payload. It distinguishes itself from siblings like get_meridians, search_symptoms, and get_wiki_page by focusing on single-point resolution by various names, so an agent can tell it apart without opening other tool schemas.

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

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

The description gives actionable context: resolve a single point via code/name/pinyin, fetch the markdown twin when the full protocol table is needed, and only present the guide pointer when the person wants something to follow at home. It provides clear conditional guidance, though it never explicitly names when-not-to-use this tool in favor of a sibling.

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 aligns with the readOnlyHint and idempotentHint annotations by indicating a fetch operation. It also adds transparency by explaining the condition under which a guide pointer appears and when to proceed to checkout, without contradicting the read-only nature.

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 three sentences long, reasonably focused, and front-loaded with the core purpose. It includes some extra guidance about the markdown twin and the guide pointer, which adds value but makes it slightly less concise than strictly necessary.

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

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

Given a simple tool with one parameter and no output schema, the description covers the essential output fields and the special guide pointer behavior. It does not describe the overall response structure, but that is acceptable since no output schema is provided and the key information is mentioned.

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

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

The schema already fully describes the single parameter 'name' as a symptom name with an example. The description does not add any additional meaning about the parameter's format, constraints, or possible values, so it matches the baseline expected from a fully documented 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 clearly states that the tool gets details for a specific symptom, listing the specific fields returned (canonical name, protocol count, page URL, markdown twin). It distinguishes itself from search tools by focusing on a single symptom's detail retrieval, making the purpose unmistakable.

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

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

The description provides a usage tip ('the markdown twin is the cheapest way to read every protocol for one symptom in a single fetch') and instructs when to trigger create_checkout for the guide pointer. However, it does not explicitly contrast this tool with the search-like siblings (search_symptoms, search_protocols), so some contextual guidance is missing.

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 cover readOnlyHint and idempotentHint, so the safety profile is already clear. The description adds behavioral detail beyond the annotations: no-argument calls return a list with section and summary, while path calls return summary, sources, and a markdown-twin URL. It also discloses that pages include provenance information about when claims were last checked.

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

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

The description is front-loaded with the core purpose and then moves into usage and return behavior. Every sentence earns its place: purpose, context, invocation modes, and provenance. The provenance sentence is slightly extra but useful for setting expectations about content freshness.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers both call modes, what each returns, provides a path example, and explains the kind of content a caller should expect. An agent can confidently decide whether and how to invoke this tool.

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

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

The schema already describes 'path' with an example and says omitting it lists every page, so schema coverage is complete. The description adds value by explaining what the caller gets when passing 'path' (summary, sources, markdown-twin URL) and gives another concrete path example ('nomenclature/point-codes'), reinforcing the behavior of the parameter.

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

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

The description states a specific verb and resource: 'Read one AcuiQ wiki page, or list what the wiki holds.' It also positions the tool as a knowledge base distinct from the protocol tools by calling it 'the context the protocol tools cannot supply,' which helps differentiate it from sibling getters like get_point and get_meridians.

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 tells when to use the tool: for reference notes on nomenclature, point safety, and prescription theory. It also gives clear invocation guidance: call with no arguments to list pages, or pass 'path' to fetch a single page. It does not name a specific sibling as an alternative, but the contrast with 'protocol tools' provides enough context.

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

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

Goes well beyond the readOnly/idempotent annotations by detailing the return shape: matches with provenance, a points dictionary deduplicated and emitted once, directMatches as index entries rather than prescriptions, a default limit of 10, and a guide pointer for mini-guides. This gives the agent a clear model of what the call will and will not do.

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?

Dense but efficient: every sentence earns its place, and the most critical scoping ('for given symptom names', 'same ranked pipeline') is front-loaded. The later sentences pack return-structure, caveats, and cross-tool routing without 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 no output schema present, the description carries the full burden of explaining the response and does so thoroughly: matches, points, directMatches, guide pointer, and the create_checkout follow-up. It also covers input provenance and limit behavior, making the tool safely callable without further inference.

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

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

The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds an important semantic constraint beyond the schema — symptom names must come from search_symptoms, not a description — and reinforces the limit default/maximum, lifting it to 4.

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: 'Find acupuncture protocols for given symptom names' and ties it to the ranked pipeline behind GET /api/protocols. The description also distinguishes it from search_symptoms by instructing that symptom names must come from that tool, so an agent can keep siblings apart.

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

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

Gives explicit input guidance: pass symptom names from search_symptoms, not a free-text description. It also provides conditional routing, telling the agent to call create_checkout with the product id only when the user wants the $5 mini-guide away from a screen.

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, and the description adds substantial behavioral detail beyond them: filler-word stripping, retrying on clinical words, reporting which term matched, always returning a symptoms array, returning an empty array when nothing matches, and conditionally carrying a guide pointer. This is exactly the context an agent needs that the annotations do not provide.

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

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

The description is dense but every sentence earns its place: core purpose, natural-language behavior, alternative mode, return contract, and conditional checkout handoff. It is front-loaded with the operation and resource, and flows logically through the calling sequence.

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 search tool with no output schema, the description fully covers the return shape, empty result behavior, and the guide-pointer branching. It also names the relevant siblings and next steps, so an agent has enough context to invoke the tool correctly and know what to do with the results.

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 is 3. However, the description adds real meaning beyond the schema: query accepts plain conversational descriptions and is processed semantically, popular=true switches modes rather than merely filtering, and the result shape depends on the chosen parameter. The only minor gap is that limit is not addressed, but the schema already covers it.

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: resolve a person's description into AcuiQ symptom names. It also distinguishes itself from siblings by positioning this tool as 'the first step before search_protocols,' so an agent can tell it apart without inspecting other definitions.

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

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

It explicitly says when to use this tool (as the first step before search_protocols), when to use the popular mode, and when to follow up with create_checkout for the guide pointer. This gives the agent clear routing logic and exclusions.

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