I Ching Hexagram MCP

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable behavioral context beyond annotations: it notes the bulk nature, stricter rate limit, and license/attribution requirement with a URL. This is useful for an agent invoking the tool.

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 remarkably concise, with two short sentences covering purpose, usage, constraints, and licensing. Every sentence earns its place, and key information is front-loaded in the first sentence.

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 the tool has only one optional parameter, an output schema, and clear annotations, the description covers all necessary ground: bulk nature, rate limits, ordering options, defaults, and licensing terms. It leaves no meaningful gaps for the agent to worry about.

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 the 'order' parameter with 100% coverage, including the allowed values and default. The description repeats the enum values and default, adding little new semantic meaning. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states it returns the full 64-hexagram dataset in one call, using a specific verb ('get') and resource ('all hexagrams'). It distinguishes itself from sibling tools by emphasizing the bulk nature and full dataset scope.

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 clear usage context: use this when you need the entire dataset in a single bulk call. It also warns about a stricter rate limit, which helps the agent decide when to use this tool versus more granular alternatives, though it does not explicitly name alternatives or 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 already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds the important behavioral condition that data requires attribution ('Data © IChing.Rocks — attribution is a condition of the license terms'), which is not captured in annotations. It also clarifies the nesting semantics of include levels, though that is largely in the 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?

Four short sentences, each earning its place: purpose, parameter options, sibling alternatives, and license notice. The most decision-relevant information is front-loaded, with no redundancy 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?

For a simple read tool with two parameters and an output schema, the description fully covers what the tool does, detailed include behavior, sibling selection, and legal constraints. The output schema covers return values, so further description is unnecessary.

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

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

Schema description coverage is 100%, with both id and include fully documented including default and meaning of each level. The description repeats the values (summary, core, lines, full) without adding new syntax or format details beyond the schema, so the baseline 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 opens with 'One hexagram by King Wen number (1-64)', clearly stating a specific verb (get) and resource (hexagram) with its key parameter. It explicitly differentiates from siblings by contrasting with get_hexagrams (several), get_all_hexagrams (entire set), and search_hexagrams, making the singular scope unambiguous.

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

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

The description explicitly names sibling tools and their use cases: 'get_hexagrams for several numbers at once, get_all_hexagrams for the entire set, search_hexagrams to find hexagrams by text, and get_reading_context for a changing-line reading.' This tells the agent exactly when to prefer this tool over alternatives, and the include parameter options define usage depth.

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 meaningful behavioral context beyond annotations: the license/attribution requirement ('Data © IChing.Rocks — attribution is a condition of the license terms'), which is a non-obvious usage constraint. It also outlines the include levels, but those are also in the 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?

Two sentences: the first establishes the tool's core function and batch limit, the second covers the optional include levels and license. No filler words; information is front-loaded and every sentence 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?

With an output schema present, the description does not need to explain return values. The schema covers parameters thoroughly, annotations cover safety, and the description adds licensing context. The only minor gap is not elaborating on invalid-id handling, but the schema's 'no duplicates, max 16 per call' covers the main constraint, making the description reasonably complete for this complexity level.

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

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

Schema description coverage is 100%, with detailed parameter descriptions for both 'ids' and 'include'. The description repeats the include levels but adds no additional meaning beyond what the schema already provides, so the baseline of 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?

The description clearly states a specific verb ('Batch hexagram lookup') and resource ('hexagrams by King Wen numbers'), explicitly distinguishing this from its sibling tool 'get_hexagram' by the batch aspect ('max 16 ids per call').

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 clear usage context by noting it is a batch operation with a maximum of 16 ids, implying it is the tool to use for multiple hexagram lookups. However, it does not explicitly name alternative sibling tools or state when not to use this tool, so it stops short of a 5.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses determinism, the input-dependent behavior, the absence of divination, and the attribution/license requirement. This adds meaningful context about what the tool does and does 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?

The description is three tightly written sentences. It front-loads the core purpose and behavior, then adds the licensing note. Every sentence earns its place with no redundancy 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?

Given the rich schema, output schema, and annotations, the description provides all necessary context: purpose, behavior under different inputs, determinism, and licensing. Nothing essential is missing for an agent to select and invoke the tool 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 baseline is 3. The description adds value by explaining the effect of changing_lines: empty values return primary only, while non-empty values include the resulting hexagram and transition. It also reinforces the range and ordering constraints already present in 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 clearly states a specific function: 'Deterministic reading context for a primary hexagram (1-64) and 0-6 ascending changing lines.' It distinguishes itself from sibling tools by emphasizing the changing-lines behavior and clarifying that no divination is performed.

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 clear behavioral guidance on when to use the tool: empty changing_lines returns the primary hexagram only; changing lines add resulting hexagram and transition. It implies the tool is for reading context rather than divination, though it does not explicitly name alternative sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds 'Identity only — returns no hexagram data,' which is more about scope than behavior. It provides some context but no additional behavioral traits like side effects or requirements.

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, front-loaded with the purpose and field list. Every word adds value, with no redundancy or fluff.

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, zero-parameter tool with an output schema and clear sibling differentiation, the description is complete. It states what fields are returned and explicitly excludes hexagram data, covering all necessary context.

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

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

The tool has zero parameters, and the schema coverage is 100%. The description does not need to explain parameters, and the baseline for 0 params is 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?

The description clearly states the tool's function: building identity of the MCP server, including specific fields. It explicitly distinguishes itself from sibling tools by noting it returns no hexagram data.

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

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

The description implies when to use it (when server identity is needed) and provides an exclusion (no hexagram data), but it does not explicitly name alternatives. Sibling tools are all hexagram-related, making the differentiation 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 and idempotentHint, so the read-only nature is known. The description adds the attribution requirement and license URL, which is actionable behavioral context beyond annotations. It does not detail error behavior for missing/multiple identifiers, but that is not required given the simple scope.

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: purpose with examples, sibling distinction, and licensing notice. Information is front-loaded and free of 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?

Given the simple single-tool scope, an output schema exists (so return format is covered), and annotations cover safety, the description is complete. It covers purpose, usage, alternatives, and legal terms without extraneous detail.

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 all five parameters with examples and clarifies that 'chinese' holds pinyin. The description adds the crucial constraint that exactly one identifier must be used, which is not captured in the schema's 'default: null' fields, helping the agent understand how to combine parameters.

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 the tool returns one of the eight trigrams using exactly one of five identifier types, with concrete examples. It also explicitly distinguishes this from list_trigrams, which returns all eight, making the purpose unambiguous.

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

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

The description directly contrasts with list_trigrams ('This returns a single trigram; list_trigrams returns all eight'), giving an explicit alternative and when-not-to-use guidance. It also instructs that exactly one identifier must be provided, which shapes usage.

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 provide readOnly and idempotent hints. The description adds valuable context that this is a compact/summary index and includes license/attribution requirements (data © IChing.Rocks), which is beyond what annotations convey. No behavioral surprises are hidden.

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, all information-dense: what the tool returns, optional parameter, and when not to use it. No filler or repetition; front-loaded with the core function.

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?

The tool is simple (one optional param, output schema provided) and the description fully covers its purpose, variants, and relationship to sibling tools. License mention also covers important usage context.

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 documents the single 'order' parameter with enum values and default. The description reinforces this by listing the allowed order values and explicitly stating kingwen is the default, adding clarity 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 the tool lists a compact index of all 64 I Ching hexagrams with specific fields (id, name, pinyin, characters, essence, trigrams, url). It clearly distinguishes from get_hexagram/get_hexagrams (returns full detail) and get_all_hexagrams (returns full dataset) by calling itself the 'summary index 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?

Explicitly explains when to use this tool vs. alternatives: use it for the summary index, get_hexagram(s) for full detail on a known number, get_all_hexagrams for the full dataset, and search_hexagrams for text search. Also notes optional order with a default.

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

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

Annotations already declare readOnlyHint and idempotentHint, so no extra safety disclosure is needed. The description adds useful behavioral context by noting the data copyright and attribution requirement, which is a real condition of use. This goes beyond what annotations provide, though it doesn't cover other behavioral aspects like rate limits or pagination.

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 only two sentences: the first states the core purpose, and the second provides necessary licensing context. Both sentences earn their place, and the main function is front-loaded. No fluff or redundancy.

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

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

Given the zero-parameter input schema, the readOnly/idempotent annotations, and the presence of an output schema, the description covers the essential content (the four orderings) and the licensing requirement. There is no missing behavioral or usage information that the agent would need beyond what structured fields already provide.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly avoids inventing parameter details and instead focuses on the tool's output content. There is nothing to add about parameter semantics since none exist.

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 ('Describes') and resource ('the four canonical hexagram orderings') and names the exact orderings (kingwen, mawangdui, eightpalaces, binary). This clearly distinguishes it from sibling tools like list_hexagrams or get_hexagram, which focus on hexagrams themselves rather than sequence orderings.

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 clear context: it lists the four canonical sequence types, making it obvious that this tool is for retrieving sequence orderings. It does not explicitly mention when not to use it or name alternatives, but the purpose is sufficiently unique among the siblings, so the absence of exclusions is acceptable.

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, which the description does not contradict. The description adds value by revealing licensing/attribution requirements and enumerating the exact fields returned, which is useful behavioral context 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?

The description is two sentences with no redundancy. The first sentence front-loads the key information (all eight trigrams and fields), and the second adds necessary legal context. Every word 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?

Given the tool has no parameters, has an output schema (which covers return structure), and has annotations for read-only/idempotent behavior, the description covers the remaining gaps: the list scope, fields included, and license condition. This is complete for a simple list 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 tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information (there is none), but it clarifies the output content, which is the closest analog to parameter semantics for this endpoint.

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 the tool returns all eight trigrams with a defined set of fields (font, binary, pinyin, etc.). It distinguishes itself from the sibling tool get_trigram by explicitly covering the full set, not a single item.

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 that this lists all eight trigrams implies use when the complete set is needed, but no explicit alternative is mentioned (e.g., 'for a single trigram use get_trigram'). Guidance is implicit rather than direct.

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 discloses many behavioral traits beyond the readOnly/idempotent annotations: determinism, literal matching, closed whitelist, case/diacritic/Chinese-insensitivity, default/max limits, translation source differences, and licensing/attribution. This significantly aids an agent's understanding of the tool's behavior.

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

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

The description is a single compact paragraph with three sentences. It is front-loaded with the core purpose, followed by behavioral details and licensing. The license link is relevant but slightly adds length; overall it is efficient and well-structured.

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 the presence of an output schema, annotations, and a well-populated input schema, the description covers all critical aspects: purpose, matching semantics, limits, data source caveats, and legal terms. No significant gaps remain for an agent to use the tool 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% with each parameter described in detail. The description summarizes optional fields, order, limit (default 10, max 64), which are already in the schema. It adds minimal new semantic value 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 clearly states it is a 'deterministic literal/keyword search' over a 'closed whitelist of hexagram text fields', with the explicit qualifier 'not semantic'. This distinguishes it from sibling get/list tools and precisely conveys the tool's function and scope.

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

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

Provides clear context on when to use this tool: for literal/keyword matching rather than semantic search, and notes case/diacritic/Chinese-insensitivity. However, it does not explicitly name alternative sibling tools for other use cases, so it lacks explicit exclusions.

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