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 already cover readOnlyHint, idempotentHint and openWorldHint=false. The description adds real value beyond that: it discloses what each page returns (summary, sources, markdown-twin URL) and that pages carry provenance and recency metadata ("what it rests on and when those claims were last checked"). It stops short of stating size/pagination limits, so it is not a full 5.

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

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

Purpose is front-loaded, then invocation modes, then the search_wiki pointer. Each sentence carries information, though the middle "context the protocol tools cannot supply" aside is slightly editorial and the whole runs dense for a one-parameter 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?

With no output schema, the description compensates by describing return contents and provenance fields. For a single optional-parameter read tool with covering annotations, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further than the schema by explaining the omit-to-list-all behavior and giving a concrete path format example. That meaningfully enriches the single parameter beyond its schema doc.

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?

It names a specific verb and resource (read/get a wiki page) and immediately states the dual behavior: read one page or list the whole wiki. It also distinguishes itself from siblings by positioning the content as "the context the protocol tools cannot supply" and routing topic lookups to search_wiki.

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 call modes ("call with no arguments to list every page" vs "pass 'path' to get one page") and names the alternative tool for the adjacent task ("To find the page for a topic, call search_wiki first"). An agent can pick the right invocation without inference.

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

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

With no output schema, the description carries the return-shape burden and does so: `matches`, per-match provenance (sourceKind/source/caveat), a deduplicated `points` dictionary, `directMatches` semantics as index entries rather than prescriptions, and the conditional `guide` pointer. It also discloses default (10) and cap (50) result counts, which goes beyond the annotations' safety profile.

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

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

Front-loaded with purpose and return shape, and nearly every clause carries new information. It is one dense block, though, and the final sentence about the guide pointer is long enough that a reader must parse it carefully – efficient but slightly overloaded.

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, non-open-world tool with no output schema, the description covers invocation (required symptom names), result volume controls, the full returned structure, and the cross-tool handoff to create_checkout. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by specifying that `symptoms` must be symptom names sourced from search_symptoms and by restating the limit default/max in context. It does not add anything for `age`/`sex` beyond the schema's own cohort-filter descriptions.

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

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

States a specific verb+resource+scope ('Find acupuncture protocols for given symptom names') and even names the underlying pipeline (GET /api/protocols). It differentiates itself from search_symptoms by insisting on symptom names rather than a free-text description, so an agent can route correctly without opening 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?

Explicit routing: use search_symptoms to obtain the symptom names to pass here, not a natural-language description. It also names the downstream alternative (create_checkout) and the exact condition that should trigger it (only when the person wants something to follow 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.

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

Annotations only declare the safe-read profile (readOnlyHint, idempotentHint, openWorldHint=false); the description goes well beyond by disclosing the matching semantics (literal match with English full-text fallback, stemming, stopword removal), the explicit non-semantic limitation, the ranking order, and the pagination contract (page 1/size 10, max 50, page while hasMore). None of this is recoverable from the annotations or schema.

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

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

Front-loaded with the core when-to-use and sibling routing, with technical detail and defaults pushed to the back. It is dense but nearly every clause earns its place; the only mild waste is restating the page/pageSize defaults that the schema already 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?

There is no output schema, so the description correctly takes on the return-value burden by describing each row ('snippet' windowed on the match, the 'path' get_wiki_page takes, and the 'markdown' URL). Combined with the ranking rules, fallback behavior and pagination, an agent has everything needed to call and consume the result.

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

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

Schema coverage is 100%, so the baseline is 3 and 'page'/'pageSize' defaults are already documented. The description adds genuine meaning by tying them together into a paging loop driven by 'hasMore' and by describing the query field's behavior (keywords, phrases, whole questions, full-text fallback) rather than just restating 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?

Opens with a specific verb+resource ('Keyword search across the AcuiQ reference wiki') and immediately scopes it as the tool for topic/question queries with no page path. It explicitly contrasts itself with get_wiki_page, so an agent can differentiate it from siblings without opening a schema.

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

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

States when to use it ('when you have a topic or a question ... and no page path') and names the alternative with its own condition ('Use get_wiki_page instead when you already have a path, or to see every page by section'). This is explicit when/when-not/alternative guidance.

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