Mesoamerican Astrology MCP Server by RoxyAPI

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

Annotations already mark the tool read-only and non-destructive, and the description adds meaningful behavioral detail: content is fixed per date, rolls over at midnight UTC, and is safe to cache for daily feeds or pre-fill an editorial calendar. It also discloses the output composition (day sign, coefficient, trecena, composed reading). 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 short sentences front-load the core output and date flexibility, then add caching behavior and use cases. Every sentence earns its place and there is no filler or 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?

Given the rich schema, the presence of an output schema, and the safety-oriented annotations, the description is complete enough for correct invocation and interpretation. It states what the reading contains, date rollover behavior, caching implications, and target integrations, leaving no essential 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?

The input schema already documents all three parameters at 100% coverage, including date format and proleptic Gregorian caveats, lang enum with fallback behavior, and compact shape. The description only echoes 'today or any date you name' without adding parameter-level meaning. Baseline 3 is appropriate because the schema carries the semantic weight.

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 names a concrete resource: the Tonalpohualli day sign, its coefficient, its trecena, and a composed reading for today or any named date. The 'daily' scoping and 'any date you name' clearly distinguish it from the sibling list/detail tools like aztec_day_signs or trecenas. An agent can tell what this tool returns 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 intended use contexts: daily energy widgets, Mexica day sign feeds, and chatbot answers about what today carries. It does not explicitly name sibling alternatives or state when not to use this tool, such as when a static reference list of day signs would be more appropriate. Thus it has clear context but no exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: results are returned in sequence order and each entry includes a machine id, Nahuatl name, meaning, world direction, and composed reading. It doesn't disclose pagination or language fallback behavior, but those are already documented in the schema.

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 dense, front-loaded sentences with no filler. The core behavior, ordering, and returned fields appear immediately, and the use-case sentence earns its place by clarifying when the tool is the right choice.

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 schema, output schema, and safety annotations, the description covers ordering, scope, returned fields, and intended use cases. There is nothing material missing for an agent to select and 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 description coverage is 100%, so the schema fully documents lang, limit, offset, and compact. The description adds no additional parameter-level meaning beyond mentioning the full set and returned fields, so the baseline of 3 is appropriate.

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

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

The description specifies a clear verb and resource: 'Retrieve all twenty tonalpohualli day signs in sequence order from Cipactli to Xochitl.' It also clarifies the data returned per entry and distinguishes itself from sibling tools by positioning this as the 'whole set in one call' endpoint.

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 usage context: it is built for Aztec sign pickers, Mexica calendar reference pages, and any app needing the complete set in one call. It does not explicitly name alternatives or exclusions, but the 'whole set in one call' phrasing implicitly routes users away from the per-id or Mayan sibling tools.

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 provide readOnlyHint=true and destructiveHint=false, so the description only adds that the result includes specific profile fields. It does not disclose any edge cases, error behavior, or authorization needs. With annotations covering safety, the description adds moderate value by outlining the return contents but no deeper behavioral 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?

The description is a single, well-structured sentence that front-loads the core action and content, then adds use cases. Every clause earns its place with no redundancy or fluff.

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-id lookup with an output schema present, the description adequately conveys the purpose and typical usage. It does not explicitly contrast with the plural list endpoint or the trecenas endpoints, but the name and phrasing are sufficiently clear. Minor gaps include no mention of language behavior (though schema covers it) and no explicit read-only indication (annotations cover it).

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

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

Schema description coverage is 100%, so the schema already documents id (with enum and case-insensitivity), lang (with BCP 47 and fallback behavior), and compact (with token savings). The description adds no parameter-specific meaning beyond what the schema provides, so the baseline score 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 a specific verb ('Retrieve') and resource ('the full profile of one tonalpohualli day sign'), and enumerates the content (Nahuatl name, meaning, direction, keynote, guidance). It also implies singular scope, distinguishing it from the plural sibling get_mesoamerican_astrology_aztec_day_signs without needing to open 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 mentions 'single Mexica sign' and lists concrete use cases (detail pages, day sign cards, chatbot answers), which implies when to use it. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent despite the clear singular/plural naming convention.

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 safe-read nature is covered. The description adds useful behavioral context by specifying what each returned entry contains: 'the period number, the day sign it opens on and a composed reading of what the period carries.' This goes beyond the structured data without contradicting it.

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 appropriately short and front-loaded with the action and resource. The first sentence states exactly what the tool does, the second describes the return shape, and the third gives intended audience. The final sentence is useful but slightly promotional, adding mild non-essential 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?

Given the output schema exists and the annotations cover safety, the description provides enough context for an agent to invoke the tool correctly. It explains what trecenas are, what the response entries contain, and the intended use context. It does not mention pagination or language fallback, but those are fully covered by 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 all four parameters are already fully documented. The description does not add parameter-level meaning beyond the schema, which matches the baseline expectation. It adds no extra detail about language coverage, pagination, or compact mode, but those are already 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?

The description uses a specific verb ('Retrieve all twenty trecenas') and a clear resource with domain context ('the thirteen day periods the 260 day tonalpohualli divides into'). It clearly describes a list-all operation, but it does not explicitly distinguish itself from the sibling tools such as get_mesoamerican_astrology_mayan_trecenas or the single-trecena variant, so it stops short of full sibling differentiation.

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

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

The description gives clear context for when to use the tool: it is 'Built for Aztec calendar apps, energy period trackers and content planners that work in thirteen day blocks.' It also makes clear this returns all twenty trecenas, implying use when a full list is needed. However, it does not explicitly name alternatives or state when-not-to-use conditions, so it lacks explicit exclusion 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 establish readOnlyHint and non-destructive safety, so the description only needs to add context. It adds that the result includes the opening day sign and a composed reading, but it does not disclose behavior such as invalid-number handling or the nature of the composed reading; acceptable but not rich.

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 sentences, no filler, with the operational core ('retrieve one trecena by number') first and the audience/use case 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 a full input schema, an output schema, and read-only annotations, nothing essential is missing. The description supplies the use case and resource scope needed to select the tool correctly, and all behaviors are sufficiently covered by the structured fields.

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

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

Schema description coverage is 100%, so the schema carries the meaning of number, lang, and compact. The description's 'by number' and 'twenty' reinforce the number parameter but add no detail beyond what the input 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 uses a specific verb ('Retrieve') plus a precise resource ('one of the twenty tonalpohualli trecenas by number') and states what the caller gets: the opening day sign and a composed reading of the period. This is clearly distinct from the plural list sibling and from the Aztec daily tool.

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?

'Built for period detail pages and for apps that show which thirteen day block a date falls in' gives clear intended contexts. It does not explicitly name an alternative tool or state when not to use it, so it stops 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond that: the response is deterministic ('fixed') for months that have begun, and the endpoint aggregates month-wide data in one call, avoiding per-day requests.

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: the first states exactly what the tool returns, the second explains the efficiency benefit, and the third identifies the audience. Key details are front-loaded and 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?

Given that all five optional parameters are fully documented in the schema, annotations cover safety, and an output schema exists, the description completes the picture by explaining the data content, the use case, and why the endpoint exists. Nothing necessary for correct invocation 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%, and every parameter already has a detailed description, including defaults, ranges, enums, and behavior. The tool description itself does not need to repeat parameter semantics, so the baseline of 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?

The description states a precise verb-resource pair: a monthly Maya calendar grid covering every day of a civil month. It enumerates the included data fields (Tzolkin sign and coefficient, trecena, Haab date, Long Count), making the tool's scope unmistakable and distinguishing it from the daily and single-date sibling routes.

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 says one call fills a whole monthly grid 'that would otherwise take a request per day,' giving clear context for when to choose this over daily endpoints. It also names target use cases (calendar widgets, editorial planners, apps showing a month of Maya dates). It does not explicitly name sibling alternatives, but the guidance is sufficient for 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=falseependently. The description adds valuable behavioral context beyond those annotations: content is fixed per date, rolls over at midnight UTC, is cache-safe, and can be precomputed weeks ahead. This meaningfully helps an agent decide how to call and cache the tool.

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: the first states the core functionality, the second adds a critical caching/rollover behavior, and the third names the intended use cases. The description is front-loaded and 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?

Combined with a 100%-covered input schema, rich enum documentation, an output schema, and read-only annotations, the description leaves nothing essential unexplained. A caller can select the tool for a daily-reading use case)Skip knowing all parameters from the schema and expect deterministic, cacheable content.

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 schema already provides exhaustive detail on date, lang, compact, and correlation. The description indirectly touches date semantics ('for today or any date', 'midnight UTC') but adds no parameter-level information beyond what the input schema already documents.

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

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

The description clearly identifies the resource: 'the Tzolkin day sign, its coefficient and its trecena for today or for any date you name, with a composed reading.' It distinguishes itself from sibling list/reference tools by focusing on the daily energy reading rather than a catalog of signs, though it does not explicitly name any sibling.

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 clear context for when to use this tool with 'Built for daily energy widgets, nawal of the day feeds and chatbot answers about what today carries.' It also explains a strong practical property—content is fixed and cached safely, enabling editorial calendars—but it does not state when to prefer an alternative sibling 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 already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: sequence ordering, the full set of fields returned per entry, and the directionScheme-dependent direction and colour. This goes beyond the annotations without contradicting them.

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

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

Three purposeful sentences: the first states the core action, the second enumerates returned fields, and the third gives use cases. The field list is dense but informative, and no sentence is wasted.

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 safe-read annotations, the description is complete enough for an agent to select and invoke the tool correctly. It explains the tool's scope, return contents, ordering, and target use cases without needing to duplicate structured schema details.

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

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

Schema description coverage is 100% and every parameter has a detailed schema description. The tool description does not need to restate parameter semantics; it only lightly references the 'requested scheme' for directionScheme. Baseline 3 is appropriate because the schema carries the burden.

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: 'Retrieve all twenty Tzolkin day signs in sequence order from Imix to Ajaw.' It also distinguishes itself from the sibling mayan_day_signs_id tool by emphasizing the whole set in one call and positioning itself as the catalogue endpoint.

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 usage context: 'Built for nawal pickers, sign reference pages and any app that needs the whole set in one call.' It does not explicitly name alternatives or exclusions, but the whole-set framing implicitly routes agents away from the single-id sibling.

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 description does not need to repeat safety. It adds value by detailing the output contents (naming traditions, glosses, direction/colour, keynote, strengths/weaknesses, guidance) and mentions the scheme-dependent direction/colour, which goes beyond the annotation and helps the agent understand what to expect.

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 primary action and a precise list of contents. Every phrase earns its place, with no fluff or repetition. It is compact yet informative, ideal for an agent to quickly grasp the tool's 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?

For a single-sign profile tool with a rich output schema, the description covers the main purpose, the scope, and the key content. It does not explain the compact option or language fallback, but these are fully documented in the schema. The description is complete enough for an agent to invoke correctly without additional clarification.

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%, with each of the four parameters fully documented. The description only references the directionScheme parameter indirectly ('under the requested scheme'), which is also explained in the schema. Since the schema carries the full semantic load, the description adds no extra parameter detail beyond that, warranting the baseline score.

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 ('Retrieve') and resource ('full profile of one Tzolkin day sign') and enumerates the exact fields returned. It also names the intended use cases ('nawal detail pages, sign cards and chatbot answers') and the singular scope ('one... sign') which clearly differentiates it from the plural list tool get_mesoamerican_astrology_mayan_day_signs.

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 ('Built for nawal detail pages, sign cards and chatbot answers about a single Mayan sign') and implies it is for a single sign as opposed to the plural tool. It does not explicitly state when not to use it or name alternatives, but the singular focus and use cases are sufficient 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, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: each entry includes 'the machine id, both spellings of the name, the length, what the name means and a composed reading'. This gives the agent a good sense of the response shape 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 three sentences with zero filler. The first sentence defines scope, the second explains return content, and the third gives context for use. Every sentence earns its place, and the key information 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?

The tool has a full output schema, complete parameter descriptions in the schema, and annotations covering the safety profile. The description adds what is not otherwise available: the purpose, the exact set of periods, the return fields, and the intended use case. Nothing needed to select and 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?

Schema description coverage is 100%, so the input schema already documents all four parameters (lang, limit, offset, compact) with defaults, ranges, and behavior. The description adds no parameter-level semantics beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource: 'Retrieve all nineteen periods of the Haab', and adds exact structural detail (eighteen months of twenty days plus the five days of Wayebʼ). It clearly distinguishes this list endpoint from the compute-oriented siblings by framing it as for 'label a Haab date rather than only compute it'.

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

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

The description gives explicit use cases: 'calendar reference pages and for any app that has to label a Haab date'. It also implies contrast with computational endpoints ('rather than only compute it'), providing clear context. It stops short of naming sibling alternatives or stating when not to use it, so it loses one point.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no safety disclosure is needed. The description adds the return-payload scope (spellings, position, length, composed reading) but little behavioral context beyond that; it is a straightforward read operation.

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 sentences, no filler, with the primary action and returned data front-loaded. The second sentence adds concrete use-case context without repeating schema or annotation 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?

For a single-record read tool with full schema coverage, an output schema, and safety annotations, this description is complete. It tells the agent what the tool returns, when to use it, and where it fits in the 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 description coverage is 100%, with enums and clear descriptions for id, lang, and compact. The description does not need to add parameter-level guidance, and the baseline of 3 applies because the schema carries the semantic weight.

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 a specific verb ('Retrieve'), a precise resource ('one of the nineteen Haab periods by id'), and enumerates the notable returned fields. It clearly distinguishes this detail/ID tool from the sibling list tool, haab_months, by emphasizing single-record retrieval.

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

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

The description states concrete use cases: calendar detail pages and labelling a Haab date returned by a chart route. It does not explicitly name alternative sibling tools or list when-not-to-use conditions, but the intended context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds behavioral context by stating that it returns all twenty trecenas and what each entry contains. It also notes the composed reading aspect, which is useful beyond the structured schema. It does not cover pagination behavior, but the output schema and parameter documentation fill much of that gap.

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 tightly written sentences: the first states the resource, the second describes the return content, and the third gives usage context. There is no redundant language or 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?

With a rich output schema, fully documented parameters, and annotations covering safety, the description completes the picture by explaining the domain, the returned fields, and the intended use. Nothing an agent needs to select or invoke this list endpoint 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 coverage is 100%, so the parameters (lang, limit, offset, compact) are fully documented in the schema itself. The description does not add parameter-level meaning beyond what the input schema provides. A baseline score of 3 is appropriate because the schema carries the burden.

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 begins with 'Retrieve all twenty trecenas,' a specific verb and resource, and clarifies the domain with 'the thirteen day periods the 260 day Tzolkin divides into.' It also lists what each entry contains, making it easy to distinguish this list endpoint from siblings like get_mesoamerican_astrology_mayan_trecenas_number.

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 this tool fits: 'Built for calendar apps, energy period trackers and content planners that work in thirteen day blocks rather than in weeks.' It does not explicitly name alternatives or state when not to use it, but the use case is specific enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict this. It adds useful behavioral context by specifying the composition of the response: the opening day sign in both naming traditions and a composed reading, which goes beyond the annotation-only 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?

The description is two efficient sentences: the first states what the tool does and returns, the second gives the intended use case. Every word earns its place and there is no fluff.

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 a rich input schema, output schema, and safe-read annotations, the description covers the essential usage context: what is retrieved, how it is identified, and when it should be used. Nothing critical for an agent 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 input schema already documents all three parameters in detail, including language fallback, number range, and compact shape. The description only says 'by number' and adds no meaningful parameter semantics 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: 'Retrieve one of the twenty trecenas by number', and adds what is returned (opening day sign and composed reading). This clearly separates it from list-oriented sibling tools like get_mesoamerican_astrology_mayan_trecenas.

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 intended contexts: 'Built for period detail pages and for apps that show which thirteen day block a date falls in.' It does not explicitly name exclusions or alternatives, but the use case is clear enough 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?

The readOnlyHint annotation already establishes safety, and the description adds meaningful behavioral context: the count is anchored on the fall of Tenochtitlan, runs in step with the Maya count under a default constant, and is verified on anchor and modern dates. No contradiction with annotations exists.

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

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

The description is three focused sentences with no filler. The first sentence front-loads the core output, the second adds calibration provenance, and the third states use cases. 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?

With a rich output schema present, the description does not need to enumerate return fields. It covers purpose, calibration basis, verification, and intended use cases, and the schema handles input constraints. The definition is complete for an agent to select and call 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 input schema already documents the date format, proleptic Gregorian convention, lang fallback, and compact shape. The description does not add parameter-level semantics beyond mentioning 'any Gregorian date', so the baseline of 3 is appropriate.

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

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

The description uses a specific verb-resource pair: 'returns the tonalpohualli day sign, its coefficient 1 to 13 and its trecena for any Gregorian date'. It clearly identifies the tool as a date-based calculator and distinguishes it from the sibling day-sign list and daily-calendar tools by emphasizing the date input and composed reading.

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: this is the tool for answering 'what is my Aztec sign' and for Aztec calendar app features. It does not explicitly name exclusions or alternatives, but the date-scoped calculator framing makes the intended use evident against the sibling catalogue/list tools.

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, so the safety profile is covered. The description adds meaningful behavioral context: the correlation parameter 'shifts every value in the response', the compact mode reduces tokens by 40-52%, and parameters are echoed for exact reproduction. It also explains the date convention (proleptic Gregorian) and how it differs from Julian-based converters. These go beyond annotations without contradicting them.

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

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

The description is dense but every sentence contributes. It opens with the core output, then justifies the design choices (correlation as a parameter, echo for reproducibility) and explains the date convention. The structure is logical: purpose → use case → behavioral notes → parameter clarifications. No fluff or 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?

Given the tool's complexity (5 parameters, 3 enums, output schema), the description covers all input nuances, language handling, compact output, correlation effects, and year bearer variants. It even addresses the calendar convention pitfall. The presence of an output schema means return format need not be detailed. The description is thorough enough for an agent to call it correctly without external knowledge.

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?

Despite 100% schema coverage, the description enriches every parameter significantly. It explains the proleptic Gregorian date nuance and the Julian disagreement, details the four correlation constants and their day offsets, and clarifies the three Year Bearer systems with their specific day signs. The lang and compact parameters are also contextualized. This is far beyond what the schema's enum descriptions provide.

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 generates a Mayan birth chart from a date, listing specific components (Tzolkin, Haab, Long Count, Calendar Round, etc.). It distinguishes itself from siblings by focusing on a comprehensive chart rather than single-aspect tools like daily or day signs. The verb 'generate' and the resource 'Mayan chart' are 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 implies use cases ('Built for nawal readings, birth chart features and multi domain spiritual apps') but does not explicitly contrast with alternative tools like post_mesoamerican_astrology_mayan_tzolkin or daily. It states what it does but not when to choose it over others. No explicit exclusions or when-not-to-use guidance is given.

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 genuine behavioral context beyond that: it discloses that results are returned as parts rather than a verdict, and that 'scoring weights are stated on every response so a caller can re-derive the number or replace it' — an important contract for callers who want to audit or substitute the composite score. 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 sentences of zero waste. The purpose and parts-based output are front-loaded, use cases follow, and the weight re-derivability disclosure closes. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

For a complex tool with 6 parameters, 3 enums, and nested objects, the description is strong: it states purpose, use cases, output shape, and the re-derivable scoring behavior. An output schema exists so return values need no explanation. The only minor gap is the absence of explicit routing guidance against the sibling post_mesoamerican_astrology_mayan_chart tool, which is adjacent in purpose.

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% with thorough parameter documentation (lang BCP 47 coverage, correlation constants and their day offsets, directionScheme quarter-turn difference, proleptic Gregorian calendar caveats). The description itself adds no parameter-level meaning — it does not need to, since the schema carries the full burden. The baseline of 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-resource pair ('Mayan compatibility between two birth dates') and details exactly what is returned: nawals with coefficients and trecenas, the five structural ties, their weights, and a composite score. The parts-based approach ('published as its parts rather than as a verdict') clearly separates it from sibling single-date tools like get_mesoamerican_astrology_mayan_daily, get_mesoamerican_astrology_mayan_tzolkin, and post_mesoamerican_astrology_mayan_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 names concrete use cases ('matchmaking features, relationship reports and compatibility widgets that need to show their working'), giving an agent clear context for when to reach for this tool. It does not explicitly state when NOT to use it or name alternative analysis tools, but its pairing focus is self-evident against the sibling set.

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 declare destructiveHint=true, yet the description presents a pure, read-only converter with no mention of side effects, data modification, or destructive behavior. This is a direct contradiction, and the description makes no attempt to reconcile or explain the destructive hint. This is a serious inconsistency that misleads agents.

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 fluff: the bidirectional purpose is front-loaded, followed by output fields and use cases. It is concise and well-structured, though it could be slightly tighter by removing the final sentence about 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?

Despite rich schema and output schema, the description fails to address the destructiveHint=true annotation, which is critical for an agent deciding whether to invoke the tool. It also never clarifies whether the tool has any side effects, permissions, or state changes. The contradiction leaves a major gap in 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 description coverage is 100% with detailed parameter docs (e.g., longCount's winal counting rule, correlation enum offsets). The description adds only a minor rationale that correlation is a typed parameter to match inscriptions, which does not significantly exceed the schema. 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 a specific verb and resource: 'Maya Long Count converter that runs both ways: give it a Gregorian date and it returns the Long Count, give it a dotted Long Count and it returns the date.' This clearly distinguishes it from sibling astrology tools, which focus on day signs, trecenas, and horoscopes rather than calendar conversion.

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

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

The phrase 'Built for epigraphy tools, museum and education apps, and anything that has to place a Maya date on a civil calendar' gives clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but no sibling tool performs this exact conversion, so the usage context is adequately implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating that the correlation is echoed on every response for reproducibility and that a composed nawal reading is included.

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 front-load the core result and use case without unnecessary padding. The 'Built for' clause earns its place by clarifying intended usage, and only minor redundancy with the title/name prevents a 5.

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, detailed parameter descriptions, and read-only annotations, the agent has enough to call the tool correctly. The only notable gap is the lack of explicit routing to sibling tools for different calendar needs.

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 schema entries for date, lang, compact, and correlation are already very detailed. The description adds little parameter-specific meaning beyond mentioning the correlation in prose, 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 ('returns') and resource ('Tzolkin day sign, the coefficient 1 to 13 and the trecena') for any Gregorian date. It also clarifies the use case ('what is my Mayan sign') and distinguishes itself from sibling list/daily/monthly tools by being a single-date calculator.

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 scopes use to single-date Tzolkin queries for apps and AI agents, and 'Classical Maya count only' hints at a boundary. However, it does not explicitly name alternatives such as long_count_convert or chart/compatibility tools, nor 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.