Life-area timing: education

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

Annotations already declare this is a read-only, idempotent, closed-world call, so the description is free to explain mechanics, and it does: windows are cut at every Vimshottari period change and every Jupiter/Saturn sign change, each window carries score, components (dasha, transit, kp), fired rules, a basis and a source key. It also discloses the default minScore behaviour (only windows where at least one rule fired) and cites the K.N. Rao double-transit rule. It stops short of stating anything about runtime, pagination or cost.

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?

Purpose is front-loaded in the opening clause, then the computation, then the output shape, then the named classical rule. It is dense astrological vocabulary, but every sentence carries information and nothing is repeated verbatim from the schema beyond two short default 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?

With annotations covering the safety profile, a 100%-covered input schema and an output schema, the description only needs to explain the domain model, and it does so adequately, including what a window contains and how windows are delimited. Cost tier and any sense of result volume are absent, which is a minor gap for a 50-credit call.

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 body properties already document years (1-20, default 5), level (pratyantar default), fromDate and minScore. The description restates the years range/default and the pratyantar default for level without adding syntax or edge cases the schema lacks, 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: it produces education timing windows derived from the 4th/5th houses, their lords, Mercury and Jupiter, with the 9th supporting. The life-area focus (education) immediately separates it from the sibling timing tools for career, marriage, property and so on, and the KP group (4, 9, 11) pins down the technique.

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?

Usage is implied rather than stated: an agent can infer this is the tool for 'when will education-related events happen', and the span parameters (years, fromDate) frame the scan. It never says when to prefer the aggregate astroway_vedic_timing_all or a muhurat-style tool instead, and gives no prerequisites or exclusions.

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