Feng Shui MCP Server by RoxyAPI

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

With readOnlyHint=true and destructiveHint=false in annotations, the description still adds meaningful behavioral context: positions include 'degree ranges rather than only sector names,' with the reason for that choice. It also exposes a non-obvious timing rule—'All four move at Li Chun in early February, not at Lunar New Year'—and states that the changeover date is returned. This is substantial value 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?

Four sentences with the core result front-loaded in the first sentence. Each subsequent sentence earns its place: the degree-range rationale, the Li Chun vs Lunar New Year clarification, and the intended use cases. No filler or repetition of schema fields.

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 lookup with one required parameter and no output schema, the description covers the four returned afflictions, the positional format, and the calendar boundary—enough to invoke correctly. The exact response object shape and field names are left implicit, which is a minor gap given the tool has no output schema to fill it.

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 description carries no obligation to document parameters. It does reinforce the 'solar year' and Li Chun boundary, but that mirrors what the schema already says for the year parameter. The baseline 3 is appropriate because the description adds no new parameter-level 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 opens with a specific verb-object statement: 'Return the four annual feng shui afflictions for a solar year with their exact positions,' then enumerates Tai Sui, Sui Po, the Three Killings, and the Five Yellow. The title and content clearly separate this from the flying-stars and bagua sibling tools. No ambiguity about what resource this tool addresses.

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 explicit context for when to use the tool: 'Built for renovation planning, date selection and yearly guidance features.' It does not explicitly name alternatives or state when not to use it, but the intended application is clear enough for an agent to make a reasonable selection decision.

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 destructiveHint=false. The description adds valuable non-obvious behavior: the map is always aligned to true directions independent of entrance facing, and trigram details are guaranteed to match the I-Ching trigram endpoints field-for-field. This meaningfully exceeds what annotations alone provide, though it does not describe response framing 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 compact and front-loaded. Each sentence earns its place: output contents, orientation invariant, data provenance, and intended use cases. There is no filler or repetition of schema fields or annotations.

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 does the necessary work of naming the returned fields and the fixed cardinal mapping, and it adds a consistency guarantee. Combined with a fully documented four-param schema and read-only annotations, this is nearly complete. An explicit pointer to sibling tools would make it complete.

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 input schema already documents lang, limit, offset, and compact. The description adds no parameter-level guidance or examples. At the high-coverage 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?

The description clearly identifies the resource and result: the nine palaces of the compass Bagua map with life area, five phase, colours, and both Later Heaven and Earlier Heaven trigrams. The title adds the verb 'List', so the purpose is unambiguous. However, it does not explicitly contrast itself with the sibling get_feng_shui_bagua_id, so it stops short of full sibling differentiation.

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 final sentence gives concrete intended contexts: floor plan overlays, room-by-room guides, and any interface mapping a space onto life areas. The orientation caveat also clarifies when this fixed-direction compass map applies. No explicit alternatives or when-not-to-use conditions are given, so it is clear context without 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 the tool read-only and non-destructive. The description adds meaningful behavioral detail: what the response covers (sector, five phase, colours, trigram arrangements, governance) and the special exception that the health palace has no direction or trigram. This goes beyond what annotations alone convey.

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 filler. The main action and output are front-loaded, and the important edge case about the health palace is included compactly without derailing the primary definition.

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-lookup tool with fully documented parameters and read-only annotations, the description covers what is returned and the one noteworthy exception. There is no output schema, but the description compensates reasonably well by listing the returned data categories, making the tool safe and callable by an agent.

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 schema already documents the id enum, lang defaults, and compact shape. The description only restates that the lookup is by life area id and adds no new parameter-level meaning, 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 states a specific verb and resource ('Look up one palace... by its life area id') and clarifies it is for a single sector rather than the whole Bagua map. This distinguishes it from the sibling get_feng_shui_bagua tool without needing to open the sibling 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?

The context is clear: use this when you need one Bagua sector by life area id, not the full Bagua map. It does not name its sibling alternatives explicitly or give when-not-to-use conditions, but the single-palace scope makes the intended usage reasonably obvious.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating this is a pure reference endpoint with no chart requirement, and it explains the remedy-element logic, which helps interpret the data. No contradictions with 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 front-loaded with the main purpose and content list, then adds a valuable domain explanation about remedy elements and closes with the chart-free distinction. It is slightly longer than strictly necessary but every sentence contributes useful context.

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 enumerates the returned fields (name, Chinese characters, phase, palace, trigram, period, meaning, strengthening/draining elements, remedy element), giving an agent a clear picture of the response. It remains complete enough for a simple read-only catalogue, though it does not specify ordering or response envelope.

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 parameters (lang, limit, offset, compact) are fully documented. The description adds no parameter-specific meaning beyond the schema, which is acceptable given the baseline of 3 for full 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 identifies a specific verb and resource: it is 'the reference catalogue of the nine flying stars' and lists the exact attributes returned. It also distinguishes itself from chart-based siblings by stating 'A pure reference endpoint that needs no chart.'

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 phrase 'A pure reference endpoint that needs no chart' gives clear context for when to use this tool: for static star reference data, not for chart-dependent calculations. It does not explicitly name sibling alternatives or list exclusions, but the context is clear and the sibling names reinforce the distinction.

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 destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context beyond those hints: the year follows Li Chun rather than Lunar New Year, and the changeover date is returned in the response. These are exactly the kind of non-obvious behaviors that help an agent call the API correctly.

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: the first states the result, the second explains scope and usage, and the third clarifies the critical calendar boundary. It is front-loaded, specific, 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?

With no output schema, the description carries responsibility for explaining what comes back, and it does: the nine-star placement per palace, meanings, element strengthen/drain effects, and the changeover date. It is nearly complete, though a tiny gap remains about whether the response includes any house/direction labels or formatting details.

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 input schema already fully documents year, lang, and compact. The description reinforces that the year is a solar year and references Li Chun, but it does not add parameter-level detail beyond what the schema provides. 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?

The description opens with a specific verb and resource: 'Return the annual flying star plate for a solar year' and enumerates exactly what the result contains (star per palace, meaning, element effects). It also distinguishes the annual plate as universal and building-independent, which sets it apart from building-dependent feng shui 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 clear context: because the plate is universal, it is 'the layer every yearly feng shui guide is built on.' It also warns about the Li Chun changeover and notes the exact date is returned so callers apply it on the right day. It does not explicitly name alternative tools or state when not to use it, 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?

Annotations already signal read-only safety, so the description adds useful behavioral context: solar-month boundaries, Li Chun start, and default month-in-progress behavior. This goes beyond the schema's defaults by explaining why months do not align with calendar months.

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 tight sentences front-load the core purpose and the critical solar-calendar caveat, then state defaults and use cases. Every sentence earns its place with 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 zero-required-parameter read-only tool, the description covers the conceptual return value, key date semantics, defaults, and intended use. The lack of return-value structure detail is a minor gap given there is no output schema, but it does not seriously impair tool selection or invocation.

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 solar-month semantics relevant to year and month but does not add significant information beyond the schema's own parameter 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 ('Return the monthly flying star plate') and distinguishes it from the annual overlay. The solar-month clarification prevents confusion with calendar-month 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?

Gives clear intended contexts: monthly guidance features and timing work for partial-year afflictions. Explains default behavior when parameters are omitted, but does not explicitly name sibling tools or state when to prefer the annual variant.

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 mark it read-only and non-destructive, and the description adds significant behavioral context beyond that: it is a pure reference endpoint, requires no birth data, and discloses the special Number 5 handling in detail — that it is never computed and that the chart returned for 5 is the Kua 2 chart. This is exactly the kind of non-obvious behavior an agent needs to know.

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: purpose first, then usage intent, then the special Number 5 caveat. Both sentences earn their place, and the unusual behavior is explained without unnecessary 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 simple reference endpoint with one required parameter, read-only annotations, and a fully documented schema, the description covers everything needed to call it correctly: what it returns, that it needs no birth data, and the special case for 5. The lack of an output schema is mitigated by the explicit list of returned fields.

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 all three parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining the special meaning of number=5, which is the most confusing parameter value, though it does not need to elaborate on lang or compact because their schema descriptions are already thorough.

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 starts with a specific verb and resource: 'Look up the reference chart for one Kua number', and clearly enumerates the returned content: trigram, east/west life group, and all eight compass sectors. It also distances itself from computed endpoints by calling itself 'a pure reference endpoint with no birth data required', which differentiates it from the post_kua and post_eight_mansions 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 description states when to use the tool: 'for building a lookup table or a picker', and clarifies that no birth data is required, which implies this is not for computed Kua results. It does not explicitly name sibling alternatives or say 'do not use when...', so it falls just short of fully explicit when-not guidance.

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 mark the tool as read-only and non-destructive. The description adds useful behavioral context beyond that: the table is fixed for a building's lifetime, and the Period 9 vs Period 8 example clarifies how completion date affects the result. This is valuable but not exhaustive; no hidden destructive or state-changing behavior exists.

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 information-dense sentences that front-load the resource and scope, then explain the practical consequence with a concrete example. No wasted words, and the example earns its place by illustrating the edge case of a Period 8 building after Period 9 opens.

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 list tool with zero required parameters and a fully documented schema, the description gives enough context to invoke it correctly. It explains the output's real-world meaning and field types, though it does not describe the exact JSON response shape. Since there is no output schema, a brief note on the response structure would push this to 5.

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 meaning to the 'date' parameter by linking it to building completion and current period, and it reinforces the lang/compact defaults are not needed for most calls. It does not substantially extend the schema's parameter documentation.

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 nine 20-year periods of the San Yuan cycle—with a clear scope (1864 to 2043) and the exact data returned (ruling star, five phase, palace, Li Chun date, current period). The use case for natal chart determination further distinguishes it from sibling Feng Shui period-specific 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 explains when to use this tool: to determine which period a building was completed in and therefore which natal chart applies. It does not explicitly name sibling alternatives or exclusion conditions, but the practical context is clear enough for an agent.

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 adds material behavior beyond the readOnlyHint annotation: sectors are returned ordered best to worst, each with a composed reading, and a ranking is included to decide which affliction to accept when no favorable sector is reachable. This meaningfully informs an agent about the return shape and the tool's logic.

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

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

The description is front-loaded with the core deliverable and remains information-dense across four sentences. The enumeration of all eight star names lengthens it, but those names are domain-significant and help an agent recognize the tool's scope.

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

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

For a tool with no output schema, the description covers the essential response behaviors: ordered sectors, per-sector readings, and an affliction-acceptance ranking. Combined with comprehensive schema documentation for language, compact shape, facing, and year boundary, a caller has nearly everything needed; only an explicit top-level response shape 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%, so the baseline of 3 applies: the schema already documents every parameter in detail. The description adds a useful conceptual summary (Kua directly vs derived) but does not need to compensate for missing parameter documentation.

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 identifies the exact operation: it builds the complete Eight Mansions (Ba Zhai) map for a person, classifying all eight compass sectors into the four favorable and four unfavorable stars. It distinguishes itself from sibling feng shui tools by naming the specific domain, output, and use cases.

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 concrete use context ('Built for bed and desk placement tools, room-by-room reports and floor plan overlays') and describes the two input routes: direct Kua number or derivation from birth date and sex. It does not explicitly name sibling alternatives or exclusion conditions, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so no safety contradiction exists. The description adds meaningful behavioral detail by explaining exactly what the read-only operation returns: nine palaces, period/mountain/water stars, formations, per-palace readings, and the prosperous-stars verdict. This goes beyond the structured annotations and gives the agent a concrete picture of the output.

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: purpose, output composition, accepted facing format, and intended use context. It is front-loaded with the primary verb and resource, and the final sentence usefully identifies the audience 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?

Given the domain complexity and the absence of an output schema, the description does an excellent job of telling the agent what to expect: all nine palaces, the three star types, the named formation, per-palace readings, and the classical verdict. Combined with the fully documented input schema, the tool definition is complete enough for correct selection and invocation.

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 every parameter already has rich guidance: facing vs facingDegrees exclusivity, period semantics including Li Chun, language defaults, and compact format behavior. The description only lightly restates that facing is accepted as 24 mountains or a compass bearing, adding no new parameter meaning beyond what the schema already 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 opens with a precise verb, 'Cast', and names the exact resource: the Xuan Kong flying star natal chart. It also specifies the two determining inputs, construction period and facing direction, and lists the output contents in detail. The word 'natal' clearly distinguishes it from the annual and monthly flying star tools among the 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 description gives clear context for when the tool applies: natal charts for buildings, driven by period and facing, aimed at property analysis, overlays, and consultation software. It does not explicitly instruct the agent to use the sibling annual/monthly tools for different time scopes, so it stops short of full when-not guidance.

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 reveals a non-obvious behavioral detail: the Chinese year is resolved at Li Chun, early February birthdays are placed in the correct year, and the boundary that decided the year is echoed back. This adds meaningful context beyond the readOnlyHint and destructiveHint annotations without contradicting them.

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 and front-loaded: core function and outputs first, edge-case behavior second, use cases third. Every sentence contributes, though the final use-case sentence is somewhat generic.

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 listing the return data and clarifying the Li Chun boundary behavior. Parameter options like lang, compact, and yearBoundary are covered in the schema, so an agent has enough to 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?

The input schema has 100% coverage with detailed descriptions for date, gender, lang, compact, and yearBoundary. The description adds no additional parameter-level semantics, 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 states a specific verb and resource ('Calculate the Kua number') and enumerates the return values: number, life group, trigram, and eight compass sectors. However, it does not explicitly distinguish itself from the sibling tool get_feng_shui_kua_number, so it is clear but not fully differentiated.

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 final sentence gives concrete use contexts: 'room and desk placement features, personalised feng shui reports, and any product that needs a favourable direction per person.' This is clear context but there is no when-not-to-use guidance or mention of alternatives among the feng shui siblings.

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