FateTell

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description reinforces this with "Deterministic; nothing stored." It also adds non-obvious behavioral detail not in the annotations, namely that southern-hemisphere births use cross-region rules. It stops short of describing output size or notes/assumption flags, which the output schema presumably covers.

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 sentences organized as purpose, positive trigger with example, and exclusion list, with the deterministic/no-storage note last. Every clause carries scope information; nothing is redundant with the name or title.

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 computational tool with a rich nested schema and an output schema, the description supplies what structured fields cannot: scope, exclusions, example phrasing, and behavioral guarantees. Return-format detail is correctly omitted because an output schema exists.

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

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

Schema description coverage is 100% and the nested birth object is documented in detail (timezone format, lunar conversion, leap month, true solar time, hemisphere inference), so the schema does the heavy lifting. The description adds only one semantic hint beyond that — the southern-hemisphere cross-region rule — which is a marginal contribution, making the baseline 3 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 leads with a specific verb and resource ("Compute a BaZi chart from birth data") and enumerates exactly what the chart contains (pillars, Ten Gods, hidden stems, Na Yin, Day Master, luck pillars, palaces, today's pillars). It also names the sibling tools it is not for, so the agent can distinguish it 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?

It gives an explicit positive trigger with a sample utterance ("What is my BaZi? Born 1990-05-17 08:30 in Taipei") and an explicit exclusion list mapping each rejected case to the sibling that handles it (get_saved_chart, get_bazi_judgment, get_almanac). Alternatives and when-not conditions are both stated.

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

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

Goes well past the annotations: annotations only say it is a non-idempotent, non-destructive write. The description adds that it returns chart_id, that time zone and hemisphere are derived from birthplace, that a missing birth time marks the chart hour-uncertain, that consent gates the write entirely, and that new charts carry no pillars until read back.

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 what is saved and what is returned, then usage, then exclusions, then the follow-up read. No sentence is redundant and the exclusion sentence is compactly parallel in structure.

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 nine-parameter write tool with a full-coverage schema, an output schema, and safety annotations, nothing material is left unsaid: return value, consent gate, derived fields, and the post-save read path are all covered.

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 still adds cross-parameter meaning the schema does not, namely the birthplace-to-timezone/hemisphere derivation and the subject/consent coupling. It does not, however, restate the enum semantics such as gender driving luck-pillar direction, which remain schema-only.

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 ('Save a new chart') plus the inputs it is built from, and immediately distinguishes itself from three siblings by name (cast_bazi_chart, get_saved_chart, list_saved_charts). An agent can route without opening any schema.

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

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

Gives an explicit trigger ('when the user explicitly asks to save a chart'), a pre-check ('check list_saved_charts first to avoid duplicates'), a hard precondition (consent_attested for another person, otherwise nothing is saved or cast), and three named exclusions with the alternative for each.

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 readOnly, idempotent, closed-world and non-destructive, so the bar is lower. The description adds genuinely new behavioral facts: the operation is deterministic, involves no personal data, and the hemisphere flag only changes which month pillar leads the text summary while the structured result always contains both. It does not discuss pagination or limits on the response size for 31 days, which is why it falls short of a 5.

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 verb and payload, then usage examples, then exclusions, then behavioral notes. Every sentence carries routing or behavioral information; there is no filler or repetition.

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 values need not be explained. Given a zero-required-parameter, four-optional-parameter read tool, the description supplies scope, routing to four sibling alternatives, and the hemisphere nuance — everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so days, timezone, hemisphere and start_date are already fully documented, giving a baseline of 3. The description echoes the 1–31 day range and clarifies that the month pillar is produced for both hemispheres, but this largely restates what the schema's hemisphere description already says rather than adding new syntax or format guidance.

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 Chinese almanac for one to 31 consecutive days") and enumerates the payload: Gregorian and lunar dates, solar terms, year/month/day pillars. It explicitly excludes Western astrology, so an agent can distinguish it from chart-oriented siblings without opening any schema.

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

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

Gives concrete example questions that should route here ("What is today's day pillar?", "When is the next solar term?") plus negative routing with named alternatives: get_saved_chart or cast_bazi_chart for a chart, get_daily_fortune or get_chart_calendar for a saved chart's days. Both the when and the when-not are explicit.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that the call is deterministic, stores nothing, and requires an active FateTell membership — an auth prerequisite the annotations cannot express. The rule-set version pin is also useful behavioral context. It does not cover rate limits or failure modes, which keeps it just short of a 5.

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, front-loaded with what is returned, then when to use, then what it is not, then operational constraints. Every sentence carries distinct information with no restatement of the name or title.

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 two-parameter, nested-schema tool with an output schema, the description covers the pieces the structured fields cannot: the auth requirement, the no-storage determinism guarantee, the versioned rule set, and the sibling routing. Return-value shape is correctly left to the output 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%, including nested birth fields, so the schema carries the semantics. The description only restates the either/or relationship between birth and chart_id, which the schema already declares on both properties; it adds no format or edge-case detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb and resource: returns the Day Master verdict (strong, weak, follow-strong, follow-weak) plus ranked favorable/unfavorable/neutral elements under rule set v1.0. It explicitly separates itself from cast_bazi_chart (pillars) and get_saved_chart (which already embeds this judgment), so an agent can choose without opening a schema.

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

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

Gives both branches of when to call: pass birth for an unsaved birth, or pass chart_id for a saved chart whose judgment get_saved_chart reported as not yet available. It also names an explicit exclusion (not a substitute for the chart; use cast_bazi_chart for pillars), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description adds value on top: it discloses the ceiling per mode (up to 31 days, up to 12 months), that pillars are hemisphere-adjusted for the chart, and that only stems, branches and relations come back with interpretation deliberately left to the caller. It does not discuss error behavior for an invalid chart_id or what happens when count exceeds the maximum, which keeps it short of a 5.

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 return shape, then usage, then exclusions — a sensible order with no filler sentences. Minor redundancy: the "up to 31" / "up to 12" limits simply restate the count parameter's schema description.

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?

Return values are covered by the output schema, and the description still signals the shape of the payload and that no interpretation is included. With alternatives named, prerequisites stated, and per-mode limits given, an agent has everything needed to select and call this 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% and each parameter already carries a description (count ranges and defaults, chart_id provenance including "self", start_date format and default time zone, granularity enum). The description only echoes the count ceilings and the chart_id requirement, so it adds little semantic meaning beyond the schema; 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?

Names a specific verb and resource ("Return a saved chart's view of upcoming dates") and immediately bounds the output shape per granularity (day: year/month/day pillars, natal relations, month clash, solar terms; month: month pillar and natal relations). An agent can tell this apart from get_daily_fortune, get_almanac and get_saved_chart without opening any schema.

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

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

Explicit when-to-use ("Use to pick a date or see upcoming days or months for a saved chart") and explicit when-not with named alternatives for both exclusions: get_daily_fortune for one day's energy/do-avoid, get_almanac for dates without a chart. It also states the prerequisite that a chart_id is required and that birth data cannot be passed, which is the main failure mode.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results contain no generated text and clarifies the default date behavior in the account's time zone, which is useful behavioral context beyond 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 dense but well organized: it states the return contents first, gives the usage scenario and parameters, then lists exclusions. Every sentence contributes useful selection or invocation information.

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

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

Given the three parameters, full schema coverage, output schema, and read-only annotations, the description is complete enough for an agent to select and invoke it correctly. It covers scope, defaults, alternatives, and even notes the absence of generated text.

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 chart_id, date, and locale thoroughly. The description reinforces the required chart_id and the 'self' shortcut and mentions the optional date default, but adds little parameter meaning beyond the schema.

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

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

The description uses a specific verb and resource ('Return a saved chart's daily fortune for one date') and enumerates the outputs: energy level, stems-and-branches relations, do/avoid items, day pillar, year/month pillars, and month clash. It is clearly distinguishable from siblings such as get_almanac and get_chart_calendar.

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 states the use case with an example question ('How is today for me?') and explicitly routes agents away to get_almanac for day pillars without a chart and get_chart_calendar for multiple days. It also rules out births that are not saved.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint false. The description adds that the tool returns permissions granted to this client and remaining quota per tool, which are behavioral details not covered by annotations. However, the output schema exists and likely details the return fields, and 'Read-only' repeats the annotation without adding new information.

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: first lists returned fields, second gives usage conditions, third excludes chart tools and notes read-only. The description is front-loaded and every sentence contributes to correct invocation. Minor redundancy with the read-only annotation, but no wasted words.

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 simplicity (0 parameters) and the presence of an output schema, the description is complete enough. It covers purpose, when to use, when not to use, and behavioral context (permissions, quota). Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters, so the baseline score is 4 per the rules. The description adds no parameter information, which is appropriate 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?

States a specific verb 'Return' and resource 'connected FateTell account', enumerates the returned fields (masked email, sign-in method, interface language, time zone, membership status, permissions, remaining quota), and explicitly distinguishes from chart reading tools by naming list_saved_charts and get_saved_chart. An agent can identify its purpose from the description alone.

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 states when to use: user asks about connected account, membership status, remaining calls, or when a tool returned membership_required or rate_limited. Also states when not to use: 'Not for reading charts' and provides sibling alternatives. Complete 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: birthplace is deliberately omitted from the return, the current luck pillar is marked, and the agent is told never to recompute a saved chart with other tools. It does not discuss pagination, errors for unknown chart_id, or what 'stored' Day Master judgment implies about freshness, leaving some room.

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 return payload, then usage and exclusions — a sensible ordering with no filler sentences. The return enumeration is dense and long, but each item earns its place by telling the agent what it will and will not get (e.g. no birthplace).

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?

Even though an output schema exists and would excuse omitting return details, the description summarizes the payload, marks the current luck pillar, notes the missing birthplace, and pins down the boundary against cast_bazi_chart and against predictive use. Nothing an agent needs in order to call it correctly is absent.

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 all three parameters (locale, chart_id, include_today) are already documented, and the description largely restates the chart_id semantics rather than adding to them. It says nothing about locale or the include_today default at the description level, so it adds little 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 opening clause names a specific verb and resource ('Return one saved chart in full') and then enumerates exactly what is included — birth date/time/zone, pillars with Ten Gods, hidden stems, Na Yin, luck pillars, palaces, Day Master strength, today's pillars. It is clearly distinguishable from cast_bazi_chart, which computes a chart rather than retrieving a stored one.

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

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

Explicit when-to-use ('whenever the user asks about a saved chart or "my chart"'), explicit exclusion ('Not for births not saved (use cast_bazi_chart)'), an explicit prohibition against re-casting or re-judging with other tools, and an explicit scope limit ('Not for predicting events or years of accident, illness or death'). The id source ('chart_id comes from list_saved_charts, or "self"') is also spelled out.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds real value beyond them: the exact field set returned and the notable omission that "Birthplace and coordinates are never returned," which prevents an agent from promising location data. It does not discuss empty-result behavior or ordering, so it stops short of a 5.

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 ordered by importance: what it returns, when to use it first, then what it explicitly does not do. Every clause carries information an agent needs; nothing is padded or restated from the title.

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-argument, read-only list tool with a declared output schema and rich annotations, the description covers the remaining gaps: the field inventory, the deliberate absence of birthplace/coordinates, and the handoff of chart_id to four named consumers. Nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly describes no arguments and instead spends its words on downstream usage.

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 ("List the charts saved in the connected FateTell account") and immediately enumerates the returned fields (id, display name, gender, own-chart flag, hemisphere, rule version, computed status). It explicitly names what it is not (create_saved_chart, get_saved_chart), so an agent can distinguish it from all siblings without opening a schema.

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

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

Gives an explicit precedence rule ("Use first whenever the user refers to 'my chart'..."), states the downstream payoff (provides the chart_id that get_saved_chart, get_bazi_judgment, get_daily_fortune and get_chart_calendar need), and adds a negative instruction ("Do not ask for birth data when a saved chart may exist"). Exclusions for the two closest siblings are named with their alternatives.

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