Asterwise

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with them. It adds significant context beyond annotations: cryptographic randomness via Python secrets.SystemRandom, per-call independence with no session state, local rejection of out-of-range counts with MCP INVALID_PARAMS, and a 50% per-card reversal chance that is explicitly 'not seeded.'

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 behavior in the first sentence, then organized into labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) that make it scannable. There is no filler; examples, validation notes, and the docs link all earn their place, and the length is proportionate to the three near-sibling tools it must disambiguate.

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?

Between the annotations (safe read operation), the output schema, and the docs link for the full output/error contract, nothing an agent needs to invoke this tool correctly is missing. The reminder to interpret drawn cards via active_meaning and active_keywords fields also closes the loop on how results should be consumed.

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?

With 100% schema description coverage, the schema already documents all three parameters; the description adds strong value with concrete examples (1 daily pull, 3 simple reading, 10 Celtic Cross, 78 full deck), the 1–78 boundary with local validation behavior, and probability mechanics for allow_reversed (50% per card, independent, not seeded). Minor gap: response_format is absent from the INPUT CONTRACT section, though its schema description is thorough.

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

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

The description opens with a specific verb and resource — 'Draws N unique random cards from the 78-card deck' — and adds scope-defining traits (unique, cryptographic randomness, no session state). The 'DO NOT CONFUSE WITH' block names the three closest tarot siblings and their distinguishing behavior, so an agent can select this tool without opening their schemas.

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

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

Explicitly states the tool is standalone with no prerequisites or follow-up ('BEFORE: None', 'AFTER: None'). The 'DO NOT CONFUSE WITH' section names asterwise_get_tarot_card_of_the_day, asterwise_get_tarot_three_card_spread, and asterwise_get_tarot_celtic_cross with the precise differences (deterministic vs positional vs random), leaving no ambiguity about when this tool is the right choice.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add context — and it does, via input constraints and a pointer to the full output/error contract URL. It does not describe result shape or what happens when zero matches are found, which keeps it short of a 5.

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

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

Front-loaded one-line purpose, then labeled blocks, and the constraints that matter are stated up front. Minor waste in placeholder lines ('BEFORE: None', 'DO NOT CONFUSE WITH: None'), though they do cheaply confirm the absence of a prerequisite or sibling overlap.

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

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

With an output schema present, the description need not explain return values, and it already covers the input contract, the dependency relationship to downstream tools, and where to find the error contract. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents query, limit, country and response_format. The description restates the same constraints (2-char minimum, 1-10 limit, ISO 3166 alpha-2) without adding format examples or syntax beyond the schema, and omits response_format entirely. 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 and transformation: 'Turns a place name into latitude, longitude and IANA timezone.' It also explicitly positions itself against all 100+ siblings ('this is the only place-lookup tool'), so an agent can rule out confusion without inspecting schemas.

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 WORKFLOW block gives explicit before/after routing: BEFORE is 'None' and AFTER names concrete consumers (asterwise_get_natal_chart, asterwise_get_panchanga, asterwise_get_muhurta, asterwise_get_festival_calendar). This tells the agent exactly when to call it and what to do with the result.

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

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

Annotations already declare readOnly/idempotent/non-destructive. The description adds concrete behavioral detail: the LP-to-sequence mapping rules, master number handling, and scope ('extracts only the Life Path → angel sequence mapping'), plus a docs link for the full output/error contract. 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?

Front-loaded with a clear first sentence, then organized into labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE, docs link). Each section earns its place; no filler.

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

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

With an output schema present, the description doesn't need to explain return values. It covers purpose, mapping, workflow, param semantics, exclusions, and points to a full contract. Nothing essential is missing for correct invocation.

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 100% of parameters with descriptions, so baseline is 3. The description adds an explicit example ('1994-03-31'), marks name as optional, and clarifies that date means 'birth date' (not today's date), which disambiguates from the sibling tool. That extra practical context justifies a 4.

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 operation — 'Computes a personal angel number from a birth date using the Pythagorean Life Path as the base' — and gives the exact mapping logic. The 'DO NOT CONFUSE WITH' section explicitly separates it from asterwise_get_angel_number_today and asterwise_get_numerology_profile.

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?

Provides explicit when-to-use guidance: recommends calling asterwise_get_numerology_profile first to confirm Life Path, and lists two confusable siblings with conditions (daily vs birth date; full profile vs only Life Path mapping). This leaves no ambiguity about alternative 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 cover readOnly/idempotent/non-destructive behavior, so the description's job is lighter. It adds value by stating the exact computed outputs, clarifying that raw matrices are exposed here rather than applied to transits, and linking to the full output/error contract. Minor operational details like rate limits or auth are absent but not critical for a read-only compute 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?

The description is well-structured with labeled sections—WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH—and the core function is front-loaded in the first sentence. It is longer than minimal, but the length is justified by the complexity of the tool and the need to disambiguate among a large sibling list.

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 Vedic tool with a nested birth object and an output schema, the description provides the essential workflow, input restriction, sibling disambiguation, and a link to the full contract. Return-value details are not duplicated because an output schema exists, so nothing necessary for correct selection and 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?

The input schema provides 100% parameter coverage with detailed descriptions for date, lat, lon, time, ayanamsa, timezone, person_name, and response_format, so the baseline is 3. The description adds only the high-level contract 'BirthData only,' which is useful but does not deepen per-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?

Description opens with a precise verb phrase—'Computes full Ashtakavarga bindu matrices, trikona and ekadhipatya reductions, and sarva totals'—clearly identifying both the resource and the computation. The 'DO NOT CONFUSE WITH' sections explicitly distinguish it from asterwise_get_chart_strength and asterwise_get_gochar, so an agent can disambiguate 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 WORKFLOW section names a recommended predecessor (asterwise_get_natal_chart), a natural successor (asterwise_get_gochar), and why the successor uses this tool's output. It also identifies the tools most likely to be confused with this one and explains the selection difference, making when-to-use unambiguous.

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 strong safety cues: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context beyond those: it is a standalone reference with no BEFORE/AFTER workflow dependencies, and it defaults the date to today. It also links to the full output and error contract, which covers any remaining behavioral details.

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 well structured and front-loaded: the core behavior appears in the first sentence, followed by compact WORKFLOW, INPUT CONTRACT, and confusion-avoidance sections. Every section earns its place and the whole thing is easy for an agent to scan.

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 tool with full schema coverage, an output schema, and rich annotations, the description is complete. It covers date format, default behavior, supported systems, sibling alternatives, and points to the full output/error contract.

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 both date and response_format fully. The description reiterates the date default but does not add meaningfully beyond the schema. Baseline 3 is appropriate because the schema carries the parameter semantics 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 states a specific verb with a resource: 'Returns ayanamsha values for all four supported systems (Lahiri, Raman, KP, Tropical) for a given date.' It is clearly distinct from sibling tools, and it even names the two most likely confusable alternatives and what they do differently.

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 provides a 'DO NOT CONFUSE WITH' section, naming asterwise_get_natal_chart and asterwise_get_westen_natal and explaining when each should be used instead. This gives concrete routing guidance beyond simply defining the 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?

The description adds some behavioral context beyond the annotations by stating it is 'standalone' and has a specific workflow after it, which is not covered by the readOnly or idempotent hints. However, it does not explicitly mention side effects or permissions, though the annotations already cover these (readOnlyHint true, destructiveHint false). Overall, it adds moderate context without contradicting the annotations.

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

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

The description is structured into clear sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) and is not overly long. However, the INPUT CONTRACT section repeats information already present in the schema, introducing slight redundancy. The front-loaded first sentence is effective, and the overall structure is easy to follow.

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 moderate complexity (4 parameters, 1 enum, output schema exists), the description covers the core purpose, usage, and differentiators. It points to a URL for the full output and error contract, which addresses potential omissions. It does not describe the output structure in detail, but the link compensates. Overall, it is sufficiently complete for an agent to decide and invoke the tool correctly.

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

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

The schema already covers 100% of the parameter descriptions, giving a baseline of 3. The description adds the range constraint for 'days' (1-90) and clarifies the default behavior for 'target_date' ('Defaults to today'), which is not fully specified in the schema. This additional context improves understanding beyond the schema alone.

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 that the tool computes physical, emotional, and intellectual biorhythm cycles for a birth date. It also explicitly distinguishes itself from related tools via the 'DO NOT CONFUSE WITH' section, naming asterwise_get_nakshatra_prediction and asterwise_get_panchanga. This provides both a specific verb and resource, and clear 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 provides explicit workflow guidance: 'BEFORE: None' and 'AFTER: asterwise_get_nakshatra_prediction', indicating where this tool fits in a sequence. It also tells the agent when not to use this tool (i.e., for Vedic daily predictions or panchanga elements), making the selection criteria very clear.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the computation uses the name only and no birth date, the date param is inert, and reduction strips non-letters per upstream rules. It stops short of discussing determinism guarantees or output shape, but the output schema covers the latter.

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

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

Front-loaded one-line summary followed by labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH, doc link). Every sentence carries routing or contract information; nothing is padding.

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

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

An output schema exists, so return values needn't be restated. Given the tool is a standalone, single-input computation, the description covers purpose, disambiguation, input handling, and workflow transitions, leaving no gap an agent would need filled before calling 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 coverage is 100%, which sets a baseline of 3, but the description adds meaning the schema lacks — that special characters and digits are acceptable in business_name and that non-letters are stripped during reduction. The date parameter's inert status is clarified in both places.

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 ('Reduces a business name to Expression and root digits') and names the actual outputs (thematic suitability lists, harmony score). The DO NOT CONFUSE WITH block explicitly separates it from asterwise_get_name_correction and asterwise_check_mobile_number, so an agent can route without opening schemas.

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 WORKFLOW block gives explicit before/after conditions ('BEFORE: None — standalone', 'AFTER: get_name_correction — if the entity is a person, not a brand') and the DO NOT CONFUSE WITH block names the two most confusable siblings with the discriminating condition for each.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing the core safety profile. The description adds no side-effect information but does describe the output (quality, ruler, local clock bounds) and the input basis (sunrise/sunset at a location), which gives some behavioral context beyond the annotations. Since annotations cover the main safety aspects and the description adds modest context, a score of 4 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 main description is a single, dense sentence that conveys the core function without fluff. The additional sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) are each short and purposeful, adding necessary guidance without redundancy. The structure is well-organized and every sentence contributes value.

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 description covers the tool's purpose, input constraints (via INPUT CONTRACT and schema), output expectations (quality, ruler, clock bounds), workflow (before/after), and alternatives to avoid. It also provides a link to the full output/error contract. For a tool with a nested location parameter, this is comprehensive and leaves little ambiguity for an agent to invoke it correctly.

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

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

Schema description coverage is 100% with all fields having descriptions (e.g., lat/lon ranges, date pattern, timezone default, response_format enum). The description text adds context by explaining that the location is used for 'sunrise/sunset' and that output includes 'local clock bounds,' which clarifies the role of timezone and lat/lon. The INPUT CONTRACT section also states that LocationInput enforces date format and lat/lon ranges, reinforcing schema details. This extra context justifies a 4 rather than the baseline 3.

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

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

The description states exactly what the tool does: 'Splits a solar day into sixteen Choghadiya segments from sunrise/sunset at a location and labels each slot's quality, ruler, and local clock bounds.' It clearly identifies the resource (solar day segments) and the action (splits and labels). The 'DO NOT CONFUSE WITH' section explicitly differentiates it from asterwise_get_hora and asterwise_get_muhurta, making it distinct among the many sibling tools.

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

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

The description provides explicit workflow guidance: 'BEFORE: None — this tool is standalone. AFTER: asterwise_get_rahu_kaal — optional inauspicious band overlay for the same date.' It also includes 'DO NOT CONFUSE WITH' warnings that clarify when not to use this tool compared to related ones (hora, muhurta). This gives the agent clear conditions for selecting this tool over alternatives.

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

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

Annotations already cover readOnly and idempotent hints, so the description does not need to repeat those. It adds behavioral context by stating the sorting logic and offering a response_format parameter, which clarifies output behavior beyond the schema. The output/error contract link provides additional transparency, though no direct side-effect details are needed given 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 well-structured with clear sections (workflow, input contract, do-not-confuse, output contract). Though somewhat lengthy, every sentence contributes useful information—no fluff. The main recommendation statement is concise, and the additional sections are organized logically.

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?

Provides sufficient context for correct invocation: required filters, output format options, and a link to the full output/error contract. Although the actual output schema is not embedded, the description's mention of markdown/json and the contract URL mitigate the gap. It also clarifies relationships with sibling tools, making the tool's role well-defined.

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 baseline is 3. The description enhances this by listing allowed chakra values (Root, Sacral, Solar Plexus, etc.) which are not in the schema enum, and providing concrete examples for intention (protection, abundance, love) and zodiac_sign. It also clarifies the limit default/max, aligning with schema but adding context.

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?

Clearly states the verb 'Recommends' and the resource 'crystals', with specific criteria (zodiac sign, chakra, intention). The 'DO NOT CONFUSE WITH' section explicitly differentiates from sibling tools like asterwise_get_crystal_by_planet and asterwise_get_gemstone_recommendations, making its purpose 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?

Explicitly states the requirement 'At least one filter is required' and describes the ordering behavior ('matches the most criteria first'). The workflow mentions 'AFTER: asterwise_get_crystal' for subsequent detail retrieval, and the 'DO NOT CONFUSE WITH' lines provide clear when-to-use guidance against alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: the payload grows sharply at higher levels, response dates are DD/MM/YYYY not ISO, and unknown birth time triggers a sunrise chart with birth_time_provided=false. It does not explain pagination or error surfaces beyond pointing to docs.

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

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

Front-loaded one-line purpose followed by labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH, docs link) that make skimming efficient. Slightly verbose with some redundancy against the schema, but every section carries routing or contract 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?

With an output schema present, return values need not be explained, and the description still adds the date-format caveat and payload-size warning. Combined with workflow ordering, sibling disambiguation, and the docs link for full error contracts, an agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, so baseline is 3. The description still adds value over the schema: it restates the levels ladder compactly and discloses the response date format and the unknown-time convention that govern how results should be read, which the schema alone does not surface. Marginal gain over a rich schema keeps it at 4 rather than 5.

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

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

States a specific verb and resource ('Computes Vimshottari Dasha from birth data') and explicitly names the scope of the returned artifacts (hierarchical period trees plus current Maha/Antar interpretation). The DO NOT CONFUSE WITH block distinguishes it from the three closest sibling dasha tools by name.

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?

Provides explicit BEFORE/AFTER workflow ordering (get_natal_chart before, get_dasha_transits after) and a dedicated DO NOT CONFUSE WITH section naming each alternative and the exact discriminator (ISO dates, sign-based, 36-year cycle). An agent can route correctly without opening any sibling schema.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: enum enforcement is local, and with an unknown birth time the lagna, houses, and houses table are omitted with birth_time_provided=false. It does not cover failure modes or rate limits, which is delegated to the docs URL.

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

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

Front-loaded core sentence, then clearly labeled WORKFLOW / INPUT CONTRACT / DO NOT CONFUSE WITH blocks. Every sentence carries information; no filler.

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

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

For a read-only computation tool with a full output schema, the description covers what is computed, the optional-parameter behavior, output contents, degradation without birth time, prerequisites, and sibling disambiguation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so birth fields, ayanamsa, timezone, and the omission-for-unknown-time semantics are already documented in the schema. The description's 'omit chart_type for all sixteen' and the birth_time_provided note largely restate what the schema says, 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 and resource ('Computes divisional (varga) charts from BirthData') and immediately names the two siblings it is not: get_natal_chart and get_chart_strength. An agent can distinguish it from all ~90 siblings without opening a schema.

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

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

Explicit WORKFLOW block recommends asterwise_get_natal_chart as the D1 anchor beforehand, states AFTER: None, and the DO NOT CONFUSE WITH section routes on the specific conditions (radix chart with houses/drishti vs. varga set; varga-based strength scores vs. placements).

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 description adds behavioral details not covered by annotations, such as 'Unknown birth time at midnight is accepted silently,' and clarifies output types like 'presence flags, typed detail objects, optional summaries, and remedy lines.' These enrich the readOnlyHint and idempotentHint already present.

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 well-structured with clear sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH), each serving a distinct purpose. It is concise yet comprehensive, avoiding redundancy while covering essential operational aspects.

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 description includes the input contract, workflow context, differentiation from siblings, and a link to the full output/error contract. Given the tool's moderate complexity, this provides sufficient context for correct usage without needing to restate every schema detail.

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?

While the schema already provides detailed descriptions for parameters, the description adds valuable semantics by noting that omitting birth time uses a sunrise chart and sets birth_time_provided=false, clarifying the behavior for the 'time' field. This goes beyond the schema's basic default 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 function: 'Scores twelve fixed dosha buckets from birth data and returns presence flags, typed detail objects, optional summaries, and remedy lines per dosha.' It also explicitly differentiates from similar tools like asterwise_get_chart_strength and asterwise_get_compatibility, making its unique purpose unmistakable.

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 guidance with 'WORKFLOW: BEFORE: RECOMMENDED — asterwise_get_natal_chart' and 'AFTER: asterwise_get_remedies.' It also includes a 'DO NOT CONFUSE WITH' section that names alternatives and explains why they should not be chosen instead.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses case-insensitive lookup, standalone execution, and provides a link to the full output and error contract. These are behavioral details not covered by 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 well-organized with clear sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH, full contract link). It is concise, uses short bullet-like sentences, and avoids unnecessary elaboration.

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 description covers the return content (Jungian archetype, Vedic meaning, context variants, related symbols), the input format with examples, the output format options, and points to a full contract link. Combined with the schema and annotations, it gives the agent full context needed to invoke 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?

The schema has 100% description coverage for both parameters. The description's INPUT CONTRACT section only repeats the name parameter details already present in the schema (e.g., examples). No additional semantic meaning is added beyond what the schema already provides.

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

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

The description explicitly states the action ('Lookup a specific dream symbol'), the target resource ('by slug or name (case-insensitive)'), and the output contents ('full dual-tradition interpretation...'). It also names the sibling tool it is not to be confused with, making the purpose unmistakable.

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

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

The description provides clear 'DO NOT CONFUSE WITH' guidance to distinguish from asterwise_get_dream_symbols (full listing), and includes a WORKFLOW section indicating it is standalone with no prerequisites or follow-ups. This gives explicit when-to-use and when-not-to-use direction.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond that: how lunar festivals are fixed, tie-break and Bhadra/Smarta Ekadashi rules, and that results are checked against Drik Panchang (New Delhi), which tells the agent about the methodology and reliability.

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?

Well front-loaded and organized into scannable sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH). The opening paragraph's dense jyotisha jargon (amanta, Madhyahna, Aparahna, Bhadra) is more than an agent needs for tool selection, but it is not wasteful padding.

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 an output schema exists, return values need no explanation. The definition supplies the year range, coordinate span, timezone default, category semantics, workflow prerequisites, and sibling routing — everything needed to invoke 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 already documents year/lat/lon/timezone/categories/response_format. The description largely restates the categories enum and its default; the 'add vrat for every Ekadashi...' guidance is only marginally additive. Baseline 3 is appropriate.

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

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

States a specific verb+resource+scope ('Hindu festivals, vrats, sankrantis, eclipses and periods for a year at a location') and explicitly distinguishes itself from three sibling tools. An agent can route to it without inspecting any schema.

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

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

Provides an explicit BEFORE/AFTER workflow (geocode before, panchanga after) and a DO NOT CONFUSE WITH block naming the two overlapping calendar/panchanga siblings with the condition that separates them. Nothing about when-to-use is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real value beyond that: it declares that all inputs derive from birth data with no sunrise fallback and states the computational dependency on the natal Moon sign. It stops short of richer behavioral detail (cost, latency, precision limits) but covers what matters for correct invocation.

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

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

Front-loaded one-line purpose followed by labeled blocks (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH). Every sentence carries routing or input information; nothing is padding, despite the length.

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

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

An output schema exists so return values need no prose, and the description supplies the missing pieces: workflow placement, the input contract, disambiguation from siblings, and a docs link for the full output/error contract. Nothing needed to call it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents birth, response_format and every nested field (including the ayanamsa enum and the warning against guessing birth time). The description only adds that Moon sign is computed from birth data, which is derived behavior rather than new parameter meaning. 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 and resource: returns the four Ghatak (inauspicious) timing parameters, scoped to Janma Rasi. It explicitly names and contrasts the sibling tools it could be confused with, so an agent can select it without opening any schema.

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

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

The WORKFLOW block gives explicit BEFORE/AFTER sequencing, and the DO NOT CONFUSE WITH block names two alternatives (get_nakshatra_prediction, get_panchanga) with the exact distinguishing condition for each. Nothing about when to use this vs. those is left to inference.

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

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

Annotations already include readOnlyHint=true and idempotentHint=true, covering the key behavioral aspects. The description adds context about the output (tags each hour with ruler, quality, and 'current' status) and references a full output/error contract link. This goes slightly beyond the annotations, though it doesn't explicitly mention side effects or permissions (which are covered by the readOnlyHint).

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 well-structured with clear sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH, full contract link). It is concise yet comprehensive, using bullet-like separations to convey essential information without unnecessary verbosity, especially given the large number of sibling tools it must differentiate from.

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 relatively simple input structure (one nested location object) and an output schema is present. The description provides enough context to understand the tool's purpose and output, and it includes a link to the full output/error contract. Given the output schema exists, the description adequately covers what an agent needs to invoke it correctly.

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

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

The input schema has 100% description coverage for all properties, including date format, lat/lon ranges, timezone default, and response_format enum. The description only restates the location rules ('date/coordinate rules apply locally') without adding new semantic details beyond the schema, so it does not exceed the baseline for schema-covered parameters.

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 specific function: 'Builds the twenty-four planetary Horas between successive sunrises for a location and tags each hour with ruler, quality text, and whether it is current.' It also explicitly differentiates from sibling tools like asterwise_get_choghadiya and asterwise_get_natal_chart, 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?

The description provides explicit guidance on when to use this tool versus alternatives. It states 'WORKFLOW: BEFORE: None — this tool is standalone' and 'DO NOT CONFUSE WITH' sections that clarify the differences from get_choghadiya and get_natal_chart, giving clear conditions 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 establish read-only, idempotent, non-destructive behavior; the description adds that this is an AI-synthesised editorial horoscope, returns structured guidance fields plus model/period metadata, and that response_format only controls rendering between markdown and JSON. It also references a full output/error contract URL, providing meaningful behavior 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 longer than minimal, but every section earns its place: purpose, workflow, input contract, disambiguation, and documentation link. The structure is clear and front-loaded with the core purpose before supporting details, making it efficient despite its length.

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, the description appropriately focuses on selection, input constraints, disambiguation, and the contract URL for full output/error details. It covers before/after workflow and alternatives, so an agent has everything necessary to invoke the tool correctly in context.

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 baseline is already strong, but the description adds genuine value by expanding moon_sign to include Sanskrit and English rashi names, clarifying that period is constrained to the schema enum, and specifying that response_format only selects rendering mode. This helps an agent understand valid inputs beyond the basic schema descriptions.

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

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

States a clear, specific action: fetches an AI-synthesised Moon-sign horoscope for a chosen horizon, and distinguishes the resource and deliverable from sibling tools. The 'DO NOT CONFUSE WITH' section explicitly contrasts it with asterwise_get_natal_chart and asterwise_get_gochar, so an agent can select it correctly.

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?

Provides explicit when-to-use guidance via WORKFLOW and DO NOT CONFUSE sections, naming the exact sibling tools and their purposes. It also notes that a personalized chart should use asterwise_get_natal_chart, giving clear exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: an ordering dependency on asterwise_get_kp_chart, the fact that the tool reads BirthData with no sunrise fallback, and the shape of the result (house tables plus planet-tier reverse indexes). It does not discuss cost, rate limits, or failure modes, which is acceptable given the annotations and output 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?

The one-line summary is front-loaded and the labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) make the routing information scannable rather than buried in prose. It is slightly padded by the redundant INPUT CONTRACT line and the external docs URL, but nothing is materially wasteful.

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, a rich nested birth object, an output schema, and safety annotations, the description covers the remaining gaps an agent needs: when to run it relative to the KP chart tool, and which sibling tools it is not. The only omission is domain context on what a 'significator tier' means, which is reasonable to defer to the linked 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?

Schema description coverage is 100% and every parameter (birth fields, ayanamsa, timezone, house_number, response_format) is documented in the schema itself, including the important 'never pass 00:00 for unknown' warning. The description's INPUT CONTRACT ('house_number optional int 1..12; omit for all twelve') only restates what the schema already says, so 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?

The first sentence states a specific verb and resource ('Computes KP significator chains') and names the scope ('all houses or one optional house from BirthData'), plus what it returns ('house tables plus planet-tier reverse indexes'). The DO NOT CONFUSE WITH section explicitly separates it from asterwise_get_kp_chart and asterwise_get_natal_chart, so an agent can identify it without opening any schema.

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

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

The WORKFLOW block gives an explicit precondition ('BEFORE: RECOMMENDED — asterwise_get_kp_chart — establish cusps before significators') and states there is no follow-up tool. The DO NOT CONFUSE WITH section names two alternatives and explains the discriminating dimension (cusps/sub-lords vs. tiered significator unions; drishti matrices vs. KP tiers).

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 this is a read-only, idempotent, non-destructive operation, so the bar is lower; the description goes well beyond them by disclosing that tropical ayanamsa is refused with INVALID_PARAMS, that omitting time yields a sunrise chart with birth_time_provided=false and approximate houses, and that the output enumerates specific derived structures.

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

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

Front-loaded purpose sentence followed by clearly labeled WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE WITH sections; the structure makes scanning fast. It is somewhat long, and the docs URL/last line is minor overhead, but each block carries actionable content rather than filler.

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

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

An output schema exists and the description summarizes the returned structures rather than restating them; combined with the ayanamsa constraint, unknown-time fallback, error behavior, and sibling routing, nothing an agent needs to invoke this 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 baseline is 3, but the description adds real semantics the schema lacks: it clarifies that ayanamsa options are used 'as sent' except tropical, which the schema lists as a valid enum value but the tool rejects, and it explains the unknown-birth-time behavior of the time parameter. That is meaningful guidance beyond the field descriptions.

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

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

States a specific verb and resource ('Produces a Lal Kitab chart from BirthData') and grounds it in a named system ('following the 1952 Lal Kitab: houses counted from the Vedic lagna'). It also enumerates what the chart contains (pakka ghar, uchcha/neecha, twelve houses, nine rin) and explicitly separates itself from asterwise_get_natal_chart, so an agent can pick 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?

Provides explicit BEFORE/AFTER workflow chaining (standalone, then asterwise_get_lal_kitab_remedies for planets needing remedies) and a 'DO NOT CONFUSE WITH' block naming the two nearest siblings with the condition that distinguishes them. Nothing about when-to-use is left to inference.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds context beyond annotations by declaring the tool standalone (no workflow dependencies) and noting the input is validated upstream. 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 the core purpose, then uses clearly labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) that each earn their place. Slightly long but efficiently organized with zero filler; the docs link consolidates the full contract rather than inlining it.

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

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

An output schema exists, so return values need not be spelled out. The description covers the input contract, workflow dependencies, sibling disambiguation, and points to a docs URL for the full output/error contract. For a read-only two-parameter tool this is nearly complete, with only the error behavior deferred to the external docs.

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% — both date (YYYY-MM-DD format) and response_format (markdown/json enum with default) are documented in the schema. The description's INPUT CONTRACT note ('date string only') reinforces but does not add semantic detail beyond what the schema already provides, 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?

The description states a specific verb (derives), resource (Lo Shu three-by-three frequency grid), input source (birth-date digits), and the analytical outputs (planes, missing/repeated digits, per-digit traits). It also explicitly names two sibling tools it should not be confused with, which sets it apart from the dozens of numerological siblings.

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

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

The 'DO NOT CONFUSE WITH' section explicitly routes the agent to asterwise_get_numerology_profile for letter-based Western numbers and asterwise_get_name_correction for spelling harmonics. The INPUT CONTRACT states the sole accepted input (date string) and that validation is handled upstream, giving clear when-to-use and when-not-to-use 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 that this is a read-only, idempotent, non-destructive, closed-world operation. Beyond that, the description discloses the actual computation behavior: which nakshatra, tithi, weekday, seasonal-ban, and inauspicious-period rules are applied, that results are scored 0-100 with reasons, and that excluded_minutes explains an empty result.

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?

Despite being detailed, the description is well structured with a front-loaded purpose sentence followed by WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE sections. For a tool with many nested parameters and close siblings, every section adds useful routing or contract 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?

The tool has an output schema, so the description need not document return values. It still covers scope, activity rules, required and optional inputs, workflow dependencies, sibling distinctions, scoring behavior, and empty-result behavior, making it complete enough for correct invocation.

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 baseline is 3. The description adds organizational clarity by separating required fields from optional ones and summarizing the participant alternatives, but it also omits some optional schema fields such as ayanamsa and response_format, and much of its input contract repeats schema descriptions.

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

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

The first sentence gives a precise verb, resource, scope, and output format: it finds auspicious time windows for a named activity between two dates at a location, returning ISO start/end times. It explicitly lists supported activities and distinguishes itself from the closest siblings with a DO NOT CONFUSE section.

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 WORKFLOW section states when to call asterwise_geocode before this tool and asterwise_get_panchanga after it. The DO NOT CONFUSE section names the two most likely alternative tools and explains their different purposes, leaving no ambiguity about when to select this 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?

Beyond the read-only/idempotent annotations, it discloses the unknown-birth-time behavior (sunrise chart cast, birth_time_provided=false) and the downstream consequence that lagna-sensitive results become approximate. That is genuine behavioral context an agent needs in order to interpret output, not a restatement of 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?

Front-loaded and well-sectioned (purpose, workflow, input contract, disambiguation), with no filler sentences. It is slightly verbose because the input contract partly restates schema-level validation rules, but each section still earns its place.

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

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

For a read-only chart tool with a rich nested schema and an output schema, the description covers the remaining needs: workflow position, sibling disambiguation, edge-case input handling, and a documentation link for the full output/error contract. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents formats, bounds, and the ayanamsa enum, making 3 the baseline. The description adds meaning by warning that time='00:00' is read as midnight and by linking the omitted-time case to approximation of lagna-sensitive values, which the schema alone does not convey.

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 (Computes) and resource (full sidereal natal chart) plus an explicit enumeration of the returned artifacts (planet rows, houses, aspects, arudhas, upapada, bhava cusps, avakhada). It also names the sibling it should not be confused with, so an agent can separate it from the divisional-chart tool without opening either schema.

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

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

Explicit BEFORE/AFTER workflow (standalone, then optionally layer yogas) plus an explicit DO NOT CONFUSE WITH routing to asterwise_get_divisional_chart. This covers when to use it, what precedes/follows, and the alternative, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail beyond that: it compares two charts, uses three reference points, and produces a threshold-based compatibility label, plus it points to a full output/error contract URL.

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

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

The description is front-loaded with the core purpose, then organized into short labeled sections for workflow, input contract, disambiguation, and documentation. Every section earns its place and there is no redundant prose.

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 Vedic compatibility tool, the description covers the core calculation, recommended sequencing, exclusions from two similar tools, the two-person input contract, and a link to the full output and error contract. The rich input schema and output schema reduce the need for inline return value 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?

Schema description coverage is 100%, and the nested BirthData fields are already fully documented with formats, defaults, and examples. The description only restates 'Two BirthData objects per global contract,' which does not add significant meaning beyond what the schema already provides.

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

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

The opening sentence states a specific computation—'Measures malefic stress from Lagna, Moon, and Venus references for each partner, compares totals, and labels compatibility level against a threshold'—with a clear verb, resource, and outcome. It also names the sibling tools it must not be confused with, making differentiation immediate.

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 WORKFLOW section explicitly recommends asterwise_get_compatibility as a BEFORE step, and the 'DO NOT CONFUSE WITH' section names asterwise_get_doshas and asterwise_get_compatibility with precise scoping reasons. This gives the agent clear when-to-use and when-not-to-use guidance relative to the closest siblings.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the analysis basis (all five classical combinations), the absence of a prerequisite step, and the downstream remediation path. It stops short of describing output shape or the odd idempotentHint=false, but an output schema exists to cover returns.

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

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

Front-loaded purpose, then labeled blocks (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) with no filler sentences. The docs link is a single trailing reference rather than padding.

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 an output schema exists, the description needn't explain returns; it still covers purpose, prerequisites, follow-up routing, sibling disambiguation, and the birth-time requirement. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every field including the 'no sunrise fallback' warning and the ayanamsa enum. The INPUT CONTRACT line only restates the top-level birth object (date, time, lat, lon) and omits ayanamsa, timezone, person_name, and response_format, adding nothing the schema doesn't already say. Baseline 3.

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

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

States a specific verb and resource ('Detects and analyses Pitru Dosha') and immediately scopes it ('using all five classical Pitru Dosha combinations'). The DO NOT CONFUSE WITH clause explicitly separates it from asterwise_get_doshas, so an agent can pick correctly without opening schemas.

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

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

Explicit WHEN/WHEN-NOT: no prerequisite step ('BEFORE: None'), a named follow-up tool (asterwise_get_puja_suggestions), and a direct alternative with the condition that selects this tool over it ('use this tool when dedicated Pitru Dosha analysis is needed').

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it is a standalone reference tool, follows classical Vedic tradition, and can return either all planets or one planet; it also links to the full output and error contract. It adds value 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?

The description is organized into short, labeled sections (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE) with the core purpose front-loaded in the first sentence. Every section earns its place by aiding tool selection or invocation, and the formatting makes scanning easy despite the large sibling list.

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, read-only reference tool with two optional parameters and an output schema, the description is complete: it states purpose, input contract, workflow context, sibling disambiguation, and points to the full output/error contract via URL. Nothing an agent needs to select or invoke 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%, but the description adds meaning for the 'planet' parameter by enumerating all nine allowed values and explicitly stating that omitting it returns all planets. The 'response_format' parameter is already well-explained by the schema enum, so the description does not need to repeat it.

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 ('Returns') and resource ('classical graha (planet) properties'), and clearly scopes the operation to 'all nine planets or a single planet'. The 'DO NOT CONFUSE WITH' section explicitly distinguishes it from puja suggestions and rudraksha recommendations, making sibling differentiation strong.

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 WORKFLOW section states there is no prerequisite ('BEFORE: None') and names the natural follow-up tool ('AFTER: asterwise_get_puja_suggestions'). The 'DO NOT CONFUSE WITH' block explicitly names alternatives and why they are different, giving clear when-to-use versus when-not-to-use guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds useful behavioral context such as omitting planet returns all nine ggrahas and positioning pujas as complementary to rudraksha. The link to the full output/error contract handles the remaining behavioral disclosure without cluttering the text.

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 a crisp purpose sentence and uses labeled short sections such as WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE, so an agent can scan quickly. Every section carries distinct information and there is no filler or repetition of schema/annotation values.

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 tool with an output schema and safety annotations, the description covers workflow context, parameter semantics, sibling disambiguation, and points to the full contract. An agent choosing between this and any of the many siblings has enough context to route correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds a complete enumeration of the nine allowed planet values plus the omit-for-all behavior, which the schema only hints at with examples. The response_format parameter is already fully described in the schema, so no further prose is needed.

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

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

The first sentence states a specific verb and resource: 'returns puja (ritual worship) recommendations for planetary propitiation per ggraha'. The 'DO NOT CONFUSE' section explicitly separates it from asterwise_get_remedies and asterwise_get_rudraksha, making the purpose unambiguous even among many siblings.

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

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

WORKFLOW provides explicit before/after tool relationships: natal chart first, rudraksha after, and the DO NOT CONFUSE section names the closest alternatives. The INPUT CONTRACT also tells the agent when to omit planet versus supply a specific ggraha.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it computes and marks based on diurnal length and local time, which is transparent and consistent. No side effects or hidden actions are implied, and with annotations present, this level of disclosure is sufficient.

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 main description is one concise sentence that front-loads the core purpose. The additional WORKFLOW and INPUT CONTRACT sections are structured and mostly non-redundant, though the input contract partially repeats schema information. Overall, it is well-organized and efficient.

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 an astrological tool with multiple intervals and disambiguation needs, the description covers the essential information: what it computes, how it uses location and time, and how it differs from closely related tools. It is complete enough for an agent to decide when and how to invoke it correctly.

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

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

The schema already provides full descriptions for all parameters (100% coverage), so baseline is 3. The description adds context by mentioning 'diurnal length' (implying lat/lon usage) and 'local time' (implying timezone importance), which helps an agent understand parameter relevance beyond the schema text.

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 exact function: computing Rahu Kaal, Gulika Kaal, and Yamaganda Kaal intervals from diurnal length and marking active status. It explicitly names the three intervals and the 'active now' feature, distinguishing it from the sibling choghadiya tool which covers full day/night slot tables.

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 'DO NOT CONFUSE WITH' section explicitly contrasts this tool with asterwise_get_choghadiya and asterwise_get_panchanga, providing clear conditions for when this tool should be used (for the three kaal bands specifically) versus alternatives. This gives direct guidance on tool 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the charts come from an independent source, are fixed rather than computed, and the harness edge cases they exercise.

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

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

Front-loads the core purpose and uses labelled WORKFLOW / INPUT CONTRACT / DO NOT CONFUSE WITH sections that are easy to scan. The long parenthetical list of edge cases is slightly verbose, though it does inform what the returned data 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 read-only, zero-required-input listing tool with a full output schema and rich annotations, the description covers everything an agent needs: purpose, placement in the workflow, the sibling to compare against, and a link to the full output/error contract.

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?

Only one parameter (response_format) with 100% schema description coverage, so the schema already documents it fully. The 'INPUT CONTRACT: No inputs beyond response_format' line is consistent but adds no meaning beyond what the schema states.

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 — published test charts with reference values — and enumerates exactly what they cover. The 'DO NOT CONFUSE WITH' section explicitly separates it from asterwise_get_natal_chart, so an agent can distinguish it without opening a schema.

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

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

Gives explicit workflow: standalone with no prerequisites, then a follow-up step of sending an input to asterwise_get_natal_chart to compare. Names the alternative and the condition ('this lists charts to check it against'), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description need not repeat those. It adds context by specifying the workflow dependency, the behavior when planet is omitted ('Omit to get all nine planets'), and points to a full output/error contract. This exceeds the annotation baseline 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 tightly structured and front-loaded with a one-sentence purpose. The WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE WITH sections are scannable and each adds distinct value. There is no filler or redundant restating of the schema.

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 read-only idempotent annotations, optional parameters, and available output schema, the description is complete enough for an agent to invoke the tool correctly. It covers prerequisites, parameter values, sibling disambiguation, and points to the full output/error contract. No critical contextual gap remains.

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 baseline is 3. The description goes further by enumerating the exact allowed planet values (Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, Rahu, Ketu) and explaining the omission behavior, which the schema does not fully specify. This adds meaningful guidance beyond the parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Returns Rudraksha bead recommendations per planet.' It clearly scopes the tool to per-planet bead recommendations and explicitly contrasts it with gemstone and puja tools in the 'DO NOT CONFUSE WITH' section, making sibling differentiation strong.

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 WORKFLOW section explicitly names the prerequisite tool (asterwise_get_natal_chart) and explains why it should be called first: to identify planets needing support. It also names two similar-sounding tools and clarifies why they are not appropriate, giving the agent explicit selection 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, idempotentHint, and non-destructive behavior. The description adds genuinely useful context beyond that: it discloses the sequential two-endpoint composition and warns that the return is a wrapper with nested branches, not a flat data.* root. It stops short of describing failure modes if one upstream call fails, so not a 5.

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

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

Front-loaded with the core behavior, then cleanly sectioned into WORKFLOW, INPUT CONTRACT, and DO NOT CONFUSE WITH. Slightly verbose with the doc link and the dict-typing shorthand, but every section earns its place for a composite tool.

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 an output schema exists, the description need not explain return values, yet it still clarifies the wrapper shape consumers must navigate. Combined with workflow ordering and sibling disambiguation, an agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100%, including a careful note that time is required with no sunrise fallback. The description adds nothing parameter-specific beyond 'one BirthData', so the schema is doing all the work and 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 composite behavior: it calls the atmakaraka and ishta-devata endpoints sequentially and merges them into top-level objects for one BirthData. This is a precise verb+resource statement that an agent can distinguish from every sibling, including the near-neighbors it explicitly names.

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?

Provides explicit WHEN context (BEFORE: RECOMMENDED asterwise_get_natal_chart; AFTER: None) and a DO NOT CONFUSE WITH section that names two alternatives and states why each is different (general chart, karaka-based timing). This is about as complete as routing guidance gets.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: exact start/end times in local and UTC, day-count bounds, timezone-driven civil-day definition, default source timezone, and the interpretive system used (Muhurta Chintamani). It omits error handling, but defers to a documentation link.

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

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

Front-loaded purpose sentence, then labeled blocks (WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH) that are scannable. Slightly dense and verbose given the schema already carries parameter detail, but every section has a clear function.

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?

Covers purpose, sequencing, parameter contract, and sibling disambiguation, and an output schema exists so return values need not be explained. Only gap is behavior on failure/limits, which is punted to an external URL.

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

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

Schema description coverage is 100%, so the baseline is 3. The INPUT CONTRACT mostly restates schema facts (defaults, ranges, IANA format) rather than adding new semantics; the only mild value-add is clarifying that target_timezone defines the civil days.

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: computes Tarabala and Chandrabala for any date, plus the Moon's star/sign change times for 1-31 civil days. It enumerates the outputs (nakshatra spans, tara from birth star, Moon house with chandrabala verdict) and cites the source text, so it is unmistakable against siblings.

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

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

Explicit workflow (BEFORE: get_natal_chart for the birth Moon star; AFTER: get_vedic_daily_factors) plus a DO NOT CONFUSE WITH block naming two alternatives and the distinguishing criterion for each. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to restate those. It adds valuable context such as the exact-slug requirement, the output/error contract link, and the distinction from bulk/random card tools. This is appropriate given the strong annotation coverage.

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 structured with clear sections: summary, workflow, input contract, disambiguation, and docs link. The major arcana list is long but genuinely useful for exact-slug lookup. The workflow section is arguably unnecessary because it just says 'None', but overall the description remains well-organized and purposeful.

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 two parameters, one required, full schema coverage, an output schema, and annotations covering safety/idempotency, the description covers the remaining needs: valid values, disambiguation from siblings, and a reference to the full output/error contract. Nothing important is missing for an agent to correctly invoke this tool.

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?

Input schema coverage is 100%, so the baseline is already strong. The description adds value beyond the schema by providing an extended list of valid Major Arcana slugs, a clear Minor Arcana pattern, and explicit 'must be exact' guidance. This helps an agent construct valid card_id values without trial and error.

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 returns full structured data for a single card identified by slug ID, which is a specific verb-resource pairing. It also explicitly distinguishes itself from siblings like asterwise_get_tarot_cards and asterwise_draw_tarot_cards, making its purpose 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 gives concrete use cases (card detail pages, single-card lookups, post-selection display) and explicitly names alternatives not to confuse it with, including when to use those alternatives. This is explicit 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.