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

Even with no annotations, the description fully discloses key behaviors: it consumes AI credits, is asynchronous, returns immediately with processing status, may return existing analysis with alreadyExists=true, force re-analyzes and re-consumes credits, and fails if no usable content exists. This exceeds transparency expectations.

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 comprehensive, with each sentence serving a distinct purpose: primary action, credit consumption, async/polling behavior, existing-analysis behavior, force behavior, and failure condition. 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 complexity (async, credit consumption, subtle id matching, conditional re-analysis) and the absence of an output schema, the description covers all necessary operational details. It provides a complete mental model for correct invocation and follow-up.

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

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

The schema already documents both parameters with 100% coverage, providing a baseline of 3. The description adds meaningful semantics beyond the schema: the id lookup order (ObjectId parse attempt followed by case number fallback), including the 404 edge case, and that force consumes credits again. This enriches parameter understanding.

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: 'Triggers AI analysis of a single case.' It distinguishes from siblings, notably 'analyze_consolidated_case' (consolidated cases) and 'get_case_analysis' (retrieval), by focusing on the triggering action and mentioning polling for results.

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

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

The description provides clear usage context: it explains the asynchronous flow, says to poll 'get_case_analysis' after 30-60 seconds, and describes when to set 'force' for re-analysis. It does not explicitly name alternative tools for excluding, but the implicit guidance is strong.

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 no annotations, the description carries full burden and does so thoroughly: synchronous blocking behavior, long timeout, cost implications, document count limits, force redo behavior, and failure conditions (no case number, no text content, exhausted credits). This is exemplary transparency.

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 every sentence provides necessary information: purpose, cost warning, sync behavior, scope, force option, and failure modes. No redundancy, well front-loaded with the primary verb and resource.

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 complexity, the description covers input semantics, behavior, and failure conditions comprehensively. However, with no output schema, it leaves the return format of the 'merged view' unspecified. It is still mostly complete as the output can be inferred from the purpose.

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. The description repeats the force behavior already in the schema and does not add additional meaning for id beyond what the schema provides. No extra semantic value beyond the structured fields.

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 a specific verb and resource: 'Runs AI analysis across ALL documents that share the given case number'. It distinguishes from sibling analyze_case by emphasizing consolidated scope and cost. The purpose is unambiguous.

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

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

Explicitly mentions the alternative analyze_case via cost comparison ('CONSUMES SIGNIFICANTLY MORE AI CREDITS than analyze_case'), implying when not to use this tool. Also gives case-type-specific scope (High Court vs Supreme Court), providing clear context. Lacks an explicit 'use this when' statement but it is inferred.

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?

No annotations are provided, but the description fully discloses behavior: no authentication required, no AI credits consumed, returns specific fields, and uses a different response envelope than 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?

Description is concise, front-loaded with the main purpose, and each sentence adds value. It covers usage context, behavior, and response details without waste.

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 simplicity of the tool (no params, no output schema), the description provides complete context: what it does, when to use it, what it returns, and how it differs from other tools.

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?

Tool has no parameters, so schema coverage is trivial. Description adds context by explaining that no key is needed, implying no input is required. Baseline for zero params is 4.

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

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

The description clearly states the tool checks API health and reachability. It distinguishes itself from sibling tools that deal with case data by focusing on connectivity.

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 it: to verify connectivity and diagnose API key configuration issues. It also notes that it works without a key, providing clear context for troubleshooting.

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 no annotations provided, the description carries the full burden and does it well. It discloses that no AI credits are consumed, explains the 50-result cap, inclusion criteria for timeline entries, and provides the return structure with status enums. This goes well beyond a basic 'finds related documents'.

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

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

The description is structured and every sentence earns its place. It covers purpose, exclusions, limitations, and return details without fluff, making it dense but immediately scannable.

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, so the description must explain the return value, and it does comprehensively: the relatedDocuments array with fields, timeline entries with statuses, inclusion criteria, and meta fields. This makes the tool fully usable without external documentation.

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

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

The schema description already fully covers the single parameter's format and lookup order (100% coverage). The tool description adds no additional parameter-specific semantics, 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 finds documents sharing the same case number and derives a procedural timeline. It distinguishes itself from semantic search, providing a specific verb and resource.

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 explains when not to use it (not similarity search) and directs users to semantic_search_cases for conceptually similar cases. This gives clear usage context and 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?

With no annotations provided, the description carries full burden. It thoroughly discloses the exact fields returned, the optional nature of metadata.diaryNumber, and explicitly lists fields that are NOT included. The 'without AI analysis' note clarifies the tool's non-AI behavior, which is beneficial for cost and latency expectations.

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 somewhat long due to the enumerated return fields, but the first sentence is concise and front-loaded. The field list is useful and not redundant; every sentence adds value. It could be slightly more compact but is well-structured.

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 has one parameter, no output schema, and no annotations, the description provides a complete picture: what is returned, what is excluded, the alternative tool, and the credit behavior. This is fully sufficient for an 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?

The schema already has 100% coverage for the single parameter id, including detailed lookup-order semantics. The description does not add additional parameter-specific meaning beyond what the schema provides, so the 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 states a specific verb+resource ('Fetches full details for one case') and clearly distinguishes itself from siblings by explicitly noting 'without AI analysis' and directing users to get_case_analysis for excluded fields. This leaves no ambiguity about what the tool does.

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 states 'No AI credits consumed' (a key differentiator) and gives a specific exclusion list with a direct pointer to the alternative tool: 'call get_case_analysis for those.' This is clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states that the tool is read-only, does not trigger new analysis, and does not consume AI credits. It also explains the behavior when analysis is absent (hasAnalysis false, message field) and that empty fields are omitted. This is thorough and transparent.

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

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

The description is front-loaded with the core purpose and then provides essential behavioral context. The long list of possible return fields is justified because there is no output schema, so the agent needs that information to understand potential responses. It is somewhat long, but every section earns its place.

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

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

Given the absence of an output schema, the description is exceptionally complete. It covers purpose, side effects, the uninitialized state and fallback action, and enumerates the full set of possible returned fields. It leaves no critical gaps for an agent to invoke the tool correctly and interpret the response.

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 fully describes the single `id` parameter, including the ObjectId/case number fallback logic. The description adds no parameter-specific meaning, but since schema coverage is 100%, the baseline of 3 is appropriate. The description's focus on return fields is useful but not directly about 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 opens with a specific verb and object: 'Reads any existing AI analysis for a case.' It clearly distinguishes this from sibling tools by emphasizing 'existing' and explicitly contrasting with analyze_case. The read-only nature is also stated upfront.

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 guidance on when to use this tool: to retrieve an already-generated analysis. It also specifies when not to use it: if hasAnalysis is false, the agent should call analyze_case instead. This direct alternative naming makes the usage boundaries highly clear.

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

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

With no annotations, the description carries full weight. It explicitly discloses that the URL is an encrypted presigned S3 URL that must not be fetched directly, expires after the returned expiresIn seconds, and returns 404 if no document exists. Also notes no AI credits are consumed, which is useful operational context.

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 and well-structured: it front-loads the core purpose, then presents a critical warning about the encrypted URL and expiration. Each sentence adds necessary value, with no filler or 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?

The description covers return behavior (pdfUrl and expiresIn), error case (404), encryption/decryption requirement, and expiration semantics. Given the complexity of the tool and lack of output schema, this is sufficiently complete for an agent to handle the tool correctly.

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

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

The input schema already has 100% coverage with a detailed description of the id parameter, including the ObjectId-or-case-number lookup order. The tool description does not add further parameter detail beyond what the schema provides, 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 returns a time-limited link to an official judgment PDF for a case. This distinguishes it from sibling tools like get_case or analyze_case, which serve different resources. The verb 'returns' and resource 'PDF URL' make the purpose unambiguous.

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

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

The description gives clear context for when to use the tool (retrieving a case PDF URL) and includes important usage warnings, but it does not explicitly name alternatives or exclusion criteria. The purpose is obvious enough to infer appropriate usage relative to 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?

With no annotations provided, the description carries the full burden. It discloses return fields (including conditional ones), the 404 error case, and states that no AI credits are consumed—providing meaningful behavioral context beyond the tool name.

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 and front-loaded with the main purpose. The list of return fields is slightly dense but earns its place by informing the caller of the response shape. 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?

The tool is a simple polling operation with one parameter and no output schema. The description covers purpose, return values, error behavior, and cost implications, which is quite complete. It could mention more about the 'result' field's format, but that is not essential for this polling 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?

The schema description coverage is 100% for the only parameter (requestId), and it fully explains its origin. The tool description adds no new parameter semantics 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?

The description clearly states the tool polls the status and result of a job started by request_case_timeline, using a specific verb and resource. This distinguishes it from siblings like get_case or request_case_timeline.

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 clearly implies usage as a follow-up to request_case_timeline by naming that tool, but does not explicitly state when not to use it or mention alternative tools for similar purposes. The context is clear but not fully explicit.

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 no annotations, the description fully discloses key behaviors: asynchronous nature, no AI credits consumed, case_id format constraints, court-specific result statuses (completed/pending/failed), and the need to poll with requestId. This goes beyond typical descriptions and covers failure modes (case number will fail).

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

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

The description is front-loaded with the core purpose and then provides dense, non-redundant details in six short sentences. Every sentence earns its place – covering behavioral nuances, parameter constraints, and court-specific outcomes. It is efficiently structured for an async tool with multiple edge cases.

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 complexity of an async job with different court types and no output schema, the description is remarkably complete. It explains the response statuses, orderCount for Supreme Court, the polling mechanism with get_case_timeline, and the need for requestId. No critical context appears 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 schema description already fully covers the case_id parameter (24-char ObjectId, from search results, case number fails). The tool description repeats this info without adding new meaning, so the baseline of 3 for high schema coverage applies.

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

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

The description clearly states 'kicks off a fetch of the live order and hearing history for a case directly from the court's own systems' – a specific verb+resource+scope. It also distinguishes itself from the sibling get_case_timeline by explaining that this request initiates the job, while polling is done with get_case_timeline.

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 clear context on when to use this tool: for initiating a live history fetch, with court-specific behavior (Supreme immediate, District sync, High Court pending). It does not explicitly say when not to use it or compare against other sibling tools, but the mention of polling via get_case_timeline and the 'no AI credits' note offer usage 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 no annotations provided, the description carries the full disclosure burden and reveals important behaviors: fast, exact match, does not consume AI credits, and two known limitations (caseNumber not filtering, sortBy date not reliably reordering). This goes well beyond a typical tool description, though it stops short of describing return format.

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 efficient: every sentence contributes either purpose, usage guidance, or a caveat. It is front-loaded with the core function and uses clear 'Note:' markers for gotchas.

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 14 parameters and absence of an output schema, this description is remarkably complete: it covers what data is searched, performance characteristics, when to choose alternatives, and known quirks. The only minor gap is no explicit mention of response structure, but the schema already handles parameter details.

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 documents all 14 parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the sortBy validation-vs-internal mismatch and reinforcing that caseNumber should be placed in query, giving agents critical operational knowledge.

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 identifies the tool as performing keyword and boolean search over a 310M-record index of Indian court cases. It names the specific resource (OpenSearch index) and distinguishes it from semantic_search_cases, making its purpose unmistakable.

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

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

It explicitly instructs when to prefer this tool over semantic_search_cases (for case numbers, party names, citations, judge names, exact phrases) and when to use the alternative (natural language questions about legal concepts). This is textbook usage guidance with 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?

With no annotations, the description fully discloses matching behavior (case insensitive substring), result cap (50), and default behavior for empty q. It also mentions the resource cost (no AI credits). It does not describe the return format, but for a simple autocomplete tool, this is adequate.

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 efficient sentences, front-loaded with purpose and usage, with no redundant or filler content. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers the core behavior, the default case, the cap, and the intended use case. It is complete enough for an agent to use correctly, though it omits the exact response shape (e.g., list of names).

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% for the single 'q' parameter, so the schema already explains the case-insensitive substring match. The description adds value by noting that an empty or omitted q returns the first 50 names, but this is behavioral context rather than parameter semantics. 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 it is an autocomplete over the combined Supreme Court and High Court judge name list, with a specific verb ('Autocomplete') and resource. It distinguishes itself from sibling tools by explicitly tying it to getting exact spellings before using search_indian_court_cases.

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 ('to get the exact spelling of a judge name before passing it to search_indian_court_cases as judgeName'), names the alternative tool, and clarifies that no AI credits are consumed. This gives clear context for when to choose 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses AI credit consumption, performance characteristics, silent ignoring of certain fields, and the fallback behavior to keyword search with a response marker. This is exemplary transparency.

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?

Although lengthy, the description is front-loaded with the core purpose and every sentence contributes unique information: cost, speed, use case, ignored fields, and fallback behavior. No fluff or repetition; the structure guides the reader from main purpose to important caveats.

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 (no output schema), the description covers essential operational details: the subset size, credit consumption, latency, ignored parameters, and the fallback mode field in the response. This is sufficient for an agent to set expectations and invoke correctly.

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

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

Schema coverage is 100%, but the description adds substantial context beyond the schema: it warns that certain top-level fields are 'silently ignored' and directs users to put filtering in the 'filters' object. It also clarifies that filters override auto-extracted ones, adding meaning not present 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 clearly identifies the tool as 'AI vector search' over a specific subset of cases, and explicitly contrasts it with a sibling tool: 'Prefer this over search_indian_court_cases for natural language questions...' This provides a specific verb, resource, and scope, fully distinguishing it from alternatives.

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

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

Provides explicit when-to-use guidance: 'Prefer this over search_indian_court_cases for natural language questions about legal concepts, fact patterns or doctrines, where exact keywords will not match.' Also warns about slowness ('a single call can take a minute or more'), setting expectations for appropriate usage.

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