AcuiQ

search_protocols

Read-onlyIdempotent

Find acupuncture protocols for given symptom names — the same ranked pipeline behind GET /api/protocols. Returns matches (each with point codes, cred, dosage and provenance: sourceKind, source, caveat) plus a points dictionary giving each referenced code its name, meridian, location and warnings ONCE. Ten matches by default; raise limit (max 50) if you need more. directMatches lists indicated points when no protocol covers the query — index entries, not prescriptions. Pass symptom names from search_symptoms, not a description.

Input Schema

TableJSON Schema

Name	Required	Description
`age`	No	Patient age. Drops protocols whose recorded cohort age is more than 20 years away; rows that recorded no age are kept.
`sex`	No	Patient sex. Drops protocols recorded in the opposite sex; rows that recorded no sex are kept.
`limit`	No	Max protocols to return (default 10, max 50)
`symptoms`	Yes	Comma-separated symptom names, max 10 (e.g. "headache,neck pain")

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds substantial behavioral context: the ranking pipeline, the exact output shape (matches, points, directMatches), provenance fields, default/max limit, and the caveat that directMatches are index entries, not prescriptions. This goes far beyond the annotations and helps the agent interpret results correctly.

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

Conciseness5/5

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

The description is three sentences, front-loaded with the core purpose and followed by precise output details. Every sentence earns its place with no filler or repetition.

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

Completeness5/5

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

With no output schema, the description fully explains the return structure, the fallback behavior, and the input requirements. Combined with annotations for safety and idempotency, it provides everything an agent needs to call and interpret the tool correctly.

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

Parameters4/5

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

Schema coverage is 100% with descriptions for all four parameters, so baseline is 3. The description adds value by instructing to pass exact names from search_symptoms, which is not in the schema, and clarifies the limit default/max behavior. This goes slightly beyond schema semantics.

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

Purpose5/5

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

The description states a specific verb ('Find') and resource ('acupuncture protocols'), names the underlying API endpoint, and details the return structure. It clearly distinguishes itself from siblings like search_symptoms by specifying the input source and the type of output.

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

Usage Guidelines4/5

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

It provides clear context for when to use the tool (when you have symptom names and want ranked protocols) and explicitly instructs to pass names from search_symptoms, implying a workflow. While it doesn't name alternative tools as exclusions, the guidance is sufficient for an agent to select it correctly.

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

All AcuiQ tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a distinct action: checkout, meridian listing, point resolution, symptom detail, protocol search, and symptom resolution. There is no overlap; even search_protocols and search_symptoms are clearly separated by input and purpose.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: create_checkout, get_meridians, get_point, get_symptom_detail, search_protocols, search_symptoms. No mixing of conventions or vague verbs.

Tool Count5/5

With 6 tools, the set is well-scoped for the server's purpose. Each tool covers a necessary function (purchase, catalogue browsing, point lookup, symptom lookup, protocol search, symptom resolution) without redundancy or bloat.

Completeness4/5

Core workflows are covered: resolve symptoms, search protocols, get point details, list meridians, and checkout. Minor gaps exist—no direct listing of all points or all symptoms beyond popular=true—but agents can work around by using search_symptoms and get_point with known codes.

Resources

Need Help?