AcuiQ

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

Annotations declare the write/irreversible profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true); the description adds real context beyond them: this hits live Stripe, the session is handed to a human, and the agent never handles payment data. It doesn't say what happens on repeat calls or session expiry, which is the one remaining behavioral gap.

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 action and return value, with the human-in-the-loop constraint and the usage condition each stated once. No filler.

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 3-parameter mutation tool with no output schema, the description covers action, return value, side-effect scope and usage condition, and annotations carry the safety profile. Remaining gaps are minor: session lifetime, repeat-call behavior, and error cases.

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% – product, source and quantity are all fully documented in the schema, including prices and the 1–20 box cap. The description adds no format or semantic detail beyond the schema, so the baseline 3 for full schema coverage 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 ('Create a Stripe Checkout session for an AcuiQ product') plus the return value (its URL). It also implicitly separates itself from the read-only siblings by noting this is not a price lookup, so an agent can choose 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?

Gives an explicit trigger ('when the person has said they want to buy') and an explicit non-trigger ('not to look up a price'), which is stronger than most mutating tools. It stops short of naming the sibling that handles price/product lookup (e.g. a wiki or product page tool), so the routing is implied rather than complete.

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 a closed-world boundary, so safety and side effects need no restating. The description adds genuinely new behavioral context: the return shape per node and the caveat that `tagPaths` can include paths the tree does not name, which warns the agent the tree is 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, both front-loaded, with the purpose stated before the field inventory. The field list is dense but every item earns its place, since no output schema exists to carry it. A shorter framing of `pageCount` vs `pageCountDeep` would be slightly crisper.

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 and no parameters, the description must carry the return contract and it does: node fields (`path`, name, description, `pageCount`, `pageCountDeep`) and the top-level `tagPaths` behavior. Nothing an agent needs to call it correctly or interpret the result 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 takes zero parameters, so there is nothing for the description to disambiguate, which is the baseline 4 case. The description's references to `path`/`tagPath` values describe outputs rather than inputs and do not mislead.

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 resource (the category tree of the AcuiQ reference wiki) with an explicit scope and value claim ('the cheapest way to orient before searching'). An agent can tell this apart from get_pages, list_pages, and search_wiki without opening any 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?

It positions itself as the orientation step before searching and names the two siblings (list_pages, search_wiki) that consume the `path` values it returns, which is a real routing signal. It stops short of stating when not to use it, e.g., that it should be skipped if a path is already known, so it is clear but not exhaustive.

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 say readOnly/idempotent/closed-world; the description adds the real behavioral traits: page-aligned truncation, the truncated/omittedPages/nextSkip return fields, and how to resume via skip=nextSkip. It also discloses what sizeOnly returns (character count, token estimate, per-branch breakdown, largest pages).

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 purpose, then procedures in the order an agent needs them. It is dense and somewhat packed into one paragraph (workflow, params, truncation, alternative), but nearly every sentence carries actionable 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 carries the return-value burden and does so: it names the sizeOnly payload fields and the truncation/resume fields. Combined with the workflow and the sibling pointer, an agent has everything needed 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 coverage is 100%, so the schema already documents all four parameters; the description still adds value by framing sizeOnly as a preflight step and tying skip to nextSkip and tagPath to branch scoping. It largely restates defaults/maxima that the schema already carries, so it is above baseline but not fully additive.

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 — the entire AcuiQ wiki returned as a single text document — and names its purpose (bulk ingestion), which immediately separates it from per-page siblings like get_page/get_pages.

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 an explicit two-step procedure (preflight with sizeOnly=true, then pull) and names the alternative: 'For a handful of pages get_pages is cheaper.' Both the when-to-use and when-not-to-use cases are 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 readOnly/idempotent/openWorld annotations, it discloses the cost ($0.50), the payment rail (Stripe SPT, single use over MPP) and the exact credential location, plus a data-completeness caveat that descriptions and five-element associations are recorded for almost none of the groups. That is material behavioral context an agent cannot get from 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-loads the resource and its returned fields, then payment mechanics, then sibling routing — a sensible order with no filler sentences. It is slightly dense with stacked parentheticals ('plus the extra-point and auricular groups the catalogue files points under', 'which is currently for almost none of them'), which costs it the top mark.

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 zero parameters, no output schema and safe read annotations, the description carries everything needed: what is returned, the payment prerequisite and its exact location, and where to go for a single point. Nothing required to invoke 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?

There are no parameters, so the baseline is 4. Schema coverage is 100% and the description correctly spends its words on return fields rather than inventing parameter semantics; the only 'parameter' mentioned is the payment credential path, which is a transport detail rather than an input.

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 (List) and resource (every channel group in the AcuiQ point catalogue) plus the exact returned fields (acupoint count, page URL) and the scope (14 classical meridians plus extra-point/auricular groups). It explicitly distinguishes itself from get_point for single points, so the agent can separate 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?

Gives both the when ('It is the whole catalogue in one call') and the alternative with its selecting condition ('for ONE point use get_point, which is free'). It also states that every other tool here is free, which removes ambiguity about when paying is required.

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?

Annotations already cover safety (readOnly, idempotent, closed-world), yet the description adds real behavioral detail beyond them: a miss returns nearest pages, URL + '.md' yields markdown, and blocks:true returns stored blocks with ids plus full metadata. It also explains the read-before-edit workflow and the version/baseVersion contract, which nothing else discloses.

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-loads the return shape, then addressing, then the batch alternative and edit workflow — a sensible order with no filler sentences. It is dense and runs longer than most definitions, but nearly every clause carries load; slightly tighter phrasing would reach 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?

No output schema exists, and the description compensates by describing the returned fields, the blocks variant's structure, and the miss response. For a 4-parameter read tool with full annotation coverage, an agent has everything needed to call it correctly and to recover from failures.

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 baseline is 3, but the description adds meaning the schema lacks: it clarifies that path values must be exactly the path or url a listing returns and that a category's path reads its hub, and it expands blocks:true into the full return shape and editing workflow. That is substantive value over the schema's one-line 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 and resource: reads one page 'in full: its text, version, update date and metadata.' Immediately distinguishes it from get_pages (batch) and implicitly from list_pages/search_wiki by naming the sibling it is not.

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: 'For 2 to 20 pages call get_pages, one round trip rather than N.' Gives addressing rules (path preferred over tagPath+slug, not a title, category path reads its hub) and the recovery path for a wrong guess. When-to-use and alternatives are both 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?

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: revisions are newest first, the limit defaults to 20 with a max of 100, and revision ids are what a restore takes. It does not need to repeat the read-only nature already provided by 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 compact and front-loaded: it begins with what the tool returns, then explains addressing, revision id use, and defaults. Every sentence contributes relevant information without repetition or filler.

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 appropriately lists the revision fields an agent will receive, including id, version, change type, message, date, and changed blocks. It also covers ordering and limit defaults. A minor gap is that it does not explain pagination beyond the limit, but the core return shape and usage context are adequately described.

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. The description reinforces the limit default and maximum and says to address the page as get_page does, but most parameter meaning is already fully documented in the schema. It adds little 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?

The description clearly states that this tool returns a page's revisions in newest-first order and enumerates the revision fields returned. It distinguishes itself from get_page by noting that the page should be addressed as get_page does, though it does not explicitly contrast with get_recent_changes.

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 when to use the tool by describing revisions and their use in restore operations, but it does not explicitly state when to choose this over siblings like get_recent_changes or get_page. The reference to addressing pages as get_page does adds some context but stops short of clear usage alternatives.

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 establish read-only/idempotent; the description goes well beyond by disclosing partial-failure semantics that matter operationally: nonexistent paths land in `missing` instead of erroring, overflow past 20 goes to `remaining`, and oversized pages are chunked out to `omitted` with sizes. That tells the agent the call degrades gracefully and that a short response may still mean more work remains.

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-loads the verb, resource, and batch size before any conditional detail, and every clause carries behavioral information rather than restating the name. It is packed into essentially one long sentence, which is dense but not padded.

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 return-value burden and does name the three auxiliary fields (`missing`, `remaining`, `omitted`). It never describes the shape of the successful page payload itself (how content maps back to each path), leaving one modest gap for a tool whose primary return is page content.

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 both parameters are already documented, which sets the baseline at 3. The description adds one genuinely useful constraint, 'Pass `paths` as the listings return them,' warning against normalizing paths, plus the default and truncation behavior of `maxChars`, but it does not elaborate further.

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 with explicit scope: 'Batch read: 1 to 20 pages of the AcuiQ reference wiki in full in one call.' The batch framing plus the 1-20 cap immediately separates it from get_page (single) and list_pages/search_wiki (listing only).

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 a concrete triggering condition: 'which is how to read search or listing results,' tying it to the search/list siblings in the toolset. It omits an explicit inverse rule (use get_page for a single known page), so the routing guidance is clear but not fully closed.

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?

Annotations already cover read-only/idempotent/closed-world, yet the description still adds real behavior: default and maximum values, newest-first ordering, identical row shape to list_pages, and the meaning of `truncated: true` plus the remedial action. It stops short of describing auth or rate-limit behavior, but for a read-only listing tool that is minor.

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 dense sentences, front-loaded with what the tool returns, followed by usage framing and defaults. No filler; the truncation guidance is placed last where an agent needs it after the core selection decision.

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 return-shape duty and does so reasonably via 'Same rows as list_pages' and the `truncated` flag explanation. The full field list must still be inferred from the sibling tool, which is a small residual 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%, so the defaults and maxima restated in the description are largely redundant. The added value is linking `limit` to the downstream `truncated` signal and telling the agent how to react to it — semantics the schema alone does not convey.

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 and scope: pages edited within the last N days, ordered newest first. It explicitly contrasts with the sibling list_pages ('Same rows as list_pages'), so an agent can tell the two apart without opening either 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?

Gives a concrete use case ('what to poll when you are watching the wiki rather than reading it') and a fallback path when truncated ('raise it, or page through list_pages'). It does not state an explicit exclusion, but the read-vs-poll framing effectively implies the boundary against list_pages.

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 declare readOnlyHint/idempotentHint, so the safety profile is covered; the description adds default ordering ('newest first'), pagination contract ('totalPages', 'hasMore', 'nextPage'), and default page size with max. It stops short of discussing the size/cost of walking the whole wiki unpaged, which would matter for get_full_corpus-style large traversals.

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 tight sentences, front-loaded with the differentiator (tag browsing vs keyword) followed by behavior, sorting, and pagination. No filler, and each sentence covers a distinct decision an agent must make.

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, yet the description still discloses the response envelope (totalPages, hasMore, nextPage) and confirms row parity with search_wiki. For a zero-required-parameter list tool with full schema coverage, nothing needed 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 already 100%, so the baseline is 3; the description adds value by explaining tagPath semantics (matches the branch and everything beneath it) and the title-vs-updatedAt sort intent beyond the enum labels. Defaults for page and pageSize are repeated from the schema rather than extended.

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 (browse/list) and resource (reference wiki pages), and clearly distinguishes itself from keyword search by contrasting 'browse by tag path rather than by keyword'. It also names the sibling search_wiki as the equivalent-row alternative, so an agent can separate it from get_pages, get_page, and search_wiki without reading 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?

Gives explicit when-to-use (browse a branch by tag path), a when-not-to-use alternative (keyword search via search_wiki), and an operating mode for omitting tagPath ('omit it to walk the whole wiki'). It even specifies an alternate sort choice (title for A–Z pass), covering the decision points an agent needs.

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 cover the read-only/idempotent safety profile; the description goes well beyond them, disclosing default result count (10), the max (50), the meaning of `studyBacked` when false, that `directMatches` are index entries rather than prescriptions, and the existence of a `guide` pointer tied to a paid mini-guide. That is real behavioral context an agent could not infer from the structured fields.

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, then return shape, then usage and workflow, so the important routing information is easy to find. It is dense and long for a single paragraph, but nearly every clause carries distinct information rather than restating the 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 no output schema, the description carries the full burden of explaining returns and does so: `matches` fields, the deduplicated `points` dictionary, `studyBacked`, `directMatches`, and the conditional `guide` pointer. Combined with the usage and limit guidance, an agent has everything needed to call it and interpret 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 description coverage is 100%, so the baseline is 3; the description earns an extra point by clarifying that `symptoms` must be symptom names sourced from search_symptoms rather than free-text descriptions, which is not stated in the schema. It says nothing extra about `age` or `sex` beyond what the schema already documents.

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 identifies the exact pipeline it mirrors ('the same ranked pipeline behind GET /api/protocols'). It is clearly distinguishable from search_symptoms, which it names as the upstream source of input.

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 routing rules: 'Pass symptom names from search_symptoms, not a description', and a conditional workflow for the guide pointer ('mention it only if the person wants something to follow away from a screen, then call create_checkout with that product id'). Both the alternative tool and the follow-up tool are named with the condition that selects them.

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 cover the safety profile (readOnly, idempotent, closed-world), leaving the description to disclose the interesting behavior: filler words are stripped, the search retries on clinical words, the matched term is reported, and the result always contains a `symptoms` array that is empty on no match. The `guide` pointer and its create_checkout handoff are extra operational context not derivable from 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, each carrying distinct load: purpose, query handling, popular mode, and return/routing behavior. The purpose and the sibling reference are front-loaded; the closing create_checkout sentence is the least essential but still guides agent behavior.

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 the return shape (`symptoms` array, empty on no match, optional `guide` pointer) and the follow-up action. Combined with full schema coverage, an agent has everything needed to call and use the 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?

Schema description coverage is 100%, so the baseline is 3, but the description goes further by explaining how `query` is actually interpreted (plain phrasing accepted, filler stripped, retried on clinical terms) and reconfirms the `popular=true` switch as an alternative mode rather than a search filter. Only `limit` receives no added 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 gives a specific verb and resource ('Resolve what a person describes into AcuiQ symptom names') and explicitly positions the tool relative to siblings by calling itself 'the first step before search_protocols'. An agent can distinguish it from get_symptom_detail or search_protocols without opening any 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?

It names the when ('first step before search_protocols'), the alternative path ('Set popular=true for trending symptoms instead'), and a downstream routing rule ('mention it only if the person wants something to follow away from a screen, then call create_checkout with that `product` id'). When-to-use and when-not-to-use are both 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 cover read-only/idempotent, but the description adds substantial context beyond them: the exact four-tier ranking order, stemming and stopword handling, and the shape of each result row (path, chars, snippet windowed on the match). Paging behavior (defaults, pageSize max, keep paging while hasMore) is disclosed.

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 purpose, then ranking rules, then result shape, then follow-up and parameters. Dense but every sentence carries actionable information; no rhetorical filler.

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, but the description describes the result row fields and the paging signal (hasMore). Combined with annotations covering safety and a fully documented schema, an agent has everything needed to invoke, page, and hand off to get_pages.

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 goes beyond it by explaining the practical role of tagPath (narrowing a common term) and by restating the paging defaults and the hasMore continuation rule in context.

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 ('keyword search across the AcuiQ reference wiki') and immediately scopes the match behavior (titles and body prose), distinguishing it from get_page/get_pages and the search_protocols/search_symptoms 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?

Explicitly names when to use it ('first call when you know what you are looking for but not where it lives'), when to narrow ('use tagPath when a term is common'), and the follow-up workflow ('feed the paths to get_pages in one call rather than looping get_page'). It also gives a negative guideline: not semantic, so one distinctive word beats a sentence.

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 this as a non-readonly, non-destructive write, so the bar is lower. The description adds real context beyond them: a hard 300-character cap and the fact that "Reports are read, not published," which reassures the agent the submission is private. It does not mention whether duplicate submissions are deduplicated or what the call returns.

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 filler; the purpose leads and the constraints (one issue per call, 300 characters, not published) follow immediately. 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?

For a three-parameter submission tool with full schema coverage and no output schema, the description covers purpose, limits and audience. The only gap is what the agent gets back after sending, which is minor for a fire-and-forget feedback 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 description coverage is 100%, including a fully documented enum for kind, so the schema carries the parameter burden. The description's 300-character limit restates what the message property already says, adding little. Baseline 3 is 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?

States a specific verb (tell the maintainers), a specific resource (feedback about AcuiQ), and enumerates the cases it covers: missing content, wrong content, breakage. All siblings are read-only lookup tools, so there is no plausible confusion about which tool to pick for this action.

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?

"what you needed and did not find, what is wrong, or what broke" maps cleanly onto the kind enum and tells the agent when this tool applies. "One issue per call" gives batching guidance. It stops short of explicit exclusions or naming an alternative channel, so not a 5.

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