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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, closed-world, so safety is covered. The description adds genuinely useful behavioral context by disclosing what is returned (koota-wise breakdown, total out of 36, Nadi/Bhakoot/Manglik dosha findings), though it says nothing about failure modes for malformed kundali input.

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?

A single compact sentence that front-loads the scoring system and the operation, then the inputs, then the return contents. No filler, no redundant restatement of the tool name.

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

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

With no output schema, the description does the work of explaining the return payload, which is the right call. Inputs are non-trivial nested kundali objects re-used from a sibling tool, and that dependency is stated. Only the handling of invalid or partial kundali input is left 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 description coverage is 100% and both parameters are documented there, including their provenance from calculate_kundali. The description's bride/groom mapping merely restates the schema's role labels, adding no syntax, format, or constraint detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource (Guna Milan/Ashtakoot compatibility), names the governing 36-point scoring system, and disambiguates from sibling calculate_kundali by declaring that tool's output as its input. An agent can identify the operation without opening the schema.

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

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

The description makes the usage context explicit by requiring kundali JSONs produced by calculate_kundali and pinning the bride/groom roles, so the agent knows the prerequisite step. It does not name a competing alternative or state when NOT to use it, so it falls short of a 5.

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 non-destructive behavior, so the safety profile is covered. The description adds that the return value is 'dasha JSON accepted by the report tools,' which is useful downstream context, but does not describe computational assumptions, required kundali shape beyond the schema, or handling of missing data.

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?

A single tight sentence front-loads the main computation and then lists the outputs and downstream use. It is appropriately sized, though the trailing clause about report tools could be slightly more integrated.

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 two-parameter, read-only computation tool with no output schema, the description covers what is computed, the time reference, and the output form. It does not need to explain return values beyond the mention that they are report-tool-compatible, so it is nearly complete.

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

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

Schema description coverage is 100%, so both parameters (kundali and on_date) are already documented in the schema with format and default details. The description only restates that on_date selects the running period, adding no new syntax or semantic constraints 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?

States a specific verb (compute) and resource (Vimshottari dasha timeline from a kundali), and enumerates the outputs (mahadasha and antardasha periods with start/end dates plus running periods). This distinguishes it clearly from sibling calculate_* tools like calculate_kundali or calculate_gochar, which produce different artifacts.

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?

Implies the tool is used to derive dasha periods from a kundali, but does not explicitly say when to use it versus generate_report_json or list_client_reports. The mention that the output feeds report tools hints at a workflow but does not give a when-not or alternative-selection rule.

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 context beyond that: it names the exact computational scope (natal Moon and Lagna) and the interoperability contract ('gochar JSON accepted by the report tools'), which tells the agent the output feeds other tools.

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 compact sentences, front-loaded with the core computation and followed by the return contract. 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?

There is no output schema, but the description characterizes the return value as gochar JSON consumed by the report tools, which is sufficient orientation. Minor gaps remain around prerequisite chaining and error behavior for a nested kundali input.

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 both parameters (kundali, on_date) are already documented in the schema, including the default of today. The description adds no format or syntax detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (compute) and resource (gochar planetary transits relative to natal Moon and Lagna), plus the Sade Sati/Dhaiya phase. It is clearly distinguishable from siblings like calculate_dasha, calculate_panchang, and calculate_kundali.

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

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

The description implies usage by noting the output is accepted by the report tools, which hints at downstream chaining, and the schema requires a kundali from calculate_kundali. However, it never explicitly states when to call this versus the other calculation tools or what the prerequisite ordering is.

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, and a closed-world scope, so the safety profile is covered. The description adds real value beyond that by disclosing the exact contents of the returned JSON and its role as a shared input for downstream tools, which is the key behavioral trait an agent needs here.

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 action and payload, with no filler. The output enumeration is dense but each listed artifact is decision-relevant, so it largely earns its place, though it could be trimmed slightly.

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

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

No output schema exists, and the description compensates by enumerating the return payload and stating which sibling tools consume it. Combined with 100% parameter coverage and clear annotations for a read-only computation, an agent has everything needed to call and sequence 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?

Schema description coverage is 100%, including formats for dob/tob, decimal-degree conventions for lat/lon, the IANA timezone requirement, the non-geocoded nature of place, and the ayanamsa enum with default — so the schema carries full parameter meaning. The description adds nothing beyond the vague phrase 'birth details', matching 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?

Specific verb (compute) plus resource (sidereal Vedic kundali/birth chart) and an explicit enumeration of the computed artifacts: lagna, Moon rashi, nakshatra with pada, planet positions, D9 and divisional charts, ashtakavarga, and the dasha seed. The closing sentence distinguishes it from siblings by naming the tools that consume its output (dasha, gochar, compatibility, report).

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 final sentence makes the usage context clear: this is the upstream generator whose JSON feeds calculate_dasha, calculate_gochar, calculate_compatibility, and the report tools, implying it must be run first. It does not explicitly exclude alternatives (e.g. parse_birth_details, calculate_panchang), so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds useful interop context (the JSON feeds the report tools) but says nothing about computation cost, ephemeris data requirements, or how partial/invalid dates are handled.

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 tight sentences: the computation scope and its outputs come first, the downstream integration second. Nothing is padded or redundant.

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

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

No output schema exists, but the description compensates by listing the returned Panchang components, so an agent knows what comes back. It does not describe the JSON's shape or nesting, which is the only remaining gap for a six-parameter computation 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?

Schema description coverage is 100%, so lat/lon/date/place/timezone_name/ayanamsa are all documented at the schema level. The description adds no parameter-level detail (e.g. how place relates to geocoding) beyond what the schema already states, 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 ('Compute') and a specific resource ('daily Panchang'), and enumerates the outputs (vara, tithi, nakshatra, yoga, karana, sunrise/sunset), which effectively separates it from calculate_kundali, calculate_dasha, and calculate_gochar. It stops short of explicitly naming which sibling to pick instead, so it is clear but not fully differentiated.

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 implied usage signal by noting the result is 'accepted by the report tools', routing the agent toward the report pipeline, and the scope is limited to a place and date. There is no explicit when-to-use versus calculate_kundali or when-not guidance.

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

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

Annotations declare idempotent, non-destructive behavior but readOnlyHint=false, so the description's disclosure that the result may be null is valuable return-shape context that annotations cannot supply. It doesn't explain the openWorldHint=false / local SQLite boundary or why the tool isn't flagged read-only, but no contradiction is 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?

One sentence, front-loaded with the matching precedence and ending with the null-result case. No padding or restatement 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?

There is no output schema, and the description correctly fills that gap by stating the return is a profile or null. What remains unstated (the profile's fields, substring-match ambiguity) is minor for a lookup tool with fully documented parameters.

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 baseline would be 3, but the description adds interpretation detail the schema lacks: that `query` is treated as an exact client_id in one path and a case-insensitive substring in the other. The db_path path restrictions are left to the schema, which already documents them fully.

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?

Specific verb ('look up') plus resource ('client profile') with the exact matching strategy spelled out. It is clearly distinguishable from siblings like save_client_profile and list_client_reports, which are write/list operations rather than a single-profile lookup.

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 defines the selection rule between two modes: exact client_id first, falling back to case-insensitive display_name substring. That is genuine usage guidance for picking a query form, though it does not name sibling alternatives or state when not to use 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?

The description discloses the action (writes PDF to disk, optionally records in SQLite) and the return value. Annotations show no destructive or read-only hints, and the description does not contradict them. However, it does not mention potential side effects like overwriting files or required permissions.

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

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

The description is a single sentence that front-loads the tool's purpose and key output. It is concise, but could be better structured to separate required and optional parts.

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

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

Given the tool's complexity (12 parameters, nested objects, no output schema), the description is relatively brief. It mentions the return value but lacks detail on error conditions, prerequisites beyond having a kundali, or the behavior of the optional sections.

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 parameters. The tool description adds context about the overall flow and mentions the renderer, but it does not significantly enhance understanding of individual parameters beyond the 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 description states a specific action (render a PDF report), lists key sections (cover, charts, planet table, dasha timeline), and identifies the input (kundali) and optional additions. It clearly distinguishes from sibling tools which perform calculations or data management.

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 implicitly indicates when to use this tool (to generate a PDF from a kundali) and mentions optional sections from other tools (dasha, gochar, panchang). However, it does not explicitly state when not to use it or provide alternatives beyond the implied prerequisite calculations.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description goes beyond them by disclosing the side effect (a JSON file is written to disk) and the returned record fields (report_id, path, client_id, created_at), which matters since no output schema exists. It does not explain non-idempotency, i.e. whether repeated calls create duplicate reports.

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, both load-bearing: the first covers the action and its output artifact, the second covers the return shape. Nothing is repeated from the title or 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?

For a 10-parameter write tool with no output schema, the description supplies the return fields and the disk-write behavior, and the schema covers all parameters. Remaining gaps are behavioral edge cases (file naming/overwrite behavior, duplicate-report behavior on repeat invocation) rather than anything needed to call it.

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

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

Schema description coverage is 100%, so the schema already documents path restrictions, enum values, defaults, and which inputs feed which report sections. The description adds only the high-level notion that dasha/panchang/gochar sections are optional; it introduces no syntax or format detail the schema lacks.

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 ('assemble ... and write it to disk as JSON') and resource ('structured astrology report draft'), and enumerates the sections it comprises. An agent can distinguish it from sibling generate_pdf_report purely from the text.

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 ('Assemble a structured astrology report draft'), and the schema hints at ordering by pointing at calculate_kundali/calculate_dasha/calculate_gochar/calculate_panchang outputs. However, it never says when to choose this JSON variant over the sibling generate_pdf_report, nor when to persist via db_path versus writing to disk only.

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 idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is largely covered. The description usefully adds that results are newest-first and enumerates returned fields, but it does not explain the notable readOnlyHint=false (an unusual signal for a listing tool) nor error behavior for unknown clients.

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

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

Two sentences, no filler, with the scoping and ordering constraint front-loaded before the return-field detail. Every clause carries 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 no output schema, the description compensates by describing the returned record shape (report_id, report_type, path, created_at), which is genuinely helpful. It omits potential pagination/limit behavior and handling of a client with no reports, leaving minor gaps for a low-complexity two-parameter 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?

Schema description coverage is 100%, and both parameters (db_path, client_id) are fully documented in the schema, including the path-resolution constraints. The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (list), resource (report records), scope (for a client), and ordering (newest first), plus the fields each record returns. It is clearly distinct from the generate_report/generate_pdf_report siblings, though it never names those siblings to reinforce the distinction.

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?

There is no guidance on when to use this versus alternatives (e.g., generate_report_json or generate_pdf_report), and no mention of prerequisites such as the client needing to exist or having prior reports. The agent must infer usage from the name alone.

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 (read-only, idempotent, non-destructive), so the description earns credit for adding behavior: it parses 'conservatively' (won't guess) and returns a 'missing' list of unparsed fields. With no output schema, this disclosure of the return contract is genuinely useful; it could go further on accepted input formats or how partial/ambiguous values are handled.

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

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

Two sentences, no filler. The extraction target list is front-loaded and the clarification rationale follows immediately, so an agent gets purpose and payoff in one pass.

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

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

For a single-parameter, read-only parser with no output schema, the description covers what is extracted, the conservative failure mode, and the shape of the return value (recognised fields plus a missing list). Nothing an agent needs to invoke 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% and there is only one parameter, so the schema already carries the semantics. The description adds only the framing that the note is 'short' and free-form, which is a marginal gain over the schema's own example — 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?

It names a specific verb (extract/parse) and enumerates the exact resource fields (dob, tob, place, lat, lon, timezone) from a clearly scoped input (a short operator note). This separates it cleanly from the sibling calculators, which compute results rather than parse free text.

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 establishes clear context: it operates on a short operator note and is meant to precede clarification ('so the agent can ask the operator for clarification instead of guessing'). It stops short of explicitly naming when to call this versus the calculate_* siblings, so no exclusions or alternatives are stated.

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 indicate destructiveHint=true and idempotentHint=true, and the description confirms upsert behavior and return of saved profile. However, it does not elaborate on what destructive actions occur (e.g., overwriting existing data) or any rate limits.

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

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

The description is a single sentence that covers key aspects (upsert, storage, optional birth details, return value) without any redundant or vague language.

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 essential behavior and return value, but lacks details on the format of the returned profile or handling of the db_path parameter. Given the absence of an output schema, a bit more detail on the return value would be helpful.

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 50%, and the description adds little beyond the schema: it mentions 'optionally with birth details' and implies db_path usage but does not describe parameter formats or constraints not already in the schema.

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

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

The description explicitly states it performs an upsert (create or update) on a client profile in the SQLite store, with optional birth details, and returns the saved profile. This clearly distinguishes it from sibling tools like parse_birth_details or calculation 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 mentions the upsert behavior and optional birth details but provides no explicit guidance on when to use this tool versus siblings like parse_birth_details or when not to use it.

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