Vedara: Vedic astrology

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

Adds real context beyond the annotations: the output is 'structured calculations, not deterministic life outcomes', and there is an explicit failure-mode instruction to ask the user rather than substitute another place. Annotations declare openWorldHint=true, so the geocoding dependency and its failure path are the right thing to disclose. Minor gap: no note on cost/latency of the external place lookup.

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 and scope come first, followed by the output caveat, then place/coordinate handling rules. Every sentence carries operational value, though the coordinate warnings overlap with the schema's own repeated 'never guess coordinates' text and could be trimmed once.

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 correctly does not enumerate return values and instead sets expectations about their nature. It covers the main ambiguity (place vs. coordinates resolution) for a nested-object tool; only the 'language' parameter and precision requirements on birth time go unaddressed.

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 description reinforces the critical constraint that latitude/longitude must be verified and place should be city/region/country, which meaningfully shapes how the nested birth object is filled. However, the top-level 'language' parameter and the date/time/timezone fields get no mention in the description, leaving partial coverage of a two-parameter but deeply nested 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?

States a specific verb (analyze) and names the three exact resources it evaluates: Manglik/Mangal dosha, Kaal Sarpa, and Sade Sati. This cleanly separates it from siblings like compute_chart, check_compatibility, or get_dasha_timeline, which handle different chart operations.

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 by 'for supplied birth data' and the place-resolution retry instruction, but the description never states when to pick this over compute_chart or get_dasha_timeline. The only explicit routing guidance concerns what to do when a place fails ('ask the user to clarify it before trying another tool'), not when to use this tool at all.

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 goes beyond the annotations by disclosing what the result contains (Moon, Lagna, chart positions, dosha flags) and by imposing a non-deterministic-advice framing rule that annotations cannot express. Annotations already cover safety and openness (readOnlyHint=false, openWorldHint=true), so no contradiction and no major undisclosed behavior remains.

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 core purpose is front-loaded in the first clause, and every following sentence is a constraint rather than filler. It is slightly verbose in that the 'never guess coordinates' / 'ask the user to clarify' rules are repeated from the schema, but no sentence is genuinely wasted.

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

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

An output schema exists, so return values need no prose. However, for a nested two-person schema where place, latitude, longitude, and timezone are all optional, the description never states that a location (place or coordinate pair) is effectively required — an agent could call with only date and time and silently produce degraded output. The undocumented `language` parameter is a further gap.

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

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

The description's parameter guidance ('Use city, region and country', 'only verified latitude and longitude', 'never guess coordinates') largely restates what the schema properties already say in detail. It adds nothing about the otherwise completely undocumented `language` parameter, and nothing about the relationship between place and coordinates when both are absent.

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 gives a specific verb and resource ('Calculate traditional 36-point Ashtakoot ... compatibility') plus the aliases (Guna Milan, Kundli matching) and the output scope (Moon, Lagna, chart positions, dosha flags). It is clearly a two-person synastry tool, distinct from siblings like compute_chart or analyze_doshas which operate on a single chart.

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

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

It gives concrete operational instructions: use city/region/country for a place, ask the user to clarify an unresolved place rather than retrying another tool with the same input, and never guess coordinates. It also sets a framing constraint ('Do not frame the score as a command to start or end a relationship'). What it lacks is explicit routing versus siblings such as compute_chart, so it is clear context without named 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 only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds real context beyond that: the returned sections, the opt-in include blocks, and a consent requirement before transmitting birth data. It omits any statement about resolution/ambiguity of place results or rate limits, keeping 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?

The purpose, inputs and output sections are front-loaded and nearly every clause adds actionable information. It is dense as a single block and repeats the 'never guess coordinates' rule twice (also in schema), a minor redundancy.

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

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

For a nested-parameter, open-world computation tool with an output schema, this covers what to supply, what is returned, opt-in sections, and the consent constraint. Only the language parameter and any behavior on place-resolution failure inside this tool (as opposed to the retry warning) go unaddressed.

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 reported at 0%, so the description must carry parameter meaning, and it largely does: it explains the place-vs-coordinates choice, the never-guess rule for lat/long, and the meaning of each include enum value (D9 Navamsa, D10 Dasamsa, Raja/Dhana yogas, Shadbala in rupas). The language and timezone parameters are not addressed in the description, leaving a gap.

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 (calculate) and resource (Lahiri sidereal natal chart) and disambiguates with synonyms (Kundli, Kundali, Janam Kundali) plus the three required inputs. It is clearly distinguishable from profile-based siblings like get_my_chart because it computes from supplied birth details.

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 when-to-use conditions: only after the user agrees to share birth details, prefer city/region/country, and clarify an unresolved place before retrying in another tool. It does not name get_my_chart as the alternative for saved-profile users, so the routing is clear but not exhaustive.

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?

Rich beyond annotations: discloses the empty-result behavior (empty_state with classical delay explanation, next_good, 14-day lookahead within the Timing horizon, fallback suggestion), the closed-world operation (saved/supplied coordinates only, no geocoding or publishing), and that auth/audit/rate limits apply. It does not explain why readOnlyHint=false despite being a 'find' call, leaving that inference to the audit-events mention.

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 first sentence is front-loaded and precise, but the description then spends substantial length on return-value details already covered by the output schema and on a list of negative capability statements (no geocoding, web search, external recipients, publishing) that could be condensed.

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 prerequisites, date format, range bound, and empty-result handling, which is enough to invoke correctly for a 5-parameter tool with an output schema. The remaining gaps are the undocumented language and include_neutral parameters, which materially affect results.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies date_start/date_end format (YYYY-MM-DD), the 32-day range limit, and that activity is a 'named Vedara activity', but it never explains language or include_neutral, leaving two of five parameters undocumented 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 and resource ('Find personalized Muhurta windows') for a named activity, plus the scoping constraint (max 32-day inclusive range) that separates it from siblings like get_my_timing and list_timing_activities. An agent can identify the task 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?

Gives clear preconditions: a connected Vedara account with a completed birth profile, and a bounded date range. It does not explicitly say when to prefer a sibling such as get_my_timing or list_timing_activities, so the routing is only implied by the activity-based framing.

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 only declare the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false); the description adds real behavioral constraints the annotations don't carry: end-exclusive range capped at 1096 days, a 90-day default when only from_date is given, depth bounded 1-20, and a place-disambiguation protocol. It does not say what happens when the range or depth limits are exceeded, which keeps it below 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 what is computed, then constraints, then input-hygiene rules, with no filler sentences. Some of the input-hygiene text ('Use city, region and country for a place', 'never guess coordinates') restates what the schema's property descriptions already say, which is mild redundancy.

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

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

An output schema exists, so return values need no explanation, and the description covers the computation, the bounded date-range behavior, depth limits, and the place/coordinate resolution rules an agent must follow. For a 5-parameter calculation tool this leaves only trivial gaps (language, depth default meaning).

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?

Reported schema coverage is 0%, so the description must carry parameter meaning, and it largely does: from_date/to_date format (YYYY-MM-DD), overlap semantics, the 1096-day cap and 90-day default, the 1-20 depth bound, and the city/region/country versus verified lat/long distinction. The 'language' parameter and the meaning of depth's default of 9 are left unexplained.

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 ('Calculate the current Vimshottari mahadasha and a bounded timeline of planetary periods from supplied birth data') and adds the sub-period depth (antardasha, pratyantardasha). This clearly separates it from sibling timing tools like get_my_timing or find_auspicious_time.

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?

Frames the tool as 'the starting point for career and relationship timing questions,' which tells the agent when to reach for it, and gives explicit operating rules for ambiguous places ('ask the user to clarify it before trying another tool with the same place'). It stops short of naming which sibling to use for follow-up work (e.g. find_auspicious_time), so no explicit alternative routing.

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 substantial behavioral context beyond annotations: no exposure of stored birth details or internal identifiers, no public geocoding/web search/external recipients/public publishing, and private auth/audit/rate-limit operations. However, the claim about 'explicitly supplied coordinates' is not supported by the input schema and may mislead about available inputs.

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 purpose and then lists optional include sections, so it is generally well structured. It is somewhat long and includes a potentially inaccurate coordinate clause, but the length is mostly justified by privacy and account-boundary constraints.

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 fully explained, and the description still covers the major chart sections and optional includes. The main gaps are the unexplained language parameter and the unsupported 'explicitly supplied coordinates' phrase.

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 0%, so the description must compensate. It does explain the include values well — divisional_charts (D9/D10), yogas, and planet_strength — but it says nothing about the language parameter, leaving one of two params undocumented.

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

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

The description states a specific verb and resource: return the connected user's saved sidereal birth chart (Kundli). It also scopes the operation with privacy constraints and optional sections, which distinguishes it from siblings like compute_chart and share_chart.

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

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

It gives clear prerequisites: a connected Vedara account with a completed birth profile, and it operates only within the user's bounded private account. It does not explicitly name when to use this versus compute_chart or other siblings, so it falls short of full alternative-routing guidance.

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

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

With annotations already declaring openWorldHint=false and destructiveHint=false, the description adds meaningful context: account requirements, private-account operation, authentication/audit/rate-limit behavior, and explicit exclusions for geocoding, web search, external recipients, and publishing. It does not explain the readOnlyHint=false annotation, which is somewhat surprising for a get-style operation, but it does not clearly contradict 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 purpose is front-loaded in the first sentence, and the remaining sentences add prerequisites, privacy boundaries, and operational constraints. It is somewhat dense and repeats the private-account idea, but the length is defensible for a tool with account and data-boundary constraints.

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?

Because an output schema exists, the description need not explain return values in detail. It covers account prerequisites, privacy scope, data sources, and excluded behaviors well. The main remaining gap is the undocumented language parameter.

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?

There is one parameter, language, and the schema description coverage is 0%. The description does not mention language at all, so it provides no guidance on what the parameter controls, whether it affects response language, or what null/default means. It therefore fails to compensate for the low schema coverage.

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

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

The description states a specific verb and resource: it returns the connected user's current Vimshottari period plus a sidereal transit snapshot, including transits to natal houses and current antardasha/pratyantardasha. That is much more specific than the name alone. However, it does not explicitly distinguish this tool from close siblings such as get_dasha_timeline or get_transits_to_chart.

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

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

The description gives useful prerequisites and boundaries: a connected Vedara account with a completed birth profile, saved or explicitly supplied coordinates, and no public geocoding or external publishing. It does not say when an agent should choose this tool over siblings like get_dasha_timeline, get_transits_to_chart, or today_for_me, so usage is only implied.

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

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

The description frames the tool purely as data retrieval ('Return ...'), yet annotations declare readOnlyHint=false and idempotentHint=false, so an agent cannot tell whether the call has side effects or produces differing results across invocations. The description does add the useful defaulting rule (today in UTC), but it discloses nothing about side effects or repeat-call behavior to reconcile the non-read-only annotation. Has an output schema, so return format need not be described.

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

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

Two sentences, front-loaded with the resource definition, followed by the defaulting rule. No filler, no repetition of the title.

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

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

The output schema covers the return value and the default behavior is stated, so the basics are present. But with 0% schema description coverage across three parameters, omitting 'language' entirely and giving no date format leaves an agent guessing on inputs for a tool whose annotations also raise side-effect questions.

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 0%, so the description must carry the load; it explains that location_timezone is an IANA timezone and that date defaults to today in UTC, which adds real meaning beyond the bare schema defaults. It never mentions the 'language' parameter at all, and gives no accepted date format, leaving a third of the surface undocumented 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: it returns sidereal planetary signs and nakshatras (gochar/transit sky) for a date and timezone. Domain terms are clarified parenthetically, so the resource is unambiguous. It does not differentiate itself from the closest sibling, get_transits_to_chart, which also concerns planetary positions, leaving the agent to infer that this is a chart-independent sky snapshot.

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 by 'now'/'current gochar' and the defaulting behavior ('defaults to today's date in UTC'), so an agent can infer this is a snapshot call rather than a chart-based analysis. However, it names no alternative and gives no conditions for choosing it over get_transits_to_chart or today_for_me, so the routing decision 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 carry the safety profile (destructiveHint=false, openWorldHint=true), and the description usefully adds the UTC-today default and the hard error on unresolved places. However, readOnlyHint=false is left unexplained by a description that reads as a pure computation, so an agent gets no signal about what side effects or external lookups occur.

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

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

Three front-loaded sentences, each carrying real information (output content, defaults, input modes, error behavior). The enumeration of return fields is slightly redundant given an output schema exists, but nothing is wasted.

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

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

Given an output schema exists, the description covers the essentials an agent needs: date default and format, timezone expectation, birth-data input modes, and failure behavior. Gaps are the unexplained language/location_timezone parameters and the noon-at-which-location convention used for transit computation.

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?

Top-level schema coverage is reported at 0%, and the description compensates for the important ones: date format YYYY-MM-DD, IANA timezone, and birth accepting a place name or verified coordinates. The 'language' and 'location_timezone' parameters are never mentioned, so two of four top-level params remain semantically opaque.

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

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

States a specific verb and resource: 'Return gochar transits at local noon for a date ... mapped to natal houses from the Ascendant and Moon.' The natal-chart mapping plus graha drishti/retrograde output clearly separates it from sky-only siblings such as get_sky_now or compute_chart.

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

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

Usage context is implied by the required 'birth' payload, so an agent can infer this is the personalized timing tool, and the error-on-unresolved-place rule helps. But it never explicitly says when to prefer this over get_sky_now, get_my_timing, or find_auspicious_time, nor whether birth profile storage is a prerequisite.

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 useful context beyond annotations: the result is a complete enumeration of searchable activities, and its ids are the valid input vocabulary for find_auspicious_time. It does not address the notable mismatch that readOnlyHint is false for what is described as a pure listing call, nor whether the list is static or server-dependent.

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

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

Two sentences, zero waste: the first defines scope and return shape, the second gives the call sequencing. Front-loaded and immediately actionable.

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 the description needn't explain return values, and it already names the key fields anyway. The only missing piece an agent would want is what 'language' changes and whether the activity set is stable across calls.

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 0% for the single optional parameter 'language', and the description never mentions it, so an agent gets no signal that it controls the language of the label/aliases. With only one param the baseline would be 4, but the complete silence on that param leaves a real gap.

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 ('List every activity Vedara can search auspicious timing for') and enumerates the returned fields (id, label, category, aliases). It is clearly differentiable from the sibling find_auspicious_time, which consumes rather than produces this list.

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

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

Gives an explicit ordering rule: 'Call this before find_auspicious_time and pass one of the returned ids as the activity.' That names the alternative, the sequencing, and the hand-off value, 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?

Goes well beyond the destructiveHint=true and idempotentHint=false annotations by disclosing exactly what is overwritten (partial birth details) and the downstream side effects (cleared cached calculations, recalculation started). It also states the human-confirmation requirement, which is real behavioral context an agent cannot get from annotations.

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

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

Three sentences, all front-loaded: what it saves, the preconditions, then the destructive side effects. Not one sentence could be dropped without losing routing or safety 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?

An output schema exists so return values need no explanation, and the dangerous-write profile is fully covered. The remaining gap is that optional geo/timezone parameters go entirely unaddressed despite affecting the correctness of what gets stored.

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 0%, so the description carries the burden, and it does clarify the four required fields and the confirmed_profile_write consent semantics. However, birth_timezone, birth_latitude, birth_longitude, and language are never mentioned, leaving half the parameters with no explanation of when or why to supply them — significant for an astrology tool where geo/timezone data drives accuracy.

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

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

Names a specific verb and resource combination (save a complete birth date, time, and place to the user's Vedara account) plus a precondition (no complete profile already saved). This clearly separates it from read tools like get_my_chart, though it never names the obvious create-vs-update sibling, update_my_birth_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?

Gives an explicit triggering condition ('when no complete birth profile is already saved') and a hard consent gate ('requires confirmed_profile_write to be true after confirming the exact details with the user'). It stops short of naming update_my_birth_profile as the alternative for the already-populated case, leaving that inference to the agent.

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

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

Goes well beyond the annotations by disclosing the irreversible public exposure: the page shows the chart, an optional first name, birth date and place, and explicitly never the birth time or coordinates. That privacy contract is exactly the kind of context annotations (readOnlyHint=false, openWorldHint=true) cannot convey.

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

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

Two sentences, zero waste. The capability and the returned link come first, then the privacy contract and the consent gate, so the most decision-relevant facts are front-loaded.

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

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

With an output schema present, the return value needs no elaboration, and the description still summarizes it as a keepable link. Privacy, consent, and published-vs-hidden fields are covered; missing only the language parameter's effect and whether a published page can be revoked or expires.

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?

Top-level schema coverage is 0% (name, birth, language carry no descriptions), though the nested birth fields are documented in-schema. The description adds real meaning by clarifying that name is optional and published, and that time and coordinates are inputs but not displayed; it says nothing about the language parameter or how partial coordinate input is handled.

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 chain (calculate a Lahiri sidereal natal chart) and a concrete output (a public Vedara page plus a shareable link), which cleanly separates it from compute_chart and get_my_chart. An agent can tell this is the only tool that produces a publicly viewable artifact.

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?

"Use only after the user explicitly asks for a sharable link and agrees the chart will be publicly viewable" is a clear gating precondition, including a consent requirement. It stops short of naming the non-sharing sibling (compute_chart) as the fallback when the user has not consented.

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

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

Goes well beyond annotations: it discloses the trust boundary (no public geocoding, web search, external recipients, or publishing), states that authentication/audit/rate limits are private account operations — which explains why readOnlyHint is false for a facts lookup — and explicitly says interpretation is not produced here. A minor tension remains between "deterministic" output and idempotentHint=false, which is not reconciled.

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 payoff ("What should I know about today: return raw deterministic Panchanga...") before the constraints, and every clause carries information. The closing sentence on auth/audit/rate limits is somewhat boilerplate but is short enough to earn its place as a boundary statement.

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 output schema covers return values and the prerequisite is stated, so the essentials are present. However, for a 5-parameter tool with zero schema descriptions, the description leaves the coordinate-vs-saved-profile precedence, date defaults, and language behavior entirely undocumented.

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 0% and none of the five parameters are named or explained. "Uses saved or explicitly supplied coordinates" weakly implies latitude/longitude and that saved values are a fallback, but date, language, and location_timezone are never addressed, including whether an explicit date overrides "today".

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

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

Names a specific verb and a concrete set of resources: raw Panchanga, caution windows (Rahu Kaal), Tara/Chandra Bala, and dasha facts for the connected user's day. It never explicitly contrasts itself with the near-identical sibling get_my_timing, so an agent still has to infer which of the two to pick.

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 one hard prerequisite ("Requires a completed saved Vedara birth profile") and a scope restriction (connected user's bounded private account), and delegates interpretation to ChatGPT. But with siblings like get_my_timing, find_auspicious_time, and get_dasha_timeline in the same domain, it offers no when-to-use-this-instead 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?

Adds real behavior beyond the annotations: it discloses that cached calculations are cleared and recalculation is started, which explains the destructiveHint=true and non-idempotent consequences in user-facing terms. It also surfaces the confirmation prerequisite, though it doesn't say whether prior values are recoverable after the overwrite.

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

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

Three short sentences with zero padding: what changes, the precondition, then the side effect. The destructive consequence is front-loaded rather than buried, which is the right ordering for a write 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?

Output schema exists so return values need no explanation, and the caching side effect plus confirmation gate are covered. Gaps remain for a destructive 8-parameter mutation: the relationship to save_my_birth_profile, whether optional coordinates/timezone are derived from birth_place, and whether omitted optional fields are nulled or preserved.

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 0% across 8 parameters, so the description must carry the burden; it names birth_date, birth_time, birth_place and the confirmed_profile_write gate, but says nothing about language, birth_latitude, birth_longitude, or birth_timezone. Half the parameters, including the coordinate/timezone fields that determine chart accuracy, are left undefined.

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 (Update) and resource (the birth date, time, and place stored in the connected user's Vedara account), with a scope word ("complete") that signals full replacement rather than partial edit. It does not, however, distinguish itself from the sibling save_my_birth_profile, which reads as an overlapping write of the same fields.

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 one concrete gating rule: confirmed_profile_write must be true after confirming the exact details with the user, which tells the agent a user confirmation step is mandatory. It gives no guidance on when to use this instead of save_my_birth_profile, nor what to do when only some birth details need correcting.

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