Tapetide - Indian Stock Market MCP

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds genuine behavioral context on top: duplicates are merged at weighted-average price rather than overwritten, and parsed/inferred input should be confirmed before writing. It does not state what the write does to existing holdings beyond merge semantics or what the response contains, so it falls short of a 5.

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

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

The purpose and merge semantics are front-loaded, followed by the suffix-stripping rule and the confirmation rule, with no filler sentences. It is dense and slightly long, but each sentence carries operational instruction (suffix list, confirmation policy, fallback tools) rather than restating the 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 single-parameter bulk mutation tool with no output schema, the description covers the tricky parts: input shapes, symbol normalization, the confirmation policy for inferred data, and pointers to search_stocks and read_me. The main remaining gap is that it never indicates what the tool returns (e.g. resulting portfolio or merge summary), which an agent might want before chaining calls.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by specifying symbol canonicalization: strip exchange suffixes (-EQ, -BE, -SM, -ST, -BZ, -BL, -RE, -IV, -RR, .NS, .BO) and pass plain NSE symbols, plus a worked example mapping natural language to the holdings object. That is real added meaning the schema cannot convey.

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

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

The description states a specific verb and resource ('Add one or more stocks to the user's portfolio') and names the key behavior that distinguishes it from update_portfolio_stock: duplicate merging by weighted-average price. It also enumerates the accepted input shapes (single add, bulk list, pasted broker CSV/table), so an agent can route to it without opening any 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?

It gives explicit when-to-act rules ('When the user has stated symbol, quantity and price, add them directly') versus when to confirm first ('When you PARSED or inferred the holdings ... show the parsed rows for confirmation first, and ask rather than guess'). It also names fallbacks: use search_stocks if a symbol does not resolve, and call read_me for the full broker-CSV procedure.

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 annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description concretely explains the idempotency no-op, which adds some clarity, but it does not add behavioral context beyond annotations such as auth requirements, rate limits, or side effects on watchlist ordering.

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 operation is front-loaded in the first sentence, followed by the idempotency note and scannable use-case bullets. The structure is efficient and every element helps an agent match user intent to the tool.

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

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

For a simple one-parameter write operation with rich annotations, full schema coverage, and no output schema, the description is complete. It covers what the tool does, idempotency behavior, and representative usage scenarios.

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% for the single symbols parameter, and the schema itself provides the example, type, and min/max constraints. The description adds no additional format or constraint detail beyond repeating that one or more stocks can be added.

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 ('Add') and resource ('stocks to the user's watchlist') and explicitly scopes support for one or more symbols. It distinguishes the tool from portfolio-oriented siblings by naming the watchlist as the target.

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 provides concrete use cases mapping user utterances to single and bulk adds, including the workflow of looking up symbols first. However, it does not state when not to use this tool or name alternatives such as remove_from_watchlist or add_portfolio_stocks.

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, but the description adds substantial behavioral context beyond them: the return shape (per-event factor, cumulative factor, ex-dates, reconstruction formula in meta), a critical limitation on unquantified events (rights issues and demergers), and the price-return vs total-return caveat. It also explicitly instructs never to invent a factor for unquantified events.

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 purpose, then usage guidance, then critical caveats. Despite its length, every sentence carries decision-relevant information: scope, trigger conditions, return shape, unquantified-event handling, and dividend exclusion.

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, so the description must explain return values, and it does: per-event factor and cumulative factor with ex-dates, plus the reconstruction formula in meta. It also covers key caveats (unquantified events, splits/bonuses only, price-return not total-return), making it complete for an agent to call and interpret 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 description coverage is 100%, so the schema already documents symbol and its two aliases (ticker, identifier). The description adds no parameter-level syntax or format details beyond that, which is the baseline 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Get the split/bonus adjustment-factor timeline for a stock', and immediately bounds scope ('factors cover splits and bonuses only'). It distinguishes the tool from raw price retrieval and from real returns, so an agent can tell what it does 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?

It gives explicit triggering conditions: 'USE THIS when a price move looks impossibly large and you need to know whether it was a corporate action rather than a real return, or when the user asks for raw/unadjusted prices, or asks how to adjust for splits and bonuses.' It also supplies an effective when-not/caution path via the CRITICAL note about rights issues and demergers lacking reliable numeric factors.

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 openWorldHint=false, so the safety profile is covered. The description adds a max-20 constraint, but that is also in the schema, and it does not disclose data freshness, auth needs, or rate limits. Limited added behavioral 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?

Three short sentences, front-loaded with the core action, then the constraint, then the alternative. 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?

Low-complexity batch quote tool with rich annotations and a fully documented single parameter. The description covers purpose, limit, and sibling alternative, though it does not explain return fields or whether quotes are real-time vs delayed. Adequate for correct 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?

Schema coverage is 100% with one parameter fully documented as an array or string, including max 20, examples, and splitting guidance. The description reinforces 'multiple stocks' and 'Max 20 symbols per request' but adds no new syntax or semantics beyond the schema. 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?

States a specific verb ('Get'), resource ('current price quotes'), and scope ('multiple stocks at once'). It explicitly differentiates from sibling get_stock_quote by noting batch efficiency, so an agent can distinguish it 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?

Clearly implies use when multiple symbols are needed and names get_stock_quote as the less efficient alternative. It does not explicitly mention when to prefer get_live_quote or other single-symbol siblings, but the batch context is 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?

Goes well past the annotations (which already declare readOnly/idempotent/non-destructive): it discloses the ~3KB default payload size, that include sections are fetched via parallel API calls (a latency implication), that peers include a median row and pipeline-included self row flagged `is_self`, and critically that a `null` metric means 'not published' and must never be read as 0. That null-semantics warning prevents a real correctness error.

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

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

Front-loaded with base payload, then a clean bullet list for the three opt-in sections, then a copy-pasteable example. The peers bullet is long, but its density is justified by the column list and the null/`is_self` semantics it carries; little here is padding.

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 full job of describing return values — base fields plus each optional section — and even documents data-quality edge cases. An agent has enough to choose parameters and interpret the response without guessing.

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 the alias parameters (symbol/ticker/identifier) are already documented, but the description adds meaning the schema does not: what each include value actually returns (the ~20 technical indicators by name, the buy/hold/sell consensus, the peers column set and median). It does not cover the three alias names, which remain schema-only.

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 ('Get detailed company overview') and then enumerates exactly what the base payload contains — sector, about, pros/cons, fundamentals, growth, quote. An agent can distinguish this from get_financials, get_stock_quote, or get_live_quote without opening any schema.

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

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

Gives a concrete condition for each optional section ('include ["technicals","ratings"] for a full analysis view') and frames include as an opt-in that costs parallel API calls. It stops short of naming sibling alternatives (e.g. get_financials for statements, get_stock_quote for a bare price), so the when-not-to-use side is left implicit.

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 openWorldHint=false, so the safety profile is covered. The description adds only the scoping detail ('for one stock') and the alias relationship, which is modest added value beyond what annotations provide. No return format or pagination behavior is described.

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

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

Two short sentences plus a compact example, with the alias relationship and scope front-loaded and zero filler. It is appropriately sized for a thin alias tool, though it could be marginally tighter.

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 read-only alias with no output schema and full schema coverage, the description is adequate: it says what it returns and what it wraps. It is thin on the relationship to get_stock_events (e.g. whether to call this or the parent) and on return contents, leaving a small completeness gap.

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

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

Schema description coverage is 100%, documenting limit, symbol, ticker, and identifier aliases, so the schema carries parameter semantics. The example {"symbol":"ITC"} reinforces the primary identifier but adds no syntax or constraint detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 states a precise identity ('Alias for get_stock_events with type:"corporate_actions"') plus the concrete resource set (dividends, splits, bonuses, AGMs) for a single stock. This differentiates it from the generic get_stock_events sibling by naming the filter it applies. It stops short of a 5 because it defines itself only relative to another tool rather than standing alone.

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 alias mapping implicitly tells the agent this equals get_stock_events filtered to corporate actions, which is useful routing context. However, it never states when to prefer this tool over calling get_stock_events directly, nor any exclusions or prerequisites. Usage is inferable but not 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds interpretive context (a rating change is a forward-looking signal on credit/solvency risk) but says nothing about history depth, time windows, or ordering, which is meaningful for a time-series tool.

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

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

Three short sentences with the resource and return fields front-loaded, followed by interpretation and use case. No filler, though the closing use-case sentence is the weakest and does little work.

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 compensates reasonably by naming the returned fields (agency, rating, action, outlook over time). It remains thin on history range and the symbol aliasing, but an agent has enough to call it 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 description coverage is 100%, so baseline is 3. The description does not mention the symbol/ticker/identifier aliasing at all, even though the schema marks symbol as "REQUIRED" while the schema's required array is empty — a gap the description does not resolve.

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 names a specific verb (Get) and resource (credit-rating actions for a company) and enumerates the exact fields returned: agency, rating, action (upgrade/downgrade/reaffirm), and outlook over time. It is clearly distinguishable from siblings like get_corporate_actions or get_financials.

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

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

"Use for risk assessment and debt-investor research" implies a use context but gives no when-not guidance, no prerequisites, and no routing to or away from any sibling tool. Usage is only implied, not specified.

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 openWorldHint=false, so the safety profile is covered. The description earns credit by disclosing what the digest actually returns (summary, highlights, risks, guidance, key metrics, and artifact links), which the annotations do not convey. It lacks any note on auth or rate limits, hence not a 5.

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

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

Three tight sentences, front-loaded with the digest description followed by invocation and the read_document alternative. Zero filler; every clause carries actionable 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?

For a read-only tool with no output schema, the description adequately covers what is returned, how to invoke it, and the alternative for raw text. It could be marginally richer on the required-input combination (e.g. symbol vs doc_id tradeoffs), but nothing essential for correct invocation 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?

Schema description coverage is 100%, so every parameter including the symbol/ticker/identifier aliases and the doc_type enum is already documented in the schema. The description only reinforces the doc_id-vs-doc_type selection rule that the schema already states, so it adds little beyond the structured data; 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?

States the specific resource ('investor digest of ONE parsed filing') and enumerates its contents (summary, highlights, risks, guidance, key metrics, PDF/Markdown links). It distinguishes itself from siblings by naming read_document for raw text and list_company_documents as the source of doc_id, so an agent can route correctly without opening any 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?

Explicitly tells the agent how to invoke it (doc_id from list_company_documents, or doc_type for newest of that type) and names the alternative when the raw text is wanted ('For the text itself use read_document or download links.markdown_url'). This is clear context plus an alternative with a selecting condition; it stops short of full when-not guidance across all 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the bar is lower. The description usefully discloses the return content (highlights, risks, guidance, metrics) and that it is grounded in filings, but says nothing about recency, availability when no transcript exists, or cost/latency.

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, front-loaded with the resource and scope, with the usage hint second. No filler, though the second sentence is slightly vague.

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 compensates well by describing the digest's contents. The main gap is that symbol is semantically required per the schema but the schema lists no required fields, and the description does not clarify this.

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 itself documents limit, symbol, and the alias fields. The description adds no parameter-level meaning beyond that, making the baseline 3 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 gives a specific verb and resource ('Get AI-generated investor digests of a company's recent earnings (concall) transcripts and investor presentations') and enumerates the digest's components. It is clearly distinct from sibling tools like get_financials or get_document_summary, though it never names an alternative directly.

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

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

'Use for qualitative fundamental research beyond the numbers' implies context but gives no explicit when/when-not and never points to a sibling such as get_financials or get_document_summary. The routing decision is left to inference.

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

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

Annotations already establish read-only, idempotent, non-destructive, and non-open-world behavior, so the safety profile is covered. The description adds meaningful context: the exact data blocks returned, the 30-day daily window, and that chart data is optional and gated by a param — useful since no output schema exists.

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 verb and resource are front-loaded, and the bulleted inventory is scannable and dense with concrete content types. The final line ('Essential for understanding institutional money flow in Indian markets') is filler that does not earn 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?

For a zero-required-param read tool with no output schema, the description adequately conveys what comes back and the effect of the optional param. The main remaining gap is the failure to differentiate from the sibling get_fii_dii_flows, which is a real selection hazard.

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 a single documented enum param, so baseline is 3. The description reinforces its role ('Optional: cumulative flow chart data with interval param') but adds no syntax or default-value detail 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 and resource ('Get detailed FII/DII institutional flow data') and enumerates the exact data categories (cash flows, F&O positioning, aggregates, streaks, chart data). However, it never distinguishes itself from the near-identically named sibling get_fii_dii_flows, leaving the 'detail' scope ambiguous.

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 when-to-use, when-not-to-use, or alternative routing guidance. The existence of get_fii_dii_flows makes this a critical omission — an agent cannot tell which of the two FII/DII tools to pick. The closing sentence ('Essential for understanding institutional money flow') is a value claim, not 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world). The description adds useful return-content context — cash market flows, F&O positioning, aggregates, streaks — which matters because there is no output schema, but it says nothing about data freshness, granularity defaults, or latency.

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 alias relationship and then the data scope. No filler 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?

For a zero-required-parameter read tool with full schema coverage and no output schema, the description adequately enumerates what comes back. Only minor gaps remain around default vs. explicit chart_interval behavior and data recency.

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

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

Schema description coverage is 100% and the single optional chart_interval parameter is fully documented with an enum in the schema. The description mentions neither the parameter nor its default behavior, so it adds nothing beyond the schema — 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+resource ('Get detailed FII/DII institutional flow data') and explicitly declares itself an alias of the sibling get_fii_dii_detail, so an agent immediately knows it is interchangeable with that tool rather than a distinct capability.

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 alias declaration gives clear context for when to invoke it (whenever FII/DII flow data is needed) and pre-empts confusion with the identically-behaving sibling. It offers no exclusions or conditions, but none are really applicable for a pure alias.

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 establish read-only, idempotent, safe behavior, but the description adds rich context about the return shape (section objects with `periods`, `data`, `pct_changes`, `row_order`, `availability`), the meaning of `available_from` and its `basis` values, the look-ahead bias use case, and the critical caveat that values may include later restatements. This goes well 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 front-loaded with a clear one-sentence purpose, then packs in necessary detail. It is dense but nearly every sentence contributes useful information, though a bulleted structure would improve readability given the volume of return-shape details.

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 carries the full burden of explaining return values, and it does so thoroughly: section layout, ordering, change fields, availability metadata, and caveats. It also covers symbol cardinality and unsupported asset types, making the definition complete for an agent.

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 `section` values, `periods` defaults, and the alias parameters. The description mostly restates those same defaults and section semantics, adding only a brief example; it does not explain the alias fields (`ticker`, `quarters`, `identifier`) or other nuances 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 states a specific verb and resource ('Get financial statements for one company'), enumerates all supported sections, and explicitly excludes ETFs, index funds, and bonds. It also distinguishes itself from get_batch_quotes, so an agent can identify what this tool does and does not cover.

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 tells the agent when to pass `section` versus omit it, how `periods` interacts with each mode, how to handle multiple companies (one symbol per call, with get_batch_quotes noted as prices-only), and how to use `available_from` for backtests. It also states the disqualifying case (ETFs, funds, bonds), leaving no ambiguity about when 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?

Annotations already cover readOnly/idempotent/no-destruction, so the bar is lower, yet the description still adds real value: EPS actuals are restated for splits and bonuses, and `meta.eps_adjustments` lists what was rescaled. It also mentions the `bands` low/high analyst range, giving the agent a sense of the response shape.

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 dense paragraph, but it is front-loaded with the resource and metric scope before drilling into restatement behavior. Every sentence carries information; slightly long but not padded.

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 explaining key return structures (`bands`, `meta.eps_adjustments`) and period coverage. The only gap is the lack of routing guidance versus siblings, which is minor for a straightforward read 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 the schema already documents symbol and its two aliases (ticker, identifier). The description adds nothing about parameter meaning or format, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get analyst forecasts') and enumerates the metrics covered (EPS, revenue, EBITDA, net income, ROA, ROE, price estimates) plus quarterly/annual periods. It is clearly distinct from report-oriented siblings like get_financials, though it never names an alternative explicitly.

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 closing line 'Useful for understanding market expectations and earnings surprises' implies the use case, but there is no when-to-use/when-not guidance and no pointer to complementary tools such as get_financials for reported (non-estimate) figures.

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 genuinely useful behavioral context by enumerating the returned fields and the three sort orders, but says nothing about data freshness/vintage or update cadence for fortnightly flow 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?

Three tight sentences, front-loaded with what the tool returns before the interpretive note. Minor redundancy between the field enumeration and the sort-order sentence, but no filler.

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 parameters and no output schema, the description carries the return-value burden and does so by listing the four payload elements and the three sort orders. An agent could call this correctly; only data-freshness semantics are 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 tool takes zero parameters, so the baseline of 4 applies. The schema is an empty object and there is nothing parameter-wise for the description to clarify or omit.

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 resource ('FPI sector-wise investment data') with concrete output contents (AUM share per sector, fortnight change, 1Y flow, sparkline). The 'sector-wise' scope naturally distinguishes it from the sibling flow tools (get_fii_dii_flows, get_fii_dii_detail), though it never names those alternatives directly.

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 closing sentence ('Useful for understanding which sectors foreign investors are buying/selling') implies a use case but gives no explicit when-to-use trigger, no when-not-to-use condition, and no routing to the sibling FII/DII tools an agent might confuse it with.

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 (readOnly, idempotent, non-destructive, closed-world). The description adds a genuinely useful behavioral trait: coverage bounds are stated in the response and out-of-range returns `out_of_coverage` rather than an empty result. It does not fully describe return shape, but that is minor 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?

Front-loads the core relationship ('REVERSE of resolve_identifier_asof') and then adds use cases and a coverage caveat. Despite length, every sentence carries distinct information; there is no filler.

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, yet the description states what is returned (symbol and ISIN as of the date) and the edge-case semantics (out_of_coverage). Combined with annotations covering safety, an agent has everything needed to invoke it 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%, so the baseline is 3. The description adds meaning beyond the schema by clarifying which symbol to pass — the one the company trades as TODAY, with the reverse mapping handled by resolve_identifier_asof — which resolves the today-vs-historical ambiguity the schema leaves open.

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

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

States a specific verb+resource ('given a company's symbol and a date, return which symbol and ISIN that company held'). It explicitly frames itself as the REVERSE of resolve_identifier_asof, so the agent can distinguish it from that sibling without opening either schema.

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

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

Gives concrete when-to-use cases (labeling historical/backtest output, explaining a rename) and names the alternative relationship to resolve_identifier_asof. Nothing is left to inference about when this tool is the right pick.

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, destructiveHint=false and openWorldHint=false, so safety and closed-world scope are covered structurally. The description adds data provenance ('Official NSE index data') and reinforces single-index scope, but says nothing about rate limits, pagination, or how missing/suspended index data is handled. With annotations carrying the behavioral profile, the added value is moderate.

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

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

Front-loads what is returned (level series with OHLC and valuation ratios) and the entity scope before moving to examples and routing. Sentences are dense but each carries distinct information: data shape, provenance, examples, and sibling disambiguation.

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 states the returned fields (OHLC, PE/PB, dividend yield) and the entity scope, and the input schema fully covers parameters. Given a read-only, single-entity history tool, nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100% and every parameter is documented in the schema, including the alias relationships (days/range -> interval, index/symbol -> index_name) and the lookback semantics. The description adds no parameter-level detail beyond this, 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: retrieve the historical LEVEL series (OHLC + PE/PB/dividend yield) for a single NSE index, with an explicit scope note and concrete examples. It distinguishes itself from get_price_history (stocks only) and get_index_performance (multi-index ranking), so the agent can pick the right tool without opening a schema.

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

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

Gives explicit use cases ('what did Nifty IT close at on <date>', valuation trend, VIX history) and names two alternatives with the condition that selects them: get_price_history for individual stocks, get_index_performance for comparing multiple indices. This is the when/when-not/alternative pattern at full strength.

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 mark this read-only/idempotent, but the description adds substantial behavior the annotations cannot: enumerated four-state semantics, the meaning of each state, and the meta.coverage / meta.freshness.lag_days reporting with an instruction to trust answers only up to coverage.answerable_through.

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

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

Front-loads the core question, then states the return states, then usage, then the honesty constraint. Although long, every sentence earns its place given the non-obvious four-state contract and the bias-avoidance warning.

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 fully compensates by enumerating and explaining all four response states plus the coverage/freshness metadata an agent needs to interpret a result. Nothing needed to call or read it correctly 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?

Schema description coverage is 100% and all five params (date, index, symbol, and two symbol aliases) are self-documented, so the schema carries the load. The description adds no date format or alias guidance beyond what the schema already states, so 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?

Opens with a precise verb+resource framing ('Was a stock a constituent of an index on a specific historical date?') and immediately defines the four-state answer, making it unmistakably the point-in-time membership tool rather than price/index history or identifier resolution.

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

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

Gives explicit triggers ('any was X in the Nifty 50/500 on <date> question', point-in-time universe construction, survivorship-bias-aware backtests) and an explicit anti-pattern ('Do NOT infer historical membership from today's constituent list'), which is exactly the sibling-confusion this tool guards against.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower — yet the description still adds real behavior: only COMPLETED periods count and the in-progress week/month is excluded, computed from official NSE closing levels, and sorting is best-to-worst cumulative. It does not mention pagination, caching or rate limits, keeping it short of 5.

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

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

Front-loads the core action, output format, universe and usage triggers in a logical order — good structure. The long inline enumeration of sectoral indices (IT, Bank, Auto, Pharma, FMCG...) consumes tokens without changing agent behavior and could be trimmed, making it slightly verbose rather than wasteful.

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 correctly carries the return-value burden, specifying per-period % plus cumulative % and the sort direction. Combined with the completed-period exclusion rule and catalog scope, an agent has everything needed to call this correctly; the absence of an output schema is fully compensated.

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; every parameter (limit, order, periods, category, granularity, index_names) is already documented in the schema, including the 'sectoral for sector rankings' guidance. The description adds only marginal param context (cumulative sorting, ~140-index catalog coverage) and no syntax or edge-case detail 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 and resource — 'Rank NSE indices by RETURN over recent completed weeks or months, using official NSE index closing levels' — and defines the output shape (per-period % plus cumulative %, sorted best-to-worst). An agent can distinguish this from get_index_history or get_market_pulse purely from the description.

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 enumerates triggering phrasings ('rank sectoral indices by 3-week return', 'which sector performed best last month', 'top gaining sectors') and adds a negative rule: do NOT compute a sector return from its constituents, which is only an approximation. This is a textbook when/when-not 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds real value by explaining the metric's interpretation (rising VIX = fear), but leaves "recent history" undefined as to window length or granularity.

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

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

Three short sentences, front-loaded with what the tool returns before the interpretive gloss. The fear-gauge explanation is arguably decorative for an agent but does aid interpretation, so it 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?

With no parameters and no output schema, the description carries the burden of describing the return, and it does so at a high level. The one gap is that "recent history" is unspecified in length and frequency, which an agent cannot resolve from the schema or annotations.

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 tool takes zero parameters, so there is nothing for the description to disambiguate — the baseline for a no-parameter tool. The description correctly implies a parameterless single-resource fetch.

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?

A specific verb (Get) plus a uniquely named resource (India VIX), with an explicit statement of what is returned: latest value, daily change, and recent history. It is clearly distinguishable from adjacent tools like get_option_iv_history or get_index_performance by resource, though it does not name a sibling to route against.

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

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

"Use for market-timing and risk context" gives an implied usage context but no when-not guidance and no named alternatives. An agent knows roughly when this is relevant but gets no explicit disambiguation from other volatility or index tools.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds that it is an alias for get_stock_quote and returns the 'latest' price, which is useful behavioral context, but it does not disclose return format, rate limits, or auth needs.

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 plus a compact example, with the alias relationship and core purpose front-loaded. 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 simple, read-only alias with no output schema and rich annotations, the description gives enough to invoke correctly. It could more explicitly state when to prefer this alias over get_stock_quote, but the schema and annotations cover the rest.

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 symbol, ticker, and identifier aliases. The description adds an example with 'symbol', which reinforces invocation but does not add meaning beyond what the schema provides. 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 ('Latest price for one symbol') and explicitly identifies the canonical sibling it aliases ('Alias for get_stock_quote'). An agent can immediately distinguish its function and understand it is equivalent to get_stock_quote.

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 calling itself an alias for get_stock_quote, but it does not say when to choose this tool over get_stock_quote or any alternative. Guidance is implied rather than 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context on top: freshness windows ('today's', 'last 7 days', 'latest session'), inclusion thresholds (>=80% of MWPL, >=50% delivery, >=Rs 1 Cr traded value), and an explicit limitation ('market-wide book not available' for mtf). It omits auth/rate-limit details, which keeps it short of a 5.

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

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

The purpose sentence is front-loaded before the option list, and the seven bullets are terse and parallel, each carrying distinct content rather than filler. The sibling-routing sentence is placed last where it belongs. Nothing reads as padding.

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 carries the return-value burden — and it does so per feed, including freshness, ranking, units (Rs crore), and caveats. Combined with annotations that fully cover the read-only safety profile, an agent has everything needed to select and invoke it 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%, so the baseline is 3, but the single enum's member names (fno_ban, slbm, mtf, deliveries) are opaque strings that the schema only lists. The description gives each one meaning, defining what fields come back and how each feed should be interpreted, which is genuine meaning 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 states a specific verb and resource ('Get one of today's market-wide data feeds') and immediately enumerates the seven feeds it can return. It also explicitly distinguishes itself from three siblings (market_valuations, market_heatmap, get_stock_deals), so an agent can route without opening any 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?

Each enum value is paired with the condition that selects it and the content it yields (e.g. 'deals — bulk & block deals for the last 7 days'; 'signals — technical signals from the latest session'). It also names explicit alternatives and their use cases, e.g. 'for index PE/PB valuation history use market_valuations' and 'for a single stock's own deal history use get_stock_deals'.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds return-shape context (sentiment tags, source URL, related symbols) beyond the annotations, though it says nothing about pagination or 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?

Front-loaded with the core purpose and return shape, followed by category enumeration and the routing rule. Every sentence earns its place with no 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?

With no output schema, the description adequately covers the return payload (sentiment-tagged articles with category, source URL, and related symbols), the filterable dimensions, and the sibling alternative — sufficient for an agent to call it 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%, so params are documented in the schema. The description nonetheless adds value by enumerating the full set of valid categories, which is richer than the schema's four-category example, and confirms the positive/negative/neutral sentiment values.

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+resource: fetches market-wide news. It explicitly scopes to 'market-wide across all categories' and names the return payload (sentiment-tagged articles). It clearly distinguishes itself from sibling news tools by noting the stock-specific alternative.

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 an explicit routing rule: 'Use this for broad market news. For stock-specific news, use get_stock_events with type "news" instead.' This names the alternative and the exact condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that by spelling out the return payload (flows in crores, PE/PB/DY, VIX), which matters because no output schema exists. It doesn't discuss data freshness or intraday-vs-close timing, which is the only meaningful gap.

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

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

Three sentences, all load-bearing: the first defines scope and contents, the second positions it as the quick overview, the third routes to the correct siblings with exact parameter values. Front-loaded and free of filler.

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 carries the return-value burden and does so by naming each data block returned. Combined with the annotation coverage and zero parameters, an agent has everything needed to select and call it 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 tool takes zero parameters, so there is nothing for the description to disambiguate and the schema imposes no burden. Baseline of 4 applies since parameter semantics are moot for a no-arg tool.

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 ('Get today's market snapshot') and then enumerates the exact contents: FII/DII net flows, Nifty 50 PE/PB/DY, and India VIX. It explicitly positions itself as 'the quick daily-overview tool', which separates it from the more granular market tools in the sibling list.

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

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

Explicitly names the alternatives and the conditions that select them: get_market_data with dataset: "signals" for the technical scanner, and get_trending_stocks for gainers/losers. It even includes the literal parameter value to pass, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantive behavioral context the schema cannot: the critical warning that `no_print` is not a zero return and must be carried forward or masked, plus honest disclosure of `classification_limits` where `no_print` conflates illiquidity, suspension, and missing data, and where `pre_listing` can only be asserted with a known listing date.

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

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

Front-loaded with the purpose, then usage, then the operational warning, then honesty limits — a sensible priority order with no filler. Given the subtlety of the classification semantics, the length is earned rather than padded.

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 carries the burden of explaining returns and does so: it names the per-day classification values and the `classification_limits` field in the response. An agent has everything needed to call this correctly and interpret the result without guessing.

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, but the description reinforces the semantics that matter most for `days` — that the window is counted in CALENDAR days, not trading days, which is the exact distinction this tool exists to surface. It adds nothing about the symbol/ticker/identifier aliases beyond what the schema already documents.

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 precise verb and resource: for every calendar day in a lookback window, return the reason a price is or is not present, enumerating the six classifications (`traded`, `weekend`, `holiday`, `pre_listing`, `delisted`, `no_print`). This is unmistakably distinct from siblings like get_price_history or get_live_quote, which return prices rather than absence reasons.

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

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

Gives explicit triggering conditions: 'USE THIS when a price series has gaps' and 'ESPECIALLY before computing returns over a gappy series,' which tells the agent exactly when this tool is the right call. It stops short of naming an alternative tool or stating when not to use it, so it falls just short of a full 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 this a safe, idempotent, closed-world read, yet the description adds substantial context beyond them: it is an end-of-day stamped snapshot rather than a live tick, snapshot_ts must be read and stated, iv_pct/atm_iv_pct are percent while atm_iv_change is percentage points, nulls mean unavailable (iv_unsolved, illiquid, pcr_undefined) and must render as '—', and it must not recommend a strike or strategy. This is unusually rich behavioral disclosure.

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?

Dense but front-loaded: purpose, then usage triggers and sibling routing, then snapshot/unit/null caveats, then presentation constraints. Each block carries distinct operational value and no sentence merely restates the name or annotations.

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 carries the full burden of describing returns and it does so: field names (snapshot_ts, iv_status, atm_offset, available_expiries), unit conventions, and null-vs-zero semantics are all covered. An agent has everything needed to call it and report results 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 description coverage is 100%, so expiry, symbol/ticker/identifier aliases and strikes-per-side are already fully documented in the schema; the description adds no input-parameter syntax or constraints. Baseline 3 applies, with the description's detail concentrated on output fields instead.

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 ('Get the INDEX OPTION CHAIN') and enumerates the payload of interest (IV, Greeks, bid/ask, OI by strike). It explicitly differentiates itself from get_option_iv_history and from stock-option coverage, so an agent can place it among siblings without opening a schema.

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

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

Gives explicit triggering questions ('show me the NIFTY option chain', 'what is the ATM IV', 'where is max pain', 'put-call ratio') and names the alternative (get_option_iv_history) with its broader underlying coverage. It also states the negative case (stock options are not collected) and how to phrase it, which is exactly the routing detail an agent needs.

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

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

Annotations only declare readOnly/idempotent/non-destructive; the description goes far beyond by disclosing percent units, the 2y+ WEEKLY bar rollup, the 400-bar cap, the returned coverage and spot_is_proxy flags, and a no-trade-recommendation constraint. These are exactly the behavioral traits an agent cannot infer from structure.

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?

Dense but front-loaded — purpose and fields come first, then units, then the rollup/cap caveats, then the reporting constraint. Every sentence carries information, though the units and rank-vs-percentile clarifications make it longer than strictly minimal.

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 carries the burden of explaining returns and does so — bar_interval, coverage, spot_is_proxy, and the 400-bar limit are all covered. An agent has everything needed to interpret and report the series 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%, so the structured fields already define range/symbol/aliases, giving a baseline of 3. The description still adds real meaning: it warns that longer ranges return weekly bars and that bar_interval must be read, which materially changes how the enum value should be interpreted.

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

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

States a specific verb+resource (historical option-analytics time series for an underlying) and enumerates the exact fields returned (ATM IV, IV rank/percentile, realised vol, PCR, max pain, 25-delta skew). It explicitly differentiates from sibling get_option_chain by noting this covers ~556 underlyings INCLUDING individual stocks while the chain is index-only.

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 concrete triggering queries ('is IV high right now', 'IV rank of RELIANCE', 'has volatility been rising') and the condition that selects this over get_option_chain. It stops short of an explicit when-not beyond the index-only contrast, and never references the sibling get_options_analytics, which an agent may confuse with a snapshot counterpart.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds that the analytics are "broken down per expiry," a useful structural detail, but says nothing about data freshness, rate limits, or what happens when a symbol has no derivatives listed.

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

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

Front-loaded with verb and resource, then a dense but justified enumeration of return fields, then one short usage sentence. The long parenthetical list of metrics earns its place because no output schema exists, though it is slightly list-heavy for a two-sentence description.

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 enumeration of IV metrics, put-call ratio, max pain, and per-expiry breakdown is genuinely load-bearing information about what comes back. Combined with annotations covering safety, an agent has enough to call it correctly; the remaining gap is the absence of any routing guidance against the overlapping options siblings.

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 all three parameters (symbol plus its ticker/identifier aliases) are documented in the schema, so the baseline of 3 applies. The description says "for a stock," which weakly reinforces that a symbol is needed, but adds no alias-selection guidance despite the schema marking zero required parameters.

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 names a specific verb and resource ("Get derivatives analytics for a stock") and enumerates the exact metrics returned — ATM IV, IV rank/percentile, realized vol, put-call ratio, max pain, 25-delta skew, OI per expiry. That is far more specific than the title alone. It does not, however, distinguish itself from close siblings like get_option_chain or get_option_iv_history, which an agent could easily confuse it with.

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

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

"Use for options strategy, volatility analysis, and gauging derivatives-market positioning" gives implied usage scenarios but names no alternative and states no exclusions. An agent cannot tell from this whether to prefer get_option_chain, get_option_iv_history, or this tool for overlapping volatility questions.

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

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

Annotations only cover the safety profile (read-only, idempotent, non-destructive); the description carries the real behavioral load. It discloses the silent 2000-day cap, points at meta.window.truncated/requested_days/next_cursor, and explains the follow-up paging loop — exactly the non-obvious behavior an agent would otherwise get wrong.

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

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

Front-loaded with the purpose and output format before the critical cap warning, which is the right ordering. The paging paragraph is somewhat long and restates the truncated/next_cursor mechanics twice, but every sentence carries operational weight.

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 takes responsibility for return shape (row-per-day columns) and the meta.window envelope. Combined with the paging guidance, an agent has everything needed to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by tying days to the cap/truncation behavior and explaining end_date as the paging cursor derived from next_cursor. It reinforces default 365 and daily/weekly aggregation, which the schema already states.

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 (OHLCV price history) and even specifies the row-per-day output shape (date, open, high, low, close, volume, delivery %). This makes it unambiguous against siblings like get_live_quote, get_stock_quote, and get_index_history, which an agent can rule out without opening a schema.

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

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

Gives clear usage context ('price analysis, trend detection, and technical calculations') and an explicit procedure for the multi-year case: page with end_date until truncated is false. It does not name alternative tools or state when NOT to use it, so it stops short of a full when/when-not/alternatives treatment.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds interpretively useful context (governance red flag, recent-quarter scope) but says nothing about data recency, latency, or coverage limits — modest added value above 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?

Three sentences, front-loaded with the verb+resource+payload, then scope, then interpretation. Every sentence carries information; nothing is boilerplate or restated from 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, so the description must convey what comes back — and it does (pledge percentage across recent quarters plus creation/release events). It is slightly thin on the required-identifier behavior (zero required params at the JSON level despite the schema's 'REQUIRED' note) and on the Indian-market framing implied by siblings.

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

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

Schema description coverage is 100% and the schema itself documents that `symbol` is required and that `ticker`/`identifier` are aliases, so the schema does the heavy lifting. The description adds no parameter-level detail (e.g. exchange prefix format or alias precedence), which is the expected baseline 3 in this situation.

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 ('promoter share-pledge history for a stock') and further specifies the returned content: quarterly pledge percentages plus pledge creation/release events. That is enough to separate it conceptually from the broad `get_shareholding`, though the description never names that sibling or draws the boundary explicitly.

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

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

'Use to assess promoter financial stress and risk' gives a concrete decision context for reaching for this tool rather than a generic quote or shareholding endpoint. No when-not conditions or named alternatives are given, so it stops 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description still adds real context: the catalog size (325 ratios) and that the return value is the exact ratio names screen_stocks accepts, which tells the agent what it gets back and why it matters.

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

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

Two sentences, zero filler, with the core action and both invocation modes front-loaded before the return-value note. Every clause 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?

There is no output schema, but the description compensates by stating what comes back (exact ratio names accepted by screen_stocks) and the catalog size. For a one-parameter lookup tool that is entirely sufficient.

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?

With a single optional parameter at 100% schema description coverage, the schema already documents 'q' fully. The description's keyword examples ('cash flow', 'debt', 'promoter') largely restate the schema's examples, so it adds little meaning beyond syntax already present.

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

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

States a specific verb+resource ('Search or list available financial ratios') and names its consumer, the screen_stocks tool, which no sibling shares. An agent can immediately tell this is a discovery helper for valid screen field names rather than a data-fetch tool.

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 describes both modes: pass a keyword to search, omit for the full catalog, and frames the purpose as finding names that screen_stocks accepts. It gives clear context and an implicit when-to-use (before constructing a screen), though it does not state exclusions or name an alternative lookup path.

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 openWorldHint=false, so the safety profile is covered. The description adds that data is returned "over time" and "quarter over quarter," a modest behavioral detail, but says nothing about return format, history depth, or latency.

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

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

Three short sentences, front-loaded with the resource and its key data categories. The final sentence ("Useful for understanding ownership changes") is largely restatement and could be cut, but there is no bloat overall.

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 read-only, idempotent lookup with a fully documented schema and no output schema, the description adequately conveys what data comes back (promoter/FII/DII/public holdings, quarterly history). It lacks any note on history range or result shape, which would have made it 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 symbol/ticker/identifier aliases and the type enum are fully documented in the schema. The description only loosely hints at the period dimension ("quarter over quarter") and adds no syntax or alias-resolution detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Get shareholding pattern") and enumerates the exact data domains returned: promoter, FII, DII, public. This is far more informative than a tautology, but it never distinguishes itself from the closely related sibling get_stock_ownership, leaving overlap unresolved.

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?

Only says it is "useful for understanding ownership changes," which implies a scenario but gives no explicit when-to-use, when-not-to-use, or alternatives. With a nearly synonymous sibling (get_stock_ownership) in the tool list, the absence of routing guidance is a real gap.

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 (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value by enumerating the returned fields (counterparty, side, quantity, price, value), which matters because no output schema exists. It omits pagination/limit behavior beyond the schema's own note.

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

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

Front-loaded with the verb and resource, then a compact field list via em-dash, then the intent question. Three sentences with little waste, though the field enumeration is slightly long and could compress.

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 return-field listing compensates well, and annotations handle safety. Coverage is complete enough to call correctly, though the missing output schema and the schema's lack of a required-array (despite symbol being marked REQUIRED in text) leave a small gap the description does not close.

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 type, limit, symbol and its aliases. The description only restates 'Optionally filter by deal type', adding no syntax or semantics beyond the schema. 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?

Specific verb+resource ('Get large-trade history for a stock') followed by an explicit enumeration of the four deal types it covers. This clearly separates it from ownership/shareholding siblings, and the example question nails the intent.

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?

Supplies a clear use context via the quoted question 'who has been buying or selling X?', which tells the agent which user intents this satisfies. It stops short of naming excluded cases or pointing to sibling alternatives such as get_stock_ownership or get_shareholding.

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 read-only, idempotent, non-destructive behavior. The description goes further by detailing what each event type returns (sentiment tags, ex-date/LTP, specific filing doc types, combined catalogues), which is valuable because there is no 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?

Front-loads the core purpose in one sentence, then uses a bulleted type breakdown. Every line contributes useful detail without redundancy.

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

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

For a read-only data retrieval tool with rich annotations and no output schema, the description covers the return content well. It stops short of routing guidance against overlapping siblings, which keeps it from a 5.

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 the baseline is 3. The description adds meaning for the type enum by explaining what 'news', 'corporate_actions', and 'filings' actually contain, lifting it to 4, though it does not discuss limit or symbol aliases.

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 'Get' and resource 'stock events', and enumerates the three event types with their contents. It does not differentiate from overlapping siblings such as get_stock_news or get_corporate_actions, so it earns a 4 rather than a 5.

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?

Offers only 'Filter by type to get only what you need,' which is parameter guidance, not when-to-use guidance. No alternatives or exclusions are named, so an agent has no help choosing between this tool and the dedicated news/corporate-action 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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds one piece of behavioral context beyond them — that results are sentiment-tagged — but says nothing about ordering, recency window, or what happens when the symbol is omitted.

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 short sentences plus an example, with the alias identity front-loaded. Slightly wasteful: the inline example duplicates information already implied by the schema's own example, but nothing is padded or buried.

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 full schema coverage and no output schema, the description's job is mostly to establish the tool's identity and output nature, which it does ('sentiment-tagged news'). Only minor gaps remain: no return shape or recency scope for a tool whose output schema does not exist.

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 symbol, limit, and the ticker/identifier aliases with their defaults and max. The description only supplies a single example call, adding no semantics beyond the schema. 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+resource: sentiment-tagged news for a single stock, and explicitly identifies itself as an alias for get_stock_events with type='news'. The 'for one stock' scope distinguishes it from the sibling get_market_news, though that sibling is never named.

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 alias disclosure is genuinely useful routing information — an agent learns this call is equivalent to get_stock_events with type='news'. However, there is no explicit when-to-use guidance and no rule for choosing between this tool and get_market_news or get_stock_events directly.

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 (readOnly, idempotent, non-destructive, closed-world), so the description's value is in return-shape behavior: empty string vs null semantics for both fields, the '|'-joined newest-first series alignment, and an explicit warning not to interpret an unlabelled figure. It does not discuss rate limits or permissions, but for a closed-world read tool that is minor.

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

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

Purpose is front-loaded in the first clause, then the payload structure follows. The very long positional-array enumeration is dense but each field label genuinely aids parsing a schema-less output; only the trailing months-alignment example feels slightly over-specified.

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 correctly carries the return-shape burden and documents both returned structures, including null/empty failure modes. It is nearly complete for call correctness; only guidance on which alias parameter to prefer 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 the three parameters (symbol plus two aliases) are fully documented there, so the baseline is 3. The description adds nothing about parameter usage or alias precedence, but it does not need to carry that burden.

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 plus the two data families returned ('yearly dividend totals and mutual fund holdings'). It also names the sibling it is not (get_stock_events for dated individual dividends), so an agent can route without opening another 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?

Explicitly directs the agent to get_stock_events with type "corporate_actions" for dated individual dividends, which is the key ambiguity for this tool. It gives no guidance against other nearby siblings like get_shareholding or get_stock_deals, so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The word 'current/latest' hints this is real-time rather than historical data (contrasting get_price_history), but there is no disclosure of auth needs, rate limits, or freshness guarantees beyond that.

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 action and differentiated routing, with zero filler. Every clause 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?

With no output schema, listing the returned fields is genuinely necessary and present. Combined with annotations covering the safety profile, the definition is nearly complete, missing only clarity versus the overlapping get_live_quote sibling.

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 all three parameters (symbol plus two aliases) are fully documented in the schema. The description adds nothing about parameter usage or alias behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the current/latest stock price quote') and enumerates the returned fields (LTP, change, %, volume, market cap, PE, PB, 52-week high/low). It distinguishes itself from get_batch_quotes, but does not differentiate from the equally close sibling get_live_quote, leaving real ambiguity.

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 routes the multi-stock case to get_batch_quotes, which is clear when-to-use guidance. It omits any guidance on when to prefer this over get_live_quote or get_price_history, so coverage of alternatives is only partial.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds rich behavioral context beyond them: the score comes from the latest complete scoring run, `null` pillars mean missing data rather than zero, `status: "insufficient_data"` means no publishable score, and governance caps/red flags may have limited the result. It also declares the deliberate absence of band and category fields.

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

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

Front-loaded with purpose and scoping, then organized into a numbered reading guide that keeps dense information navigable. It is long and carries some repetition (the band-coarseness caveat appears twice) plus boilerplate disclaimers, which keeps it short of a 5.

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 carries the full burden of explaining return contents and how to interpret them, and it does so thoroughly: pillars, weights, percentile base, confidence, coverage, governance overlays, and every degenerate case an agent might encounter.

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

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

Schema description coverage is 100%, and the schema already documents `symbol` as required plus the two aliases, so the schema does the heavy lifting. The description adds no parameter-level syntax or format guidance, 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+resource+scope ('Get the Tapetide Score for ONE stock') and defines what the score is: a deterministic, non-LLM 0-100 composite with six pillar sub-scores, percentile, confidence, coverage and governance flags. It explicitly distinguishes itself from the multisource sibling `screen_tapetide_scores` by noting the band cutoffs live there.

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

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

Gives explicit trigger phrases ('what is Tapetide's score for X', 'why is X rated Y') and an additional use case (rating input to a write-up). It also implicitly routes multi-stock lookups to `screen_tapetide_scores` by referencing it as the source of the band table.

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 fully covered. The description adds the universe constraint (Nifty 500) and recency scope (today), which is useful, but discloses nothing about return shape or whether the snapshot is cached/live.

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, front-loaded with the verb and contents, zero filler. Nothing is restated from the title or annotations.

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 no-parameter, no-output-schema aggregate tool, the description covers what it returns and its scope well. The main gap is sibling disambiguation versus scan_movers, which the context suggests is an overlapping 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 tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering is required, though it does not explicitly note that no inputs (e.g., index or count) are accepted.

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 (get trending stock summary) plus the exact contents: top gainers, losers, and high-volume stocks scoped to Nifty 500. That is clear and actionable, but it does not distinguish itself from the sibling scan_movers, which appears to cover overlapping mover data, so an agent cannot fully disambiguate from the name alone.

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?

'Quick snapshot of market movers today' implies the when (fast daily overview), but there is no explicit guidance on alternatives. With siblings like scan_movers, get_market_pulse, and market_heatmap in the set, the description should say when to prefer this tool, and it does not.

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 safety is covered. The description adds genuinely new behavioral context: that it returns an empty list when the user has no holdings, and that prices are live. It does not cover freshness/latency or auth failure behavior, which would push it to a 5.

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

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

Purpose is front-loaded in the first clause and the second paragraph handles edge cases and the alternative tool. The long comma-separated field enumeration is dense, but with no output schema it is doing real work rather than padding.

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 carries the full burden of describing return values and does so field-by-field, plus states the empty-result case and the companion write tool. An agent has everything needed to call and interpret 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?

Zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to clarify or omit.

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

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

States a specific verb+resource ('Get the authenticated user's current stock portfolio with live prices') and scopes it to the authenticated user, which cleanly separates it from the watchlist, screener, and company-data siblings. The exhaustive return-field list makes the tool's payload 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?

Gives clear context (current holdings with live prices) and routes the agent to the right sibling for the write path by naming add_portfolio_stocks. It does not explicitly say when to prefer this over get_watchlist or get_stock_ownership, so it stops short of full when/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 read-only, idempotent, non-destructive, closed-world behavior, and the description goes well beyond them: it enumerates returned fields, flags that quote fields are null when unpriced, describes the `movers` tally, and explains the 50-per-page clamp plus the has_more/next_offset paging contract. With no output schema, this disclosure is exactly what an agent needs.

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 dense paragraph ordered purpose → returned data → paging mechanics, with no filler. Every clause carries information an agent needs to call the tool correctly.

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, so the description must describe returns, and it does so completely: field list, null semantics for unpriced quotes, the movers summary, and the full paging protocol. Nothing needed to invoke or interpret the call 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?

Schema description coverage is 100%, so both `limit` and `offset` are already documented, including the default/max 50 clamp and the 'pass next_offset' convention. The description restates the same semantics (50 per call, offset: next_offset) without adding format or edge-case detail, 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 ('Get the user's stock watchlist — the stocks they are following') with ordering ('newest first'), which cleanly separates it from add_to_watchlist, remove_from_watchlist and get_user_portfolio. An agent can identify the tool without opening the schema.

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

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

Gives explicit operational guidance for the paging loop ('when has_more is true, call again with offset: next_offset') and warns to finish paging 'before acting on all of a long watchlist'. It does not, however, contrast the tool with siblings like get_user_portfolio or search_stocks, so no exclusion guidance is offered.

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 establish read-only, idempotent, non-destructive semantics, so the description's job is lighter. It adds genuine behavioral value beyond the annotations by declaring sort order ('Newest first') and that the response is an index with no narrative prose ('No prose'). It does not mention pagination behavior despite the limit parameter.

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, then the returned shape, then the downstream-tool relationship, then two short trailing facts. Nearly every clause earns its place, though the field enumeration is dense and 'Newest first' reads as a tacked-on fragment.

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 carries the burden of describing return values, and it does so thoroughly (field list plus per-document links). Annotations cover the safety profile, and parameters are largely handled by the schema. The remaining gap is pagination/limit behavior, which an agent would need for iterating large result sets.

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 83%, so the schema already documents limit, since, symbol, ticker, doc_types, and identifier, making the baseline 3. The description's only parameter-relevant contribution is implicitly mapping 'concall transcripts, annual reports, presentations, IPO documents' to the doc_types enum, which adds marginal meaning 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 identifies the resource ('Index of a company's filings parsed to text') and enumerates exactly what it returns (doc_id, type, period, date, num_pages, flags, links), so an agent knows it is a listing/retrieval tool for corporate documents. It relates itself to get_document_summary and read_document by noting the doc_id feeds those tools, which aids disambiguation. The only weakness is that no explicit verb is used ('Index of...' rather than 'Lists...'), but the intent is 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?

The sentence 'The doc_id is the input get_document_summary and read_document take' effectively tells the agent this is the discovery step in a two-stage workflow, which is meaningful usage context. It does not, however, provide explicit when-to-use vs when-not guidance or exclusions, so it stops short of full routing clarity.

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 readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. With no output schema, the description adds real value by specifying the payload contents (the full metric list), which the agent could not otherwise know.

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 core verb and payload, with the index guidance appended. No padding, though the trailing note partially restates what the schema already lists.

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 one optional parameter, full schema coverage, and no output schema, the description supplies what the schema cannot: the shape and breadth of the returned per-stock record. A short note on default index behavior or sort order would make it 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% and the schema itself enumerates every index slug, so the description is not required to carry parameter meaning. It adds only a light grouping hint ('Nifty broad, size and sector indices plus Sensex'), which is marginal over 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+resource with scope ('stock heatmap for an index — all constituent stocks') and enumerates the exact metrics returned (market cap, PE, PB, multi-horizon price changes, volume, sector). That distinguishes it cleanly from sibling index tools like get_index_performance or get_market_data.

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 the use case (view all constituents of an index at once) and points the agent to the index parameter for available values, but it never states when to prefer this over get_index_performance, scan_movers, or get_market_data, nor any 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 declare readOnly/idempotent/non-destructive, so the safety burden is lifted, and the description adds real behavioral context beyond them: the default index, the weekly sampling frequency (not present in the schema), and the default 5-year window. It stops short of covering data freshness, rate limits, or return shape.

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

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

Front-loaded with what the tool returns and its defaults before the input-format detail. The enumerated slug/code list is verbose but earns its place by disambiguating a string-or-number parameter; nothing else 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?

With only two optional parameters, no output schema, and no nesting, the definition covers enough: what metrics come back, the default scope, and how to address indexes. It could be more complete by noting the return granularity or how the time series is shaped, but that gap is minor for a read-only metrics endpoint.

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 the baseline is 3, but the description genuinely adds meaning by mapping slugs to numeric codes (nifty-50 → 13, nifty-bank → 25, etc.) that the schema only refers to abstractly. The 'years' max-20 constraint is left to the schema, so it is not fully additive.

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

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

States a specific verb+resource ('Get index valuation metrics (PE, PB, Dividend Yield) over time') with concrete defaults, so the agent knows exactly what it returns. It does not, however, distinguish itself from adjacent siblings like get_index_performance or get_index_history, which an agent could plausibly confuse it with.

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 an implied use case ('assessing whether the market is overvalued or undervalued relative to historical averages'), which is genuine context, but it never states when to prefer this over get_index_performance, get_index_history, or get_market_pulse, nor any exclusions. Usage is inferable but not directed.

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 (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them by disclosing hard limits (12 pages / 24000 chars, max_chars up to 60000), the pagination behavior (pages_returned, next_pages), and the fallback links returned. That is exactly the operational context an agent needs to page correctly.

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 dense sentences with the return format front-loaded, then limits, then usage guidance. Every clause carries information (markers, caps, pagination fields, full-file alternative) with no filler.

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 naming the fields the result returns (pages_returned, next_pages, markdown/PDF links) and the citation markers. Combined with annotations covering safety, an agent has everything needed to invoke and page through the 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 coverage is 83% (>80%), so the schema documents most parameters, including the page-range pattern and max_chars bounds. The description reinforces doc_id/page-range/max_chars but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Markdown text of a parsed filing by doc_id and page range.' It is clear what the tool returns and how it is scoped, but it never names the obvious siblings (get_document_summary, list_company_documents) to disambiguate, so an agent must infer the boundary from the schema's doc_id reference.

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 real context for use: 'Annual reports run 100-400 pages: read the sections you need, or download links.markdown_url to search the whole file.' This names an alternative (whole-file download) and the condition that selects it, though it stops short of stating explicit when-not-to-use cases.

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 safety (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), so the bar is lower. The description adds real value by disclosing what the response contains — the categorised tool list, the SEBI disclaimer requirement, and research usage patterns — which matters because there is no 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?

A single sentence, front-loaded with the primary action and then listing the payload's parts. No filler 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?

With no parameters and no output schema, the description carries the burden of describing the return, and it does so adequately by naming the three content blocks. It stops short of explaining structure or size, but nothing critical for invocation 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 tool takes zero parameters, so the schema has nothing to document; per the rubric this is a baseline 4. The description correctly does not invent parameter discussion.

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 ('Returns the complete guide to this server') and enumerates its contents. Among ~55 data-fetching siblings, this is unmistakably the meta/onboarding tool rather than a market-data call.

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?

Mentions 'usage patterns for common research tasks', which implies consulting it before planning research, but never says explicitly to call it first or when it is the right choice over a specific sibling. Usage is inferable rather than 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description's added value is the non-obvious multi-step bulk-removal procedure, though it never states that removal is permanent or what happens for symbols not on the watchlist.

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?

Opens with the core action in one sentence, then uses a compact bulleted use-case block. Every line carries distinct information and nothing repeats 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 destructive mutation with no output schema, the description supplies the operationally critical bulk-removal recipe that is missing from schema and annotations. It stops short of stating error behavior for unknown symbols or explicitly confirming permanence, which would make this fully 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% and the single parameter is fully documented with an example (['INFY', 'TCS']) plus min/max item constraints. The description's 'one or more' adds only cardinality, which the schema already encodes via minItems/maxItems, so 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 (remove) and resource (stocks from the user's watchlist), and the phrasing 'one or more' matches the array parameter's cardinality. It is cleanly distinguishable from add_to_watchlist, get_watchlist, and remove_portfolio_stocks in the sibling list.

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

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

Provides two concrete use cases with the natural-language triggers ('Stop watching INFY', 'Clear my watchlist') and, for the bulk case, an explicit prerequisite workflow: call get_watchlist, page with next_offset until has_more is false, then remove. That is when-to-use and how-to-use guidance an agent would otherwise have to guess.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, but the description adds critical context beyond them: the action 'cannot be undone' and 'Always confirm with the user before removing stocks.' It also clarifies that removal is 'entirely' (not partial), which helps the agent avoid a destructive mistake.

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 definition is front-loaded with the core action, followed by tightly scoped use cases, a safety warning, and an alternative-tool routing note. Every sentence earns its place; no redundancy or filler.

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 destructive, single-parameter mutation tool with no output schema, the description covers purpose, invocation scenarios, safety confirmation, irreversibility, and the correct sibling alternative. Nothing an agent needs in order to call it safely and correctly 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?

Schema description coverage is 100%, and the single 'symbols' parameter is already documented in the schema with an example array. The description reinforces the multi-symbol nature through use cases but adds no syntax, format, or constraint details 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 ('Remove') and resource ('stocks from the user's portfolio entirely'), making the scope unambiguous. It explicitly distinguishes itself from the sibling 'update_portfolio_stock' for partial sells and references 'get_user_portfolio' as the source for symbol 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?

Provides three concrete use cases (single delete, bulk thematic delete, clear portfolio) and an explicit exclusion: 'For partial sells (reducing quantity), use update_portfolio_stock instead.' The confirmation requirement is also stated as a workflow rule, leaving no ambiguity about when and how to invoke 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?

Annotations already cover read-only/idempotent/non-destructive, but the description goes much further: it enumerates the four return states, explains that `uncertain` means an open bracket around a rename/ISIN change, and warns that `out_of_coverage` must not be reported as 'no such symbol'. That is exactly the behavioral context an agent needs.

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?

Dense but front-loaded: what it does, when to use it, what it returns, and how to read each state. No filler sentences, though it is on the longer side and could tighten the back half 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?

With no output schema, the description carries the return-value burden and does so fully, including the meaning of each status and the coverage-window caveat. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so the schema already documents date, kind, and value. The description reinforces the symbol/ISIN distinction and date anchoring but adds little syntax or format detail beyond the schema, so 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 (resolve), a specific resource (historical symbol or ISIN), and the temporal scope ('ON a given date'). This is clearly distinguishable from sibling tools like get_identifiers_asof, which presumably go the other direction.

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

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

Gives explicit when-to-use context with concrete scenarios (2018 holdings file, old research note, backtest) and a clear failure mode to avoid (merging two companies after ticker recycling). It doesn't name a sibling alternative for current-data lookups, so it stops short of a full 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 cover the safety profile (readOnlyHint, idempotent, non-destructive), so the bar is lower. The description adds the key behavioral fact that invoking this tool is a dead end and the correct action is to re-route, which is genuinely useful context beyond 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?

A single sentence, front-loaded with the disqualifying fact and then delivering all three destinations. Zero waste and perfectly sized for a redirect stub.

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 zero required parameters and no output schema, the only thing an agent needs is to be told not to call this and where to go instead, which the description delivers completely. Nothing actionable 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?

Schema coverage is 100% and the single 'preset' parameter is already documented as ignored. The description's 'Not a standalone tool' reinforces that the argument is inert, but adds no syntax or value meaning beyond the schema — baseline 3 is correct.

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 immediately declares 'Not a standalone tool' and defines the tool's actual function as a router to three named alternatives. The verb+resource of the tool's own name is never fulfilled by the tool itself, but the agent knows exactly what this definition is for and can distinguish it from every sibling it names.

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?

Names three concrete alternatives (get_trending_stocks, screen_stocks, screen_stocks_technical) and pairs each with the condition that selects it (ready-made movers, custom fundamental screens, technical screens). This is explicit when-to-use routing with nothing left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds a modest behavioral detail ('today' freshness and the categories returned), but nothing about rate limits, auth, or result shape. With annotations carrying the safety burden, a 3 is appropriate.

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 short sentences with zero waste; the alias relationship is stated first and the data categories follow. Fully front-loaded and appropriately sized for a zero-param alias.

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 usefully states what the response contains (gainers, losers, most-active, today), and the annotations cover safety. For a zero-parameter alias this is essentially complete, with only the usage-vs-sibling question left open.

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 tool takes zero parameters, so the schema has nothing to describe and the baseline is 4. There are no argument semantics the description could or should add.

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 names the specific resource it surfaces (top gainers, losers, most-active stocks today) and explicitly states its relationship to the sibling get_trending_stocks as an alias. That lets an agent distinguish it from the many other market-data siblings, though it never gives a verb of its own beyond the alias framing.

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?

'Alias for get_trending_stocks' implicitly tells the agent the two are interchangeable, which is useful routing context. However, it gives no explicit when-to-use/when-not guidance and does not say whether to prefer this over get_trending_stocks in any circumstance.

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 carry the safety profile (readOnly, idempotent, closed-world), so the bar is lower. The description adds real operational context beyond that: the 1500-character query cap, that ratios must be EXACT names, that an invalid query errors with the offending token named, and that cross-field comparison is permitted. It does not disclose pagination/result-format behavior, which is a minor remaining gap.

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

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

Purpose and the sibling alternative are front-loaded, then a clearly labelled QUERY SYNTAX block, ratio list, example, and a final note. Despite being dense, every block is headed and each earns its place; no filler sentences.

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 complex filter tool with 6 params and no output schema, the description covers invocation thoroughly (syntax, limits, errors, ratio catalog, alternatives). The one omission is any hint of what the response contains (result shape/pagination semantics), which the absent output schema leaves to the description.

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 the baseline would be 3, but the description enriches the critical `query` parameter far past the schema's one-line example: it documents the operator set, AND/OR connectors, per-line grouping, cross-field comparisons, exact-name matching, a starter list of common ratio names, and a worked example. That is substantial added meaning for the parameter that drives the call.

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

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

States a specific verb+resource+"scope ("Screen Indian stocks by fundamental criteria using 325 financial ratios") and explicitly names the sibling it is not (screen_stocks_technical). An agent can distinguish it from the technical screener and from get_screener_ratios without opening any 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?

Names the alternative explicitly ("For technical screens ... use screen_stocks_technical instead") and routes the agent to get_screener_ratios for unknown ratio names and to read_me for stock disambiguation. When-to-use, when-not, and the fallback tools are all 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: filters combine with AND logic, crossover operations evaluate against today's bar, screening runs on real-time data, and market_cap_basic is in absolute ₹ rather than crore — the last one prevents a serious misuse.

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

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

Front-loaded with purpose and sibling routing before the DSL details, and nearly every sentence carries load. The FIELDS block is long but it is a required vocabulary list, so the bulk is justified rather than padding.

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 should ideally say what a result row looks like, but it does cover the inputs thoroughly (filters DSL, operations, field vocabulary, units, example, limit/columns/sort exist in schema). An agent has everything needed to construct a valid call; only the return shape is left implicit.

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 80% (baseline 3), and the description goes well past it for the hardest parameter: it defines the {left, operation, right} shape, enumerates the valid operations with the special case that in_range takes [min,max] and crosses_* mean crossover today, and provides a large whitelist of legal field names plus a worked example. The ₹-vs-crore units warning for market_cap_basic is exactly the kind of semantics the schema cannot express.

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 (screen) plus resource (Indian stocks), the axis (technical indicators) and enumerates the indicator families it covers. It explicitly names the sibling it is not (screen_stocks for fundamental screening), so an agent can route between the two without opening either schema.

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

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

Gives a clear routing rule: technical indicators here, fundamentals via screen_stocks. It does not mention other plausible-looking siblings such as run_preset_screen, scan_movers, or screen_tapetide_scores, so the agent must infer those boundaries on its own.

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

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

Annotations only cover the safety profile (readOnly/idempotent/not destructive); the description adds substantial beyond-annotation context: the non-ordinal band presentation rule, the default filtered slice (large+mid, confidence>=75), the size-bucket liquidity caveat, and snapshot/cursor pinning to a single scoring run.

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

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

Purpose and the key usage triggers are front-loaded, which is good. But the entry is bloated by a long 'IMPORTANT' block plus three near-duplicate disclaimers ('NOT investment recommendations', 'Decision-support only', 'not investment advice', SEBI line) that restate the same point and dilute the signal.

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 an 11-parameter ranking tool with no output schema, the description fully discloses what rows contain (score, band, pillars, sector, size, market cap, next_cursor) and how to page, so an agent has everything needed to call and interpret it 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%, so the schema already documents every parameter (q, sort, bands, sizes, cursor, min_confidence, etc.) in detail. The description restates the filter set but adds little parameter syntax beyond echoing defaults already in the schema, so 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+resource ('List and rank stocks by the Tapetide Score') with the filter axes enumerated, and it clearly separates the tool from siblings like get_tapetide_score and screen_stocks by framing it as the rank/filter-by-score surface that mirrors the tapetide.com ranking page.

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 concrete trigger queries ('which large caps score highest', 'show me Strong-band pharma stocks') and states the tool owns 'any rank/filter-by-Tapetide-Score question'. It does not explicitly name when to prefer get_tapetide_score (single-stock) or screen_stocks instead, so no true exclusion 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 readOnly/idempotent/non-destructive, yet the description adds much more: alias and brand-name matching ('Zomato'→ETERNAL), a specific ranking order (listed first, exact > prefix > word > contains, larger companies first), and typo tolerance for 4+ character queries. These are genuine behavioral traits an agent could not infer from structured fields.

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

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

Front-loaded with what is searched, then matching/ranking, then the routing note. Three dense but purposeful sentences with no filler; slightly information-heavy but every clause 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?

For a search tool with full schema coverage and complete annotations, the description covers searchable fields, ranking, alias handling, and the outbound use of the result. No output schema exists, yet the key return field (`symbol`) and its purpose are explained, so nothing essential 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?

Schema coverage is 100%, so the schema already documents query, limit, sector, and industry. The description adds only one extra parameter behavior — typo tolerance at 4+ characters — beyond what the schema states, 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?

States a precise verb and resource: search ~8,200 Indian stocks by name, symbol, BSE code, or ISIN. The enumeration of searchable fields and the scale distinguish it cleanly from screening/quote siblings like screen_stocks or get_live_quote.

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 closing sentence gives clear workflow context: the returned `symbol` is the input the per-stock tools expect, establishing this as the entry point. It does not, however, explicitly contrast itself with identifier-resolution siblings (e.g. resolve_identifier_asof) or state when-not to use it, so it stops short of 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 declare destructiveHint=true and non-idempotent, so the mutation profile is already carried structurally. The description adds genuine context beyond that: both fields must always be supplied as final values, existing values are replaced via weighted-average recomputation, and the zero-quantity edge case routes to removal. It stops short of stating permissions or exactly what is overwritten on the record.

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

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

Front-loaded purpose sentence, then clearly delineated use-case and numbered-workflow blocks. Slightly long for a three-parameter tool, but nearly every line carries operational content (formulas, edge case, alternative) rather than filler, so the length largely 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?

For a destructive mutation with no output schema, the description supplies the prerequisite call, the arithmetic the agent must do, and the zero-quantity escape hatch, which is close to a full operating procedure. Minor remaining gap is the absence of any statement about the response/confirmation or auth requirements.

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% (baseline 3), but the description adds real semantic value the schema lacks: the weighted-average formula, the distinction between additional vs total quantity, and the invariant that avg_price is unchanged on a sell. That is meaning beyond the field-level text.

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+resource ('Update the quantity and/or average price of an existing stock') with immediate scope narrowing to an existing position. The use-case bullets and workflow make it unmistakable versus add_portfolio_stocks (new positions) and remove_portfolio_stocks (zeroing out), both of which it names.

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?

Explicit when-to-use via three natural-language user phrasings, plus concrete formulas for both purchase and partial-sell scenarios. It names the alternative (remove_portfolio_stocks) and the exact condition that selects it (new_qty = 0), and it mandates the get_user_portfolio prerequisite step.

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