AVnester — Indian Real Estate Intelligence

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds value by clarifying it is 'deterministic math; not advice or a loan-approval claim' and mentions the response includes assumptionNote and disclaimer, which goes beyond what annotations provide.

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 concise with 5 sentences, each serving a purpose (purpose, nature, usage modes, output hint). It is front-loaded with the main action and free of unnecessary words.

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 (4 parameters, output schema present), the description covers the two modes, mentions response fields (assumptionNote, disclaimer), and specifies geographic context (India). It is complete 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?

Schema description coverage is 100%, so the baseline is 3. The description reiterates the mode distinction (propertyValue vs loanAmount) but adds no substantial new meaning beyond what the schema already explains about each parameter.

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 it estimates monthly home-loan EMI for India, using specific verbs like 'estimate' and defining resource as 'home-loan calculator'. It distinguishes from sibling tools by specifying it's for EMI calculation, not comparisons or other fees.

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 states when to use it ('what would my EMI be' / 'monthly payment on …') and explains the two modes (propertyValue or loanAmount). While it doesn't list when not to use or directly compare to siblings, the context is clear given the sibling names.

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 significant behavioral context beyond annotations: 'Pure deterministic math — no advice, no loan-approval claim' and 'Always surface the disclaimer field.' Annotations already indicate readOnly/idempotent/non-destructive; description enriches with operational constraints.

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, front-loaded with purpose, no unnecessary words. Each sentence earns its place: purpose, usage guidance, and output summary with disclaimer note.

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

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

Despite 6 parameters and required outputs, the description covers all key aspects: what it compares, when to use, what it returns (including disclaimer). Output schema exists so return values are further detailed; description provides sufficient high-level completeness.

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

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

Schema coverage is 100%, so each parameter is described in the schema. Description does not add further parameter details but summarizes outputs. Baseline score of 3 applies as description adds no extra parameter meaning.

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 clearly states it compares staying vs. transferring a home loan, lists what it returns, and explicitly says when to use it (user asks about switching/refinancing). Distinguishes from siblings like simulate_loan_prepayment.

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 usage context: 'Use when the user asks...' and clarifies it is pure math with no advice/approval. Lacks explicit when-not-to-use or alternative tools, but context is sufficient.

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, openWorldHint, and idempotentHint. The description adds value by disclosing scope restrictions (only Coimbatore/Chennai), the supported=false response for out-of-scope cities, and the need to surface scopeMessage. This goes beyond what annotations provide, though it doesn't detail the full output structure (covered by 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 description is three sentences, each earning its place: purpose, usage trigger, and scope/alternative handling. It is front-loaded and free of fluff, providing maximum information in a compact format.

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 is complete for a comparison tool with rich schema and output schema. It covers the supported cities, the scope behavior, and the key alternative tool. Nothing essential is missing given the structured fields already provide parameter details and output schema.

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

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

Schema description coverage is 100%, with each parameter already described in detail. The description adds minimal parameter-specific insight beyond mentioning '2–3 localities' which is already encoded in the schema's minItems/maxItems. It does not introduce new meaning for city or propertyType, so baseline 3 is appropriate.

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

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

The description clearly states the tool compares 2–3 localities side-by-side with specific aspects (price trends, livability, investment grade, etc.) and names the cities (Coimbatore/Chennai). It explicitly distinguishes itself from compare_properties, making its purpose unambiguous and distinct from 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 description provides explicit when-to-use guidance ('X vs Y' or 'which is better' for buying/renting) and an alternative (use compare_properties for listing comparisons). It also defines behavior for out-of-scope cities (return supported=false and surface scopeMessage), giving clear conditions for use.

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 (readOnly, openWorld, idempotent, non-destructive), the description adds important behavioral context: unknown IDs return 'not_found_or_unpublished', geographic coverage (Coimbatore and Chennai), output semantics (pricePerSqft, vsCheapestPercent, vsLargestAreaPercent), and a user-facing requirement ('Always surface the disclaimer'). This significantly enriches the agent's understanding of the tool's behavior.

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 compact yet information-dense, with each sentence adding value: purpose, prerequisite, edge-case handling, output fields, scope, and limitations. It is front-loaded with the core function and avoids redundancy, making it easy to process.

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 key contextual aspects: prerequisites, error behavior, geographic scope, output semantics, selection strategy for many candidates, and a disclaimer requirement. Given that an output schema exists, the description need not repeat return types, but it still adds meaningful context like 'not_found_or_unpublished' and the meaning of comparative percentages, making it highly 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?

The schema fully describes the only parameter (listingIds), including its purpose, constraints, and source (from search_properties). The description adds little beyond restating that IDs are not guessable and listing the count range, which the schema already covers. With 100% schema coverage, a score of 3 is appropriate—the description doesn't introduce new parameter semantics.

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: 'Compare 2–5 AVnester listings by listingId, side-by-side.' It specifies the verb (compare), resource (AVnester listings), and method (by listingId, side-by-side), distinguishing it from siblings like search_properties (which returns listings) and compare_localities (which compares localities).

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: 'Get IDs from search_properties first (not guessable)' establishes a prerequisite and alternative. It also addresses when not to use the tool ('Does NOT recommend a purchase') and how to handle over 5 candidates ('pick the most relevant 5... and say so'). This clearly instructs when and how to invoke the tool, including exclusions.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive. Description adds behavioral details: handling of states outside India (supported=false), GST itemization based on constructionStatus, and buyer-gender concessions. 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?

Four sentences, no wasted words. Front-loaded with purpose, then key features, special case, and disclaimer. Each sentence contributes meaning.

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 8 parameters, 100% schema coverage, and existence of output schema, the description covers main functionality, edge cases (supported=false for non-India), and offers a customer-facing disclaimer. Could mention rateBasis set but is implied. Complete enough.

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 is 3. Description adds value by explaining the effect of parameters (e.g., 'urban/rural overrides', 'commercial/agricultural multipliers') and provides a usage hint for constructionStatus to get GST. This goes beyond 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 clearly states it estimates Indian state stamp duty and registration charges, using specific verb 'Estimate' and resource 'stamp duty + registration'. It distinguishes from siblings like calculate_home_affordability or compare_properties by focusing on statutory charges.

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?

Description provides context for usage (property purchase in India) and includes a disclaimer ('Always surface the disclaimer'), but does not explicitly state when not to use this tool or compare with alternatives among 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 indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: out-of-scope cities return supported=false, the need to surface scopeMessage, and the requirement to always surface the disclaimer field when returning livability/investment grade. This goes beyond the annotations and helps the agent handle edge cases.

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 concise, front-loaded with purpose, then usage trigger, then edge-case handling, then a mandatory caveat. Every sentence earns its place; no redundant wording or fluff.

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

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

Given the presence of an output schema and rich annotations, the description covers all necessary context: what the tool returns, when to invoke it, how to handle unsupported cities, and an important user-facing requirement (disclaimer). It is complete for an AI agent to select 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?

Schema coverage is 100% with both parameters having descriptions, so baseline is 3. The description adds semantic value by specifying that city must be Coimbatore or Chennai (not just any Indian city) and that locality is a neighborhood within those cities. This clarifies the expected values beyond the generic 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 uses a specific verb ('Get') and resource ('aggregated insights for a locality'), and enumerates the exact output components (avg price, supply count, demand pulse, livability/investment grade, etc.). It clearly scopes to Coimbatore or Chennai localities, distinguishing it from sibling tools like compare_localities or search_properties by its focus on single-locality insights.

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 when to use: 'Use when the user asks "what is X locality like" about a neighborhood in either city.' It also provides handling for out-of-scope cities (supported=false, surface scopeMessage). However, it does not explicitly contrast with sibling tools or state when not to use it, though the trigger phrasing implicitly differentiates it.

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?

Given annotations already declare readOnly/openWorld/idempotent, the description adds substantial behavioral context: it produces a single verdict that is 'indicative', combines multiple financial components, and explicitly disclaims loan approval status. It also discloses the need to surface a disclaimer, which is not in 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 dense but compact, using a long first sentence to enumerate key computations, then clear mode separation and disclaimers. No filler words; every clause adds information. Slightly long but appropriate for the tool's complexity.

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 does not need to explain return values. It covers purpose, modes, disclaimers, indicative nature, and key computation components, which is comprehensive for a 21-parameter tool. The schema already handles individual parameter details, so the description fills the conceptual gaps (modes, exclusions) effectively.

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 covers 100% of parameters, so baseline is 3. The description adds value by framing how parameters are grouped into Mode A (listingId) vs Mode B (propertyValue + state), and by explaining that cash-to-close includes itemized GST and stamp duty components, which helps the agent understand which parameters matter in each mode.

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 starts with a specific verb ('Assess whether a buyer can afford') and clearly defines the output as ONE verdict with enumerated possible values. It distinguishes this tool by combining eligibility, EMI, cash-to-close, tax, and lender-fit triage, differentiating it from simpler sibling tools like calculate_home_affordability.

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 explicitly defines two mutually exclusive modes (listingId vs propertyValue+state) and provides clear constraints (e.g., 'any Indian state', 'Coimbatore/Chennai catalog'). It also states exclusions ('NOT a loan approval') and a required action ('Always surface the disclaimer'), giving usable when-to-use guidance without naming sibling 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses important runtime behavior: unknown/unpublished IDs return { listing: null, notFound: true } without throwing, purposely to avoid leaking existence. It also notes catalog coverage and that IDs are not guessable, which adds significant context beyond the structured 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 compact (three sentences) and front-loaded with the core purpose. Every sentence adds value: the first states the main function, the second gives prerequisite and sequence, the third explains edge-case behavior and scope. No wasted words.

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 simplicity (one parameter), the rich schema and annotations, and the presence of an output schema, the description is complete. It covers prerequisites, manual fallback (sourceUrl), geographic scope, and not-found behavior. Nothing important 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 already provides comprehensive parameter semantics with 100% coverage: it explains listingId is from search_properties, not guessable, and the trailing segment of sourceUrl. The description repeats this guidance but adds no new parameter-level information beyond what the schema already documents, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool fetches full public details for one AVnester listing by listingId. It uses a specific verb ('Fetch') and resource ('AVnester listing'), and distinguishes itself from siblings by being the follow-up to search_properties for a single listing.

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

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

The description gives explicit usage context: get listingId from search_properties first, and use when the user references a specific listing. It also notes catalog coverage (Coimbatore and Chennai). However, it does not explicitly name alternatives for other use cases (e.g., compare_properties for multiple listings), so it lacks a full 'when-not or alternative' statement.

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 indicate readOnlyHint, idempotentHint, openWorldHint, non-destructive. Description adds that it is pure deterministic math, not tax advice, and lists modelled sections and exclusions. No contradiction.

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

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

Three sentences with no extraneous information. Front-loaded with core purpose, followed by usage guidance and behavioral notes. Every sentence serves a purpose.

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

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

Given 18 parameters, output schema exists, and annotations provide safety signals, the description covers the essential behavioral aspects: what is modelled, what is excluded, disclaimer requirement, and usage triggers. Complete for the complexity.

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% with full descriptions for all 18 parameters. The description does not add meaning beyond the schema for individual parameters, but it provides high-level context of what the tool computes. 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?

Description clearly states the tool compares OLD vs NEW tax regime for home-loan borrowers to recommend the cheaper one, using deterministic slab math. It distinguishes from sibling tools (none of which are tax calculators) by naming specific user queries and tax sections.

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 tells when to use: when user asks 'old or new tax regime', 'home-loan tax benefit', or 'section 80C / 24(b) deduction'. Lists what it does and does not model (capital gains, HRA, etc.), and reminds to surface disclaimer.

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?

Despite decent annotation coverage (readOnly, idempotent, non-destructive), the description adds valuable behavioral context: returns are sanitized listing cards with handoff URLs and per-listing verified flags, and seller contact details are intentionally withheld. The out-of-scope response format is also disclosed. This goes well beyond the annotations and informs the agent of critical output limitations.

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

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

The description is three sentences: purpose/scope, usage trigger, and behavioral notes. It is front-loaded with the core verb and resource, and every sentence provides actionable information without redundancy. No wasted words.

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 10 optional parameters and an output schema, the description covers the essential context: geographic constraint, when to invoke, output shape (sanitized cards, URLs, verified flag), a hard privacy boundary (no seller contact details), and fallback error handling for out-of-scope cities. The output schema handles return-value documentation, so the description is complete for selection and 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?

The input schema already describes all 10 parameters with 100% coverage, including enum values, defaults, and units. The description only ties usage to user mentions (locality, price band, BHK, transaction type), which is a selection hint rather than parameter-level detail. Since the schema carries the heavy lifting, the baseline of 3 is appropriate; the description adds a small amount of contextual mapping.

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: 'Search residential property listings in Coimbatore and Chennai, Tamil Nadu.' It specifies the resource (property listings), geographic scope, and includes an explicit usage trigger ('Use when the user names a locality, price band, BHK, or transaction type'). This distinguishes it from sibling tools that focus on comparison, details, or financial calculations.

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 'Use when' conditions, which is strong guidance. It also explains the out-of-scope behavior ('Out-of-scope cities return supported=false + supportedCities + scopeMessage — surface the scopeMessage'). However, it does not name alternative sibling tools or provide explicit 'when not to use' instructions, so it misses the top score.

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 indicate readOnlyHint, idempotentHint, destructiveHint. The description adds context: 'Pure deterministic math — no advice, no loan-approval claim,' which clarifies the tool's non-advisory nature. No contradictions.

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 concise with no redundant sentences. Each part serves a purpose: stating the function, clarifying it's a calculator, listing use cases, and summarizing modes and strategies.

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 (8 parameters, multiple modes), the description covers all key aspects: purpose, use cases, modes, strategies, and a usage instruction (disclaimer). An output schema exists, so return values need not be detailed.

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% (all parameters described). The description adds value by summarizing modes and strategies (e.g., 'Modes: one-time, recurring yearly...') and the comparison of reduce_tenure vs reduce_emi, which goes beyond the schema.

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

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

The description clearly states the tool simulates prepaying an Indian home loan early, lists specific use cases (e.g., 'should I prepay'), and describes modes and strategies. It is distinct from sibling calculators like 'calculate_home_affordability'.

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 lists when to use the tool (e.g., 'use for early/part/lump-sum repayment') and instructs to 'always surface the disclaimer field.' However, it does not explicitly state when not to use or compare to alternative tools.

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