Deterministic calendars, seasons, moon phases, retrogrades, and symbolic systems as stable JSON for AI agents via MCP. Gregorian dates 1900–2100; same date → same bytes.
Scored across 8 tools
Most tools are cleanly separated by input type and domain (date vs name vs two-person vs baseball), and the descriptions include explicit NOT exclusions that help an agent avoid misselection. The only real ambiguity is among get_age_plate, get_age_spread, and get_long_range, which all concern age-based boards but require different inputs and return different structures.
All eight tools use the uniform get_ prefix with lowercase snake_case resource names, creating a predictable read-only query pattern. The noun specificity varies, but no naming convention is mixed or inconsistent.
Eight tools is squarely in the ideal range for a focused read-only server. Each tool addresses a distinct query family: date, name, compatibility, age boards, and baseball-derived numerology.
The date, name, compatibility, age, and baseball analytics surfaces each have core query tools with no obvious dead ends. Minor gaps remain, such as no direct name-to-name compatibility tool and no batch retrieval of all 90 long-range ages, but agents can work around these via multiple calls.
USE for one Magian Grand Solar Age board by age_no (0..89; larger values wrap via mod 90). No birth date / no PII. NOT Long Range Journey; NOT get_age_spread person slice. RETURNS exactly 52 seats: card ref + age_spread_pos + planet_row + planet_col + is_fixed_card. Fixed seats: J hearts@11, 8 clubs@21, K spades@52.
| Name | Required | Description | Default |
|---|---|---|---|
| age_no | Yes | Magian age board index (0..89 preferred; wraps via f_age_mod90) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the existing readOnlyHint/idempotentHint annotations, the description reveals the mod-90 wrapping behavior, guarantees exactly 52 seats, lists the returned fields, and even furnishes the fixed seat positions. It also discloses that no birth date or PII is involved, giving the agent a precise behavioral contract.
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 text is front-loaded with the operation and resource, and each subsequent clause adds a distinct fact: no PII, exclusions, return shape, fixed seats. There is no filler or repeated content.
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 furnishes the essential return contract, field names, and fixed-seat detail. It omits explicit handling for negative age_no, but that is a minor gap for a one-input read-only getter; this is still highly 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?
The input schema already documents `age_no` with its range and wrapping behavior in 100% coverage. The description repeats the same 0..89 and mod-90 constraint rather than adding genuinely new meaning; it does not explain, for example, what happens with negative `age_no` values.
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 action ('USE for one Magian Grand Solar Age board') and the resource keyed by `age_no`, and it enumerates exactly what is returned (a 52-seat board with card ref, position, planet coordinates, and fixed-card flag). It also distinguishes itself from get_age_spread and 'Long Range Journey', so the purpose is 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?
It gives an explicit when-to-use ('for one Magian Grand Solar Age board by age_no') plus two explicit exclusions ('NOT Long Range Journey; NOT get_age_spread person slice'). An agent can route to this tool or away from it without opening any schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE for one person's Magian Age Spread board seat: birth_date + as_of_date (completed civil years; no wall clock). NOT the 90-year Long Range Journey theme card; NOT get_date sky/calendars; NOT two-person scoring. RETURNS compact cosmic birth card + age_spread {age_civil, age_no (mod 90), age_aliases, age_spread_pos, planet_row, planet_col, is_fixed_card}. Feb-29 follows Postgres age(). Error as_of_before_birth when as_of_date < birth_date.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | As-of civil date YYYY-MM-DD (pass host today when asking current age board) | |
| birth_date | Yes | Civil birth date YYYY-MM-DD (month/day resolves Cosmic birth card) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, the description discloses the return object ('cosmic birth card + age_spread {age_civil, age_no, age_aliases, ...}'), date semantics ('completed civil years; no wall clock'), the leap-year edge case ('Feb-29 follows Postgres age()'), and the validation error ('as_of_before_birth when as_of_date < birth_date'). These are all behavior details the annotations alone do not 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?
The description is front-loaded with the core use case, followed by focused exclusions, then the return shape and edge-case handling. Every clause adds information and there is no filler or redundant restatement of what the schema already contains.
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 two-parameter, read-only, idempotent tool with no output schema, the description is materially complete: it specifies the output fields, date semantics, leap-year behavior, error condition, and sibling disambiguation. An agent can correctly invoke the tool without additional inference.
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 is 100% covered with meaningful descriptions, so the baseline is 3. The description adds further semantic value: 'completed civil years', 'no wall clock', and the Feb-29 handling clarify how birth_date and as_of_date should be interpreted when computing age.
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?
Description starts with a specific verb-plus-resource: 'USE for one person's Magian Age Spread board seat' and lists the exact inputs. It explicitly differentiates from sibling tools by naming what it is NOT (90-year Long Range Journey theme, get_date sky/calendars, two-person scoring), so an agent can resolve 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?
The description gives a clear when-to-use target ('one person's Magian Age Spread seat') and explicit when-not-to-use exclusions: not the 90-year Long Range Journey card, not get_date sky/calendars, and not two-person scoring. This is direct selection guidance against the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE when comparing exactly two people by Gregorian date. NOT for one date (moon/season/Rx/weekday/leap year/day_ruler → get_date) or names → get_name. Requires date_a and date_b. RETURNS scored dyad: cosmic_card_a/b (each side is full get_date shape incl. tarot_majors.greer/tarot_school, karma, planetary_spread; Cosmic card = birth = life = sun via also_called; planetary_spread and retrogrades_active planets include planet_type/symbol/emoji + names{} 10 cultures; each planetary_spread slot carries spread_pos 1-14 — sort by spread_pos for canonical Life-spread order), connections, overall_score, Chinese zodiac + true sidereal aspects, element harmony, life paths. temporal_context.date_a/b = {band, payload_scope} (full|extended|out_of_range × full|cosmic_card_only; 1900-2100 focus).
| Name | Required | Description | Default |
|---|---|---|---|
| date_a | Yes | Person A date YYYY-MM-DD (exactly two people; not a roster) | |
| date_b | Yes | Person B date YYYY-MM-DD (exactly two people; not a roster) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false; the description goes well beyond this by detailing the full return shape (cosmic_card_a/b, connections, overall_score, temporal_context), clarifying term equivalences ('Cosmic card = birth = life = sun via also_called'), and even providing ordering guidance for spread_pos. There is 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?
The description is front-loaded with usage conditions, followed by required parameters and a returns section. It is dense but organized, with only minor over-packaging such as nested parentheticals and comma-heavy enumerations. Every sentence contributes value, especially given the lack of an output schema, but the complexity prevents a perfect conciseness score.
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 must fully explain return values, and it does: cosmic_card_a/b with get_date shape details, cultural names, planetary spread positions, temporal_context bands, and integration with Chinese zodiac and life paths. It also covers date format, required parameters, and the exact two-date scope, making the tool callable without external documentation.
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% description coverage, with each parameter clearly described as 'Person A date' and 'Person B date' in YYYY-MM-DD format. The description only reinforces the 'exactly two people, not a roster' constraint already present in the schema, adding no new parameter-specific meaning. 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 leads with a specific verb+resource: 'comparing exactly two people by Gregorian date.' It explicitly distinguishes itself from siblings with 'NOT for one date ... → get_date' and 'names → get_name,' making the tool's scope immediately clear. The title 'Compatibility (two dates)' reinforces this.
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 explicit when-to-use and when-not-to-use guidance, naming sibling tools and their exact triggering cases. It also states the required parameters ('Requires date_a and date_b'), leaving no ambiguity about invocation conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIMARY single-date tool. USE for any one Gregorian date when the ask needs moon phase (incl. blue/blood/supermoon/micromoon flags, Earth-Moon distance, phase_gmt, prev/next blue or blood dates), season/equinox anchors, classical retrogrades (retrogrades_active phase=retrograde), calendars, lunar year, Cosmic card (same card as life/sun — cosmic.also_called + planetary_spread.sun), karmic source/spirit, 14 planetary Life-spread cards, weekday or leap year (calendar_meta.weekday / is_leap_year), day_ruler (weekday planetary ruler Roman/Greek/Norse), or full date identity. NOT for two-person scoring → get_compatibility; name text → get_name. RETURNS cosmic block (incl. karma + planetary_spread) + tarot_majors (greer + tarot_school) + day_ruler (full+extended) + temporal blocks (moon_phase, season, retrogrades_active, calendar_meta, …). planetary_spread and retrogrades_active planets include planet_type/symbol/emoji + names{} (greek,norse,celtic,egyptian,sumerian,babylonian,mesopotamian,arabic,sanskrit,chinese). Each planetary_spread slot carries spread_pos (1-14 canonical Life-spread order; midheaven=13, phoenix=14 — sort by spread_pos; jsonb object keys are unordered). temporal_context={band, payload_scope} (band full|extended|out_of_range; payload_scope full|cosmic_card_only). Out-of-range responses set cosmic_card_available.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Single query date YYYY-MM-DD (any Gregorian date — sky, calendars, weekday, leap year, day_ruler, Cosmic card) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent behavior, so the bar is lower, but the description adds significant behavioral context: response structure, out-of-range behavior (temporal_context band and payload_scope), and a caveat about unordered jsonb object keys requiring sorting by spread_pos. This goes well 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 and front-loaded with the primary use case and sibling exclusions before return details. Some listing could be trimmed or structured, but every sentence contributes necessary guidance, and no content is wasted for the complexity involved.
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-parameter tool with no output schema, the description is remarkably complete: it enumerates the use cases, the returned blocks, field details, ordering caveats, and out-of-range behavior. An agent has enough context to invoke the tool correctly and interpret its results.
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 date parameter fully, including format and scope. The description merely restates that it accepts any Gregorian date, adding no new semantic details 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?
Description states a specific verb and resource: get the full identity of any single Gregorian date. It explicitly distinguishes itself from siblings by saying it is NOT for two-person scoring (use get_compatibility) or name text (use get_name), leaving no ambiguity.
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 a clear, explicit when-to-use list covering specific needs like moon phase, retrogrades, calendars, weekday, and more. It also names the exact alternative tools and the conditions that route elsewhere, which is model guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE for one person's 90-year Long Range Journey theme card: birth_date + as_of_date (completed civil years; no wall clock). NOT Magian Age Spread board (get_age_spread / get_age_plate); NOT get_date sky/calendars. RETURNS compact cosmic birth card + long_range {age_civil, age_no (mod 90), age_aliases, theme_card, spread_offset, planetary_period}. One theme card only — never 90 ages. Feb-29 follows Postgres age(). Error as_of_before_birth when as_of_date < birth_date.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of_date | Yes | As-of civil date YYYY-MM-DD (pass host today when asking current journey year) | |
| birth_date | Yes | Civil birth date YYYY-MM-DD (month/day resolves Cosmic birth card) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the output structure (compact birth card plus long_range with specific fields), the cardinality (one theme card only), the edge-case handling (Feb-29 follows Postgres age(), error if as_of_date < birth_date). Annotations (readOnly, idempotent, non-destructive) align with the stated behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, covering purpose, usage, behavior, and edge cases in a few sentences. It avoids fluff and focuses on essential information, making it efficient for an agent to parse.
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 lack of an output schema, the description compensates by listing the output fields and their names. It also mentions the specific error condition. All necessary contextual details for using the tool correctly are present.
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 descriptions for both parameters are clear and meaningful: birth_date is described as 'Civil birth date YYYY-MM-DD' and as_of_date as 'As-of civil date YYYY-MM-DD'. The tool description adds context (e.g., birth_date resolves Cosmic birth card, as_of_date used for current journey year), and schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: computing a 90-year Long Range Journey theme card from birth_date and as_of_date. It explicitly distinguishes from sibling tools like get_age_spread and get_date, ensuring no ambiguity.
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 explicitly states when to use the tool ('USE for one person's 90-year Long Range Journey theme card') and what not to use it for (not for age spread/plate or date/sky/calendar). This gives clear guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE for person or word name text only (gematria → cosmic cards + Expression / Soul Urge / Personality). NOT for any date questions (weekday, leap year, moon, season, Rx, Cosmic card, day_ruler, Life Path) → get_date; two people → get_compatibility. RETURNS Francis Bacon cards, Latin cipher suite, periodic{} + periodic_set{}, numerology (expression/soul_urge/personality plus full-name karmic_lessons / hidden_passion / cornerstone / capstone / first_vowel / echoes and number lens polarity/planet/element/color), and per-word tarot/medicine/iching/chakra/lenormand/karma/planetary_spread. Free-text input guard (Del as a name is allowed; DEL FILE and SQL verbs are not).
| Name | Required | Description | Default |
|---|---|---|---|
| full_name | Yes | Person or word name to decode (whitespace-separated words; not a date) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and idempotent behavior; the description adds the 'free-text input guard' detail, which provides extra behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly verbose due to listing many output components, but it is well-structured with clear 'USE for', 'NOT for', and 'RETURNS' sections, front-loading the purpose.
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?
Despite lacking an output schema, the description lists the computed outputs and mentions the input guard, which gives the agent sufficient context to understand what to expect and any constraints.
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 fully describes the single parameter (full_name) with 100% coverage. The tool description does not add significant extra meaning beyond the schema's own description, so it stays at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function (computing gematria, cosmic cards, and numerology from names) and explicitly distinguishes it from sibling tools (get_date for date queries, get_compatibility for two people).
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 provides explicit when-to-use (person or word name) and when-not-to-use guidance (date questions, two people), directing the agent to the correct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE when a player's season HR# or K# aligns with calendar day-of-month, jersey number, or inning on baseball.plays. NOT for roster cardology → get_team_chemistry; cosmic day card → get_date. Requires retro_id. mode=season (default) | spotlight (tier<=1) | career_summary (aggregates only). lane=both (default) | hr | k. Optional game_dt filter, tier_max (0-4), limit (1-500). RETURNS summary + events[] with pattern labels (day=HR#, HR#=jersey, day=K#=jersey, etc.). Overlay get_date(game_dt) for MCP day-card narrative.
| Name | Required | Description | Default |
|---|---|---|---|
| lane | No | Home runs, strikeouts, or both (default both) | |
| mode | No | season (default) | spotlight | career_summary | |
| limit | No | Max event rows returned (default 100, max 500) | |
| game_dt | No | Optional single-game filter YYYY-MM-DD | |
| retro_id | Yes | Retrosheet player id e.g. ohtansh01, freef001 | |
| tier_max | No | Max pattern tier 0-4 (spotlight defaults to 1) | |
| season_yr | No | Required for season/spotlight modes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by stating it 'RETURNS summary + events[]' and mentioning mode/lane behavior (e.g., spotlight defaults to tier 1). While not covering every side-effect, the annotations cover the safety profile and the description enriches the expected behavior without contradiction.
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 information-dense, using shorthand like 'HR#' and 'K#' that is likely domain-standard. It avoids unnecessary words and front-loads the core trigger condition. Minor demerit for cryptic phrasing ('roster cardology') that might confuse a general agent, but overall it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, but the description partially compensates by specifying 'RETURNS summary + events[]' and listing example pattern labels (day=HR#, HR#=jersey). It also includes an example retro_id and mode/lane defaults. This is sufficient for a read-only tool, though a full output schema would improve completeness.
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 covers all 7 parameters with descriptions (100% coverage). The prose description repeats some parameter details (mode defaults, lane defaults, limit range) but adds no new semantic meaning beyond the schema. Since coverage is complete, a baseline of 3 is appropriate; no significant extra clarity is provided by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving play numerology when a player's season HR# or K# aligns with calendar day, jersey number, or inning. It also explicitly distinguishes from sibling tools ('NOT for roster cardology → get_team_chemistry; cosmic day card → get_date'), ensuring an agent can select it correctly 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 provides explicit usage triggers ('USE when...') and exclusions ('NOT for...'), along with mode/lane defaults and a cross-tool hint ('Overlay get_date(game_dt)'). This gives clear when-to-use and when-not-to-use guidance, fully satisfying the dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
USE for MLB team × season roster cardology (suit mix, anchor stacks, Chinese zodiac year-animal match on postseason scope). NOT for play-by-play HR/K numerology → get_plays_numerology; two-person dyads → get_compatibility; single date → get_date. Requires season_yr + team_code. scope=ws_champion (default) | postseason. RETURNS roster_size, suit_mix, anchor_stacks, season_animal; postseason adds year_animal_match_pct (CNY-aware birth animal). Apply: apply_mcp_baseball_linked.ps1.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | ws_champion (default) or postseason active roster | |
| gametype | No | Postseason round when scope=postseason (default worldseries) | |
| season_yr | Yes | MLB season year e.g. 2024 | |
| team_code | Yes | Retrosheet team code e.g. LAN, CHN, HOU | |
| include_pair_matrix | No | Reserved v2 — echoes pair_note when true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds some behavioral context (returns specific fields, conditional field for postseason, and mentions an 'Apply:' command), but does not go beyond that in terms of side effects, auth, or rate limits. Since annotations are present, a score of 3 is appropriate.
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 organized: purpose, exclusions, requirements, scope, returns, and application note. It packs a lot of information in a compact form without excessive verbosity. The 'Apply:' line is a bit cryptic but not redundant. Overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by listing the returned fields (roster_size, suit_mix, anchor_stacks, season_animal) and the conditional year_animal_match_pct. It also clarifies the default scope and gametype. Given no output schema is present, this is sufficient for a caller to understand what to expect.
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 a description for every parameter; the description adds little beyond the schema. It repeats that season_yr and team_code are required, and the schema already explains scope and gametype defaults. The description's mention of 'suit mix' and 'anchor stacks' refers to output concepts, not parameter meanings. 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 it retrieves MLB team × season roster cardology data including suit mix, anchor stacks, and Chinese zodiac year-animal match. It explicitly distinguishes from sibling tools by saying what it is NOT for (play-by-play numerology, dyads, single date) and points to the correct alternatives.
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 provides explicit when-to-use and when-not-to-use guidance, naming sibling tools (get_plays_numerology, get_compatibility, get_date) as alternatives. It also states required parameters (season_yr + team_code) and explains the two scope options (ws_champion default vs postseason) with gametype default.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_long_rangeget_age_plateget_age_spreadget_plays_numerologyget_team_chemistryget_compatibilityget_dateget_name
Add one secure layer between your agents and this server.