小道 Xiaodao

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

Annotations already declare read-only, idempotent, closed-world, so the bar is lower, yet the description still adds substantive behavior: historical time zone and true-solar day boundaries, 3-days-per-year luck calculation with yang/yin direction rules, pillar comparison against solar terms, and the 1801–2099 supported range. It stops short of describing error payloads or output shape, keeping it at a strong 4.

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

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

Front-loaded with purpose and outputs before diving into parameter mechanics, and nearly every clause carries operational information. Minor waste: the trailing bilingual restatement of the Gregorian range (公历日期范围…) duplicates the preceding English 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?

For a 13-parameter, nested-object, no-output-schema tool, the description covers time-zone handling, supported date range, boundary-resolution behavior, and which facts are returned. It does not sketch the response structure at all, which matters somewhat given there is no output schema, but the enumerated deliverables largely compensate.

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 85%, so baseline is 3, but the description adds meaning the schema does not: focusDate is evaluated at noon against the birth place, detailYears is capped at ten inclusive years and must fit the pre-luck/twelve-cycle timeline, and ranges follow Lichun-through-Xiaohan month boundaries. Calendar/leap-month and boundaryChoices semantics are largely left to 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?

Opens with a specific verb+resource ("Calculate a full Bazi chart using the Xiaodao engine") and enumerates the concrete outputs: four pillars, lunar date, auxiliary palaces, luck start/direction, twelve cycles, and focused period facts. That level of specificity clearly separates it from siblings like qimen_chart and true_solar_time.

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 real operating guidance: focusDate selects a noon local civil date, detailYears adds up to ten inclusive years, allDaysOfMonth expands the solar-term month, and repeated/nonexistent times return needs_input or are not calculated. It also sets expectations with "returns chart facts, not an interpretation." It does not explicitly route between this and qimen_chart, so not a 5.

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

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

Beyond the annotations, the description discloses substantial behavior: historical time zone and DST handling, longitude and equation of time, local true solar time expressed in Beijing time, the 23:00 day change, repeated and nonexistent local times, and the Gregorian date range. It also states that the tool returns chart facts without interpretation rules and describes language-dependent output behavior. The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, and the description is consistent with 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 front-loaded with purpose and then proceeds through parameters, time handling, and output behavior in a logical order. Most sentences carry necessary domain or invocation information, but the date range is repeated in both English and Chinese, and the single dense paragraph could be more scannable. The verbosity is largely justified by the tool's complexity, but there is minor 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?

For a complex chart-calculation tool with no output schema, the description covers the input constraints, time-zone and DST semantics, dependency requirements, date range, and what the return contains: nine-palace chart facts and optional birth-year stem locations without interpretation rules. It also explains language effects on chart text and glossary fields. Nothing essential for correct invocation appears missing.

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

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

Schema coverage is already high at 83%, but the description adds important meaning: date/time are local Gregorian wall-clock values at placeId, placeId omission has a specific default, daylightSaving is only needed for ambiguous repeated times, and birthYearPillar must be a full sexagenary pillar from bazi_chart rather than a numeric year or single stem. It also explains that language=en adds English conventions and a field glossary. These details go well beyond the schema field 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?

The description states a specific verb and resource: calculate an hour-based Qimen chart using the chai bu method and rotating plate only. It also distinguishes related dependencies by naming search_birth_place for placeId and bazi_chart for birthYearPillar, and notes that year/month pillars can differ from Bazi. This lets an agent identify the tool without opening the 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 description gives clear operational guidance: placeId comes from search_birth_place, omitting it uses the configured reference place, and birthYearPillar must be obtained from bazi_chart first. It also states that repeated wall-clock times require an explicit daylightSaving choice and nonexistent times are not calculated. It does not explicitly contrast this tool with true_solar_time or bazi_chart as alternatives for the same user intent, so it falls short of full when/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 cover the safety profile (readOnly, idempotent, closed-world), so the description's added value is the warning that coordinates and historical time zone rules — not today's UTC offset — drive downstream calculations. That is a genuinely useful behavioral nuance. It omits result-count limits and whether matches are fuzzy, which for a catalogue search an agent would want 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?

Two tight sentences with zero filler; the resource and returned fields come first, the downstream-consumption caveat second. Every clause earns its place.

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

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

With no output schema, the description does well to enumerate the returned fields, and it flags the historical-timezone pitfall. But for a search tool it says nothing about result volume, ordering, or how to disambiguate multiple hits, leaving real gaps for the intended resolve-a-birth-place workflow.

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 0%, so the description must carry the parameter burden and it does not: nothing explains how 'query' is matched (exact, prefix, fuzzy) or that 'language' selects the returned name script, even though the zh-CN/en enum and default go unmentioned. The phrase 'Chinese and English names' is the only faint hint at the language parameter.

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?

Opens with a specific verb and resource ('Search Xiaodao's place catalogue') and enumerates exactly what a result contains (IDs, Chinese/English names, countries, first-level administrative areas). It implicitly separates itself from the sibling chart/calculation tools by naming them as downstream consumers, though it never states the contrast explicitly.

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?

'Select the intended place; its stored coordinates and historical time zone rules are used by the calculation tools' establishes the resolve-then-calculate workflow and gives the agent a clear selection instruction. There is no explicit when-not guidance (e.g. what to do when multiple matches return) and no direct naming of an alternative tool.

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

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

Annotations only cover the read-only/idempotent safety profile, and the description adds substantial behavior beyond that: the exact conversion algorithm, hemisphere handling of the equation of time, defaults for earlyLateZi, rejection of nonexistent local times, the needs_input fallback, and the supported date window. That is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the primary action and the correction pipeline, and most sentences carry distinct constraints (ambiguity, defaults, date range, return contents). The bilingual restatement of the date range and the slightly cryptic 'Longitude and birth date are unchanged' sentence are minor waste.

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 9 parameters, a nested object and no output schema, the description does its job by summarizing returns (minute-resolution solar time, historical zone/offset, DST and Zi-hour policy) and the needs_input path. The gap is that boundaryChoices (DAY/HOUR/TERM) and when a boundary situation arises are never explained, so an agent facing that response has little to act on.

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

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

Schema coverage is already 89%, so the baseline is 3; the description still adds meaning by tying repeated clock times to an explicit occurrence (daylightSaving), explaining that earlyLateZi defaults to false with a 23:00 day change, and noting that missing boundary choices produce needs_input. It leaves the DAY/HOUR/TERM boundary concepts themselves unexplained, which keeps it below 5.

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: convert historical local wall-clock time to true solar time, and enumerates the correction chain (DST removal, longitude correction, equation of time). It also carves out its own scope against siblings by declaring 'No pillars or lunar date are returned', which separates it from bazi_chart/qimen_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?

Gives clear operational context: repeated clock times need an explicit occurrence, nonexistent times are rejected, missing boundary choices return needs_input, and the Gregorian range is 1801-2099. It does not explicitly name an alternative tool or say 'use bazi_chart instead when you also need pillars', 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.