Feng Shui MCP Server by RoxyAPI

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: positions come with degree ranges rather than just sector names because Tai Sui occupies 15 degrees; all four afflictions move at Li Chun rather than Lunar New Year; and the changeover date is returned. This gives the agent the key behavioral facts needed to interpret results correctly.

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

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

The description is front-loaded with the core purpose and enumerates the four afflictions immediately. Every sentence adds useful information: positional precision, the Li Chun timing, the changeover date, and target use cases. It is dense but not padded, and the structure flows logically from result to boundary conditions to application.

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 has an output schema, so return-value details are not required in the description. The description fully covers purpose, scope, positional behavior, calendar boundary, and intended usage contexts. Combined with the high-coverage input schema and read-only annotations, an agent has everything needed to invoke this 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 input schema already documents all three parameters well. The description reinforces the year semantics (Li Chun boundary) but does not add new meaning for lang or compact beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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 four annual feng shui afflictions for a solar year with their exact positions.' It names exactly which afflictions are included (Tai Sui, Sui Po, Three Killings, Five Yellow) and gives positional detail, clearly distinguishing this from sibling tools focused on bagua, flying stars, or periods.

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 application context: 'Built for renovation planning, date selection and yearly guidance features.' It also explains the Li Chun boundary, which is essential for correct usage. It does not explicitly name sibling alternatives or say when not to use this tool, but the context is specific enough to guide selection.

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: the map is aligned to true directions regardless of entrance facing, and trigram details are served from the same source as the I-Ching endpoints so they agree field for field. This gives the agent confidence about data semantics and consistency.

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 four sentences long, front-loads the core content, and contains no filler or repetition. Every sentence earns its place: what is returned, how it is aligned, consistency with I-Ching endpoints, and intended use cases.

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 endpoint with zero required parameters and a full output schema, the description provides everything an agent needs: data content, semantic orientation, consistency guarantees, and use cases. The annotation already covers side effects, and the output schema covers return structure, so nothing essential 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 schema already documents lang, limit, offset, and compact in detail. The description does not add parameter-level meaning beyond what the schema provides, which matches the baseline for high coverage. No compensation is needed.

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 identifies exactly what is returned: the nine palaces of the compass Bagua map, each with life area, five phase, colours, and both Later and Earlier Heaven trigrams. It also distinguishes this tool from other feng shui endpoints by emphasizing the compass-aligned, direction-fixed nature of the map. The title and description together make the tool's 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 provides clear use cases: floor plan overlays, room-by-room guides, and any interface mapping a space onto life areas. It also clarifies that this is the compass map rather than one dependent on entrance facing. It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough for an agent to route correctly.

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 this as read-only and non-destructive. The description adds useful behavioral context beyond that: it lists the returned data (compass sector, five phase, colours, trigram arrangements) and explicitly documents the health palace special case of having no direction or trigram. No contradiction 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?

Three concise, front-loaded sentences with no filler. The first sentence defines the operation, the second summarizes the return payload, and the third documents the important exception. 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?

For a simple single-lookup tool with full schema descriptions, read-only annotations, and an output schema available, the description is complete. It covers what the tool returns, the key input concept, and the notable health-palace exception. An agent has enough 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 coverage is 100%, so the schema already documents id, lang, and compact. The description adds semantic value by explaining the 'id' selects a life area and by highlighting that 'health' behaves differently as the centre with no direction or trigram. This goes beyond the enum list 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?

States a specific verb and resource: 'Look up one palace of the compass Bagua map by its life area id.' The description clearly scopes the tool to a single sector lookup, not the whole map, and gives concrete examples such as wealth, career, or love. This effectively distinguishes it from sibling tools like get_feng_shui_bagua.

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 clearly establishes when to use the tool: when you have a life area id and want details for one bagua palace. It does not explicitly name sibling alternatives or exclusions, but the 'one palace... by its life area id' framing gives enough context for an agent to select it appropriately.

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, covering the safety profile. The description adds useful context by emphasizing this is a pure, static reference and explaining the remedy-element reasoning, but it does not disclose other behavioral details such as pagination behavior or response shape beyond what annotations and schema already 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 dense, purposeful sentences with no filler. The description front-loads the core reference catalogue content, then adds the remedy-element nuance, and ends with the distinguishing 'needs no chart' guidance. 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?

For a static read-only reference endpoint, the description is complete: it states what the data is, what fields are included, the domain logic behind remedy elements, and the key distinction from chart-based tools. Output schema exists and annotations cover safety, so nothing critical is missing for an agent 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 description coverage is 100%, so lang, limit, offset, and compact are already fully documented. The description adds no additional parameter-level information, which is acceptable given the schema does the heavy lifting; 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 states exactly what the endpoint is: a reference catalogue of the nine flying stars, listing the specific attributes returned (name, Chinese characters, five phase, home palace, trigram, ruling period, meaning, strengthen/drain elements). It also distinguishes itself from chart-based siblings by saying it is '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 description gives clear context for when to use it: when you need the static reference catalogue of nine stars rather than a chart-based reading. It does not explicitly name alternatives like the annual or monthly flying star endpoints, but the 'needs no chart' phrasing makes the intended use reasonably clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: the plate is universal, the changeover occurs at Li Chun rather than Lunar New Year, and the exact date is returned so callers apply the plate 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 with no filler, front-loading the core action and output contents first. Every sentence earns its place: what it returns, how it differs from building-specific charts, and the critical date nuance.

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 output schema exists, annotations cover safety, and all parameters are fully described in the schema, the description supplies the missing domain context: the plate's universality, its role in yearly guides, and the Li Chun boundary. Nothing an agent needs 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 description coverage is 100%, so the schema fully documents year, lang, and compact. The description reinforces the meaning of 'solar year' and the Li Chun boundary, but it does not add material information 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 specific verb and resource: 'Return the annual flying star plate for a solar year,' then enumerates what the plate contains (stars, palaces, meanings, elements). It distinguishes itself from building-dependent or monthly variants by stating the annual plate is universal and does not depend on any building.

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 clearly positions this tool as the building-independent yearly layer on which annual feng shui guides are built, giving strong context for when to use it. It does not explicitly name sibling alternatives or state when not to use it, but the universality and annual scope make the usage context 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?

With readOnlyHint=true and destructiveHint=false already covering the safety profile, the description adds meaningful behavioral context: solar months follow the twelve major solar terms, never align with calendar months, and omitting parameters yields the current month. It also flags the API as a 'faster overlay,' a useful performance and composition trait.

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 substantive sentences with the core result front-loaded and the non-obvious solar-month caveat placed immediately after. Every sentence earns its place, with no filler or unnecessary repetition of schema details.

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 100%-covered input schema, an output schema, and read-only annotations, the description covers the domain-specific ambiguity around solar months, default behavior, and intended use. Nothing an agent needs to call this tool 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?

The input schema fully documents all four parameters with defaults, ranges, enums, and examples, so the description does not need to carry the schema. It still adds value by clarifying the solar-month model and by stating the combined default behavior when both parameters are omitted.

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 concrete verb-resource pair ('Return the monthly flying star plate') and immediately distinguishes it from the annual concept by calling it 'the faster overlay that sits on top of the annual one.' This clearly separates it from sibling tools like get_feng_shui_flying_stars_annual_year.

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 identifies specific use cases: 'monthly guidance features' and 'timing work around an affliction that only lands for part of the year.' It also explains the default invocation ('Omit both parameters to get the month in progress'), though it does not explicitly name an alternative tool or state when not to use it.

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 substantial non-obvious behavior: Kua 5 is never a computed result, belongs to the centre, and the chart returned for 5 is the Kua 2 chart. It also explains the man/woman substitution rule, which is valuable 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 opens with the core purpose and outputs, then gives usage context, then the edge case. Every sentence earns its place, and there is no filler or repetition of schema details. The long third sentence is dense but directly relevant.

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 spell out the return shape. It provides the lookup context, the no-birth-data distinction, and the critical Kua-5 edge case, making it complete 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 description coverage is 100%, so the baseline is 3. The description adds extra semantics for the `number` parameter that the schema lacks, specifically the special meaning of 5 and its mapping to the Kua 2 chart. This is meaningful 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 states a specific verb ('Look up') and resource ('the reference chart for one Kua number'), and enumerates the returned contents: trigram, east/west life group, and all eight compass sectors. It also distinguishes itself from computation-oriented siblings by labeling itself a 'pure reference endpoint' with no birth data required.

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 cases ('building a lookup table or a picker') and explicitly says no birth data is required, which implies a computation endpoint should be used when birth data is present. However, it does not name the sibling computation tool directly or state a clear 'do not use when...' condition.

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 safety is covered. The description adds genuine domain behavior beyond the annotations: that a building keeps the period plate it was completed in for life, plus the concrete Period 9 / January 2024 edge case. It does not discuss pagination or response shape, but for a read-only lookup this is solid added context.

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 core definition at the start, and the trailing sentences on period-plate permanence and the Feb 2024 example earn their place by clarifying a real ambiguity. It runs slightly long, but nothing is 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?

An output schema exists, so return-value shape need not be explained. For a read-only table lookup with well-covered parameters, the description covers what the tool returns (the whole table plus the active period) and the key domain rule; completeness is high, with only minor gaps around alternative-tool routing.

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 date, lang and compact are already fully documented in the schema. The description only implies the date parameter via 'which period is in force on a given date' and adds no syntax or format detail 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?

States a specific verb (list) and resource (the nine twenty-year San Yuan periods / 180-year cycle table), plus what each row contains (ruling star, five phase, palace, Li Chun date) and that it resolves the period in force for a date. This cleanly distinguishes it from the flying-stars, kua, bagua and afflictions 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?

Gives clear domain context for when it matters ('this is the table that decides which natal chart a property gets') and supports the date-resolution use case. It does not explicitly name an alternative tool or state when-not-to-use, so it stops short of a full routing guide.

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, and the description adds meaningful behavioral detail: sectors are returned ordered best-to-worst, each with a composed reading, plus a ranking that decides which affliction to accept. It also clarifies that a Kua may be supplied or derived, adding context without contradicting 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 information-dense and each sentence earns its place: the core purpose, the ordered output shape, and the derivation/use-case context. The main action is front-loaded before the star-name details.

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?

Together with a rich input schema and output schema, the description gives an agent enough context to select and invoke the tool correctly: it explains the output substance, input modes, and intended applications. It does not repeat parameter constraints like the mutual-exclusion of kua vs date+gender, but those are already explicitly covered in the schema.

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 all parameter meaning. The description only summarizes the Kua-or-birth-date/gender choice already described in the schema and adds no new parameter-level semantics, matching the baseline of 3.

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: 'Build the full Eight Mansions (Ba Zhai) map for a person,' then enumerates the four favorable and four unfavorable stars. This clearly distinguishes it from sibling tools like flying stars, bagua, or Kua-number-only 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 explicitly names target use cases: 'Built for bed and desk placement tools, room-by-room reports and floor plan overlays.' It does not name sibling alternatives or give an explicit when-not-to-use condition, so it stops short of full usage 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 declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: it returns all nine palaces, the period/mountain/water stars, named formations, a composed reading, and the classical verdict. This gives the agent a strong picture of what the tool produces beyond the structured 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 three sentences with no wasted words: it states the operation, summarizes the rich output, and covers accepted facing inputs plus intended use cases. Every sentence earns its place and the core action is front-loaded.

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 input schema, output schema, and safety annotations, the description is complete enough for an agent to select and invoke this tool correctly. It covers inputs, output meaning, domain context, and target use cases; the either/or facing/facingDegrees requirement is already fully documented in the parameter descriptions.

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 applies and the input schema already documents period, facing, facingDegrees, compact, and lang. The description adds useful domain context about mountain stars governing health/relationships and water stars governing wealth, but it does not substantially clarify parameter mechanics 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 specific verb and resource: 'Cast the Xuan Kong flying star natal chart for a building' from construction period and facing direction. It clearly distinguishes this natal-chart tool from the annual and monthly flying star siblings by emphasizing construction period, facing, and the nine-palace natal output.

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 is appropriate: natal chart calculation for a building, intended for property analysis tools, floor plan overlays, and consultation software. It does not explicitly name sibling tools as alternatives or state when not to use it, so it stops short of full routing 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, so the safety profile is covered. The description adds valuable behavioral context: the boundary being 'echoed back' and the edge-case handling of early February birthdays (placed in previous year). It also clarifies that date resolution is at day start, with the boundary day falling in the outgoing year. This goes beyond annotations and provides meaningful behavioral detail for an API with no side effects.

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, front-loaded with the core purpose. The first sentence states the action and outputs, and the second explains the key behavioral nuance (Li Chun resolution) and use cases. It is concise and well-structured, with no fluff. It could be slightly more concise by dropping 'personalised' duplication, but it's well within acceptable limits.

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's moderate complexity (5 parameters, 3 enums, output schema present), the description is sufficiently complete. It doesn't need to explain return values because an output schema exists. It covers why parameters like date and yearBoundary have edge cases, and mentions the boundary echo, which is a subtle behavior. Combined with the detailed schema, an agent has enough information to call this tool correctly. The only minor gap is that it doesn't explicitly state how the compact format works, but that's a schema concern, not a description 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%, with detailed parameter descriptions for each field (e.g., date format, gender affecting formula, yearBoundary differences). The description adds context on the date parameter by explaining why only the Chinese year matters and highlighting the boundary edge case, which is helpful. However, it doesn't add semantics for 'lang', 'compact', or 'yearBoundary' beyond what the schema already states. The description focuses on the date parameter's significance, providing slight added value, but generally the schema handles most of the load, so a 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 the verb 'Calculate' and the resource 'Kua number' (also known as Ming Gua or life gua). It lists specific outputs (number, life group, trigram, compass sectors) and elaborates on the Chinese year resolution (Li Chun boundary), which distinguishes it from any calendar-year-based tool. This differentiates it from siblings like get_feng_shui_kua_number (which is likely a getter for a list or a different endpoint) and other calculation 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 conveys clear use cases: 'Built for room and desk placement features, personalised feng shui reports, and any product that needs a favourable direction per person.' While it doesn't explicitly mention when NOT to use it or reference sibling alternatives, the distinct purpose and mention of Li Chun default (contrasting with lunar-new-year) give context for typical usage. It lacks explicit exclusion of scenarios like when only a zodiac year is needed.

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