MarketPing

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context: it is measured data, not a forecast, and it explicitly states that no buy/sell recommendations, price targets, or grey-market premium are provided, going beyond the structured annotations.

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

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

The description is three sentences with no fluff. The first sentence front-loads the exact output and horizons, the second clarifies data nature and uniqueness, the third gives the prerequisite, and the final sentence sets boundaries. Every sentence 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 one-parameter read-only tool with no output schema, the description fully specifies what is returned (percentage returns over multiple horizons), how to obtain the input (from recent_alerts), and what is excluded (recommendations, targets, grey-market premium). 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% and the single parameter alert_id is described as 'Alert UUID from recent_alerts'. The description repeats this guidance without adding new semantic meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'percentage returns at 5 minutes, 30 minutes, 1/2/3/5/7/15 days and 1/2/3 months from the announcement price' after ONE announcement. It distinguishes from siblings by explicitly saying 'measured data, not a forecast' and emphasizing that no other Indian data source publishes it, making the tool's unique purpose clear.

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 a clear prerequisite: 'Get an alert id from recent_alerts first', which tells the agent exactly what input to use and where to get it. It also implicitly contrasts with forecast tools via 'measured data, not a forecast' and explicitly excludes recommendations, price targets, and grey-market premium, guiding against improper use.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical interpretation guidance: 'A missing year means not yet read — never read it as clean' and clarifies that only factual data is returned, no recommendations. This adds value beyond the structured metadata.

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

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

The description is concise, with two sentences that pack the core function, usage context, a crucial caveat, and a factual-data disclaimer. Every sentence earns its place, and the structure is front-loaded.

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

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

For a single-parameter read-only tool, the description covers what it returns, how to interpret missing data, and its factual scope. It lacks explicit output schema but the caveats and page-cited detail make it adequately complete for an agent to call correctly.

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

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

The schema already provides a complete description for the 'company' parameter (slug, symbol, or UUID), covering 100% of the schema. The description does not add extra parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves auditor opinions, key audit matters, CARO exceptions, and auditor changes per fiscal year, sourced from annual reports. This is specific enough to distinguish it from general company data tools, though it doesn't explicitly name sibling alternatives.

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

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

It advises use for governance and red-flag questions, giving context on when to apply the tool. However, it does not mention alternatives or provide explicit exclusions, so the guidance is implied rather than directly contrasted with 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 non-destructive behavior. The description adds meaningful behavioral context beyond that: it states the data is factual only and explicitly excludes buy/sell recommendations, price targets, and IPO grey-market premium, setting expectations about what the tool will not return.

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 well-structured and front-loaded: the core data scope comes first, followed by concrete use cases, then a factual boundary. Every sentence adds distinct value with 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 simple one-parameter, read-only tool with appropriate annotations, the description is complete: it names the returned data categories, gives usage contexts, and clarifies limitations. No output schema exists, but the description sufficiently enumerates what the agent can expect.

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 100% schema description coverage for the single 'company' parameter, the schema already explains that a slug, NSE symbol, or UUID is accepted. The description adds only the 'one company' scope, which is already implied by the tool name and input schema, so no significant extra parameter semantics are provided.

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

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

The description clearly identifies the tool as returning latest fundamentals and valuation for a single company, enumerating the specific data points (price, market cap, P/E, P/B, revenue, profit, growth, ROCE/ROE, debt ratios). It distinguishes itself from broader siblings like run_screener or results_calendar by emphasizing 'one company' and the snapshot nature.

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 usage guidance is provided: use for 'how is X doing', 'what does X trade at', or as the numeric backdrop before reading filings. It does not explicitly name alternatives to avoid, but the use cases are concrete enough for an agent to route correctly.

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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral boundaries beyond that: it is factual only, and explicitly excludes buy/sell recommendations, price targets, and IPO grey-market premium. This helps an agent avoid misusing the tool for advisory content.

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 carry the full package: what the briefing contains, when to use it, and what it deliberately does not include. Nothing is redundant, and the key content is front-loaded.

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

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

With no parameterschers, no output schema, and strong read-only annotations, the description still enumerates the expected content categories, making the return shape predictable. No critical invocation information 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 has zero parameters, and the schema coverage is 100%, so the baseline is 4. The description provides no parameter-specific detail, but none is needed; it instead clarifies the scope of the returned briefing.

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 identifies a specific resource—the daily briefing for the latest NSE trading day—and enumerates the content categories it covers, such as market score, index moves, flows, breadth, movers, and announcements. The 'Use for' phrasing immediately signals the intended query, distinguishing it from more specialized sibling tools like fpi_flows.

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

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

The description explicitly says to use it for 'how did the Indian market do today', giving clear contextual guidance. It does not name alternatives or state when not to use it, but for a broad daily briefing tool this is a minor omission.

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, and non-destructive behavior, so the description adds value by disclosing the data boundary: factual content only, with no recommendations, price targets, or grey-market premium. This is meaningful context beyond the structured annotations.

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

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

Two sentences with no wasted words: purpose first, then usage guidance, then a content boundary. Every clause adds relevant information without repeating 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 single-parameter tool with no output schema, the description fully equips an agent: what the tool returns, when to call it, and what it will not contain. No critical omission is apparent.

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 doc_id fully explained as coming from list_documents or search_filings. The description adds no new parameter-level 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?

The description clearly identifies the resource (a document's table of contents) and the specific contents (section titles, one-line summaries, page ranges). It also distinguishes the tool from read_pages by explicitly positioning it as the precursor to page selection.

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-use guidance: read this before read_pages to avoid guessing which pages to open. The rationale ('annual reports run to 300+ pages') reinforces the intended workflow and names the sibling tool it relates to.

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, so the safety profile is covered. The description adds value by stating 'Factual data only' and clarifying that no recommendations or price targets are included, which is behavioral context beyond the annotations. It also specifies 'full content', though it doesn't describe the return format or error handling – but given the simple read-only nature, this is sufficient.

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 two sentences with zero waste. The first sentence front-loads the core action and enumerates the supported record types; the second sentence clarifies the data nature. Every word earns its place, and the structure is efficient and scannable.

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

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

For a single-parameter fetch tool with no output schema, the description covers all necessary aspects: the action, the input source (id from search), the types of records supported, and the nature of the data. Annotations cover the safety profile, and the schema covers the parameter. Nothing essential is missing 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 the parameter 'id' is documented as 'An id returned by search'. The description enriches this by listing what kinds of ids are valid (company profile, announcement, filing page, IPO issue), giving the agent a clearer understanding of what it can retrieve. This goes beyond the schema's minimal definition.

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

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

The description clearly states the verb 'Retrieve' and the resource 'the full content of one search result by its id', and it enumerates the specific record types (company profile, announcement, filing page, IPO issue). This differentiates it from sibling tools like search (which returns ids) and company_snapshot (which presumably targets a specific record type), making the purpose unambiguous.

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

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

The description implies usage: you must first have an id from search, and this tool retrieves the full content for that id. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for a one-parameter fetch tool. The lack of explicit exclusion criteria keeps it at a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context beyond that: the data source (NSDL), the update cadence ('as NSDL publishes them' implying daily), and what it deliberately excludes (no recommendations, price targets, grey-market premium). This gives an agent a richer behavioral model without contradicting 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?

Two sentences total: the first front-loads the purpose and content, the second adds usage guidance and exclusions. There is zero filler, and every clause earns its place. The structure is ideal for an agent to parse quickly.

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

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

The tool has 7 optional parameters, no required ones, and no output schema, but the description accurately summarizes the data scope and the intended use. It does not explain return format, but with no output schema the agent can infer it from the described content. The description is complete enough to understand what data will come back and how to frame a query, missing only detailed parameter-combination examples that the schema already covers.

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 86%, so the schema already documents each parameter reasonably well. The description adds a few conceptual hooks (e.g., 'by investment route', 'month-to-date totals', 'daily net equity and debt flows') that map to route, period, category, and granularity, but it does not go beyond what the schema descriptions already convey. Baseline 3 is appropriate because 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: 'Foreign portfolio investor (FPI/FII) flows into Indian markets as NSDL publishes them' and lists concrete content (daily net equity and debt flows, by investment route, month-to-date totals). It distinguishes the tool from siblings by giving it a unique, self-contained scope and even names the intended question ('are foreign investors buying'). No ambiguity remains about what the tool does.

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

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

The description explicitly says 'Use for are foreign investors buying questions', giving a clear trigger condition. It also adds a negative boundary: 'Factual data only — MarketPing publishes no buy/sell recommendations, no price targets and no IPO grey-market premium', which tells the agent when not to use this tool, though it does not name alternative tools. This is clear context with a partial exclusion, but not a full when-not/alternative matrix.

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

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

Annotations already indicate a read-only, idempotent, non-destructive operation, so the bar for additional disclosure is lower. The description adds valuable policy-level behavior: it deliberately excludes grey-market premium, recommendations, price targets, and verdicts. This tells the agent what kind of data it will never receive, which is useful beyond the structured annotations.

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

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

The opening sentence is information-dense and immediately communicates the tool's contents. The following sentences add important exclusions, but the final sentence repeats 'no IPO grey-market premium' and overlaps with the 'apply/avoid verdict' caveat. The message is clear but could be tightened without losing meaning.

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

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

Given the read-only annotations and absence of an output schema, the description does a solid job of conveying what data the tool returns and what it intentionally omits. It covers statuses, boards, and content fields, which is enough for an agent to decide whether this tool fits a query. It does not detail return structure or sort semantics, but the enums and the field list mitigate that 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?

Only 33% of parameters have schema descriptions, so the description must compensate. It partially does by mapping 'mainboard and SME' to board, and 'open now, upcoming, closed or already listed' to status. It also mentions subscription figures and post-listing performance, which relate to some sort options like 'subscription' and 'gain'. However, it does not explicitly explain individual parameters such as sort, year, or how they interact.

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 (Indian IPOs) and the scope of data: price band, issue size, lot size, dates, subscription figures, and post-listing performance, across mainboard and SME. It implicitly describes a listing/tracking tool, though it never uses a direct verb like 'fetch' or 'list'. It also distinguishes itself from sources that provide grey-market premiums or apply/avoid verdicts, which helps separate it from related financial tools.

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

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

The description explicitly states when this tool is not appropriate: if the user needs grey-market premium or apply/avoid verdicts, this is not the source. It also frames the tool as a factual, recommendation-free IPO tracker, giving clear context for expected use. It does not name sibling alternatives, but no obvious sibling tool covers the same IPO-tracking niche.

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 signal read-only, open-world false, idempotent, and non-destructive behavior. The description goes beyond this by disclosing specific behaviors: newest-first ordering, each item carrying a doc_id, capped lists marked as truncated, and a strict factual-data scope with no recommendations or targets. This is exactly the kind of contextual detail agents need to interpret results 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?

The description is concise and front-loaded, leading with the resource and document types before adding the truncation warning and factual scope note. Every part contributes useful information without fluff. The brief listing of content types justifies the term 'documents' and helps agents gauge relevance quickly.

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 there is no output schema, the description covers the essential return semantics: newest-first order, doc_id presence, and truncation behavior. It also clarifies the data scope, which is important for agents deciding whether this tool answers a user's request. It could be even more complete by describing pagination or the full set of fields returned, but for a simple read-only list it is largely 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?

Schema description coverage is 100%, so the schema already documents the company and doc_type parameters, including the enum values. The description adds a few examples that align with the enum but does not provide extra meaning about how the params behave or interact. A baseline 3 is appropriate because the description neither compensates nor needs to compensate 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 as the documents MarketPing holds for a companyhare and provides concrete examples of the document types included. It also specifies ordering (newest first) and that each item has a doc_id, giving a precise operational picture. It does not explicitly differentiate this from search_filings or doc_contents, but the scope is much clearer than a generic statement.

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

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

Description implies usage through its listing of document types and the caveat about truncated lists, which tells agents not to treat a truncated result as exhaustive. However, it does not explicitly state when to prefer this over search_filings or doc_contents, nor does it mention any exclusions. The factual-data clarification is a useful boundary but not a full routing guideline.

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, and non-destructive behavior. The description adds useful context beyond annotations: the account-link prerequisite and the factual-data-only policy with no recommendations, price targets, or grey-market premium. No contradiction found.

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

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

Four concise sentences, with the core purpose and model types front-loaded. The factual-data-only clause adds a relevant boundary rather than fluff.

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

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

Even without an output schema, the description sketches the output (company and link), the account prerequisite, filtering behavior, and data-policy constraints. This is sufficient for a simple list tool, though the return shape is only lightly described.

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 schema already documents `company` as an optional slug to narrow by. The description reinforces this by saying it narrows to one company, but adds little new format or behavior 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?

The description clearly identifies the resource: saved valuation models on the MarketPing account, with model types and output elements (company, link). It does not use an explicit verb like 'lists' or 'returns', and it doesn't contrast with sibling run_model, so it misses the top tier.

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 actionable context: a linked account is required, and the optional company parameter narrows to a single company. However, it doesn't mention alternatives or when not to use this tool, so it stops short of explicit routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context: daily rebuilds, the nature of the data (factual, no recommendations), conditional personal stacks when an account is linked, and the return fields. This goes well beyond annotations.

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

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

The description is compact, front-loaded with the core definition, and includes the use case and a factual-data disclaimer. Every sentence earns its place; no filler. It is appropriately sized for a zero-parameter 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?

With no parameters, no output schema, and annotations covering safety, the description is complete for an agent to call it correctly. It explains what is returned, the conditional account behavior, and the intended use. Nothing critical is missing for a list 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 has zero parameters, so the schema is empty and coverage is 100% by definition. Per the rubric, a 0-parameter tool gets a baseline of 4. The description adds no parameter semantics, but none are needed.

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

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

The description clearly states the tool lists curated stacks of Indian companies, rebuilt daily, and specifies what is returned (slug, rule, member count, changes). It distinguishes itself from siblings like run_stack and stack_changes by focusing on listing rather than executing or showing changes. The 'Use for' phrase reinforces its purpose.

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 a concrete use case: 'Use for which companies clear several quality screens right now.' It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to decide. A small gap: no explicit exclusions or comparison to run_stack, but the use case is directive.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the 12-page limit, the required citation format, the verification rule that quotes must actually appear on the cited page, and the factual-only nature of the content. These are non-obvious behavioral constraints an agent needs before calling.

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 compact sentences front-load the core function, add the critical citation rule, and finish with content-boundary context. No word is wasted and every sentence adds operational value.

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

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

For a simple read-only tool with fully documented parameters and safety annotations, the description is nearly complete: it states the payload, the constraint, and the return expectation. The only minor gap is that page_to is optional in the schema but the description consistently describes a 'page range', leaving single-page behavior 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 100%, so the baseline applies; the schema already documents doc_id, page_from as 1-based, and page_to with the 12-page maximum. The description adds no parameter-specific detail beyond reinforcing the page-range limit and the quote rule.

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

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

The description opens with a specific verb and resource: it returns the actual text of a page range, capped at 12 pages. It also differentiates itself by declaring itself the only source from which quotes may be taken, distinguishing it from document-level siblings like doc_contents.

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 a clear conditional: use this tool whenever you need a verbatim quote from a document, and it states that quotes must be verified against the returned text. It does not explicitly name alternatives or enumerate when not to use it, but the 'ONLY source' phrasing provides strong routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, fully covering the safety profile. The description adds valuable context beyond annotations: it mentions the AI classification, clarifies that the data is factual only, and explicitly lists exclusions (no recommendations, no price targets, no IPO grey-market premium). This helps the agent set user expectations.

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

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

The description is two sentences with no waste. The first sentence front-loads the core concept and returned fields; the second sentence gives usage guidance and boundaries. 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 read-only query tool with no output schema, the description lists the output dimensions (subject, category, document type, importance, sentiment), explains both company-specific and market-wide usage, and states data constraints. An agent has enough to decide when to call it and what to expect in return.

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

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

Schema description coverage is 100%, so both parameters (days and company) are already well-documented. The description reinforces that omitting company gives market-wide results, but it does not add new parametric semantics beyond the schema, so the baseline 3 is appropriate.

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

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

The description names a specific resource ('Recent NSE/BSE corporate filings') and the AI-classified fields (subject, category, document type, importance, sentiment), making the tool's purpose unmistakable. It also distinguishes itself from siblings by calling itself 'MarketPing's core dataset' and giving concrete query examples.

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

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

The description gives explicit use cases: 'what has X announced lately', 'any news on X', and 'what is happening in the market today' for the no-company case. It also sets boundaries by stating 'Factual data only' and listing what the tool does not provide (buy/sell recommendations, price targets, IPO grey-market premium). It does not name alternative tools, but the 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?

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral context: it returns candidate matches rather than a single canonical record, and it clarifies that the data is factual, with no recommendations or price targets. This goes beyond what annotations provide.

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

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

Three sentences, each carrying essential information: the lookup action and scope, the slug output and routing instruction, and the factual-data boundary. It is front-loaded and free of repetition.

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 resolver with a simple query schema, the description fully covers what the agent needs to know: what to pass, what it returns, and when to use it. No output schema exists, but the return value (slug candidates) is clearly stated.

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 parameter description already explains the query format. The description reinforces 'name, ticker or partial match' and scopes to Indian listed companies, but adds little beyond the schema's own documentation.

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

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

The description uses a specific verb-resource pair, 'Find an Indian listed company by name, ticker or partial match,' and clearly identifies the output as candidates with a MarketPing slug. It differentiates itself from siblings like company_snapshot and search by positioning itself as the entry-point resolver.

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

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

It explicitly instructs to call this tool FIRST unless a slug is already held, because every other company tool requires a slug. This gives unambiguous when-to-use guidance and effectively routes the agent away from alternatives.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful non-obvious traits: no dates means the next 60 days, and the tool intentionally excludes advisory content. It does not discuss response shape or pagination, but these are minor for this simple factual calendar.

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 carry distinct, non-redundant information: purpose, default behavior, and data policy. The purpose is front-loaded and every sentence 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 read-only, two-parameter calendar with no output schema, the description covers what data is returned (company/date pairs), the default window, the source, and the scope. It does not specify response sorting or exact formatting, but the expected output is clear enough 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?

The schema already documents both parameters (from_date, to_date) with format and a 120-day cap, so baseline is 3. The description adds meaningful value by stating that the default window is the next 60 days, which helps the agent decide whether to supply dates. This goes beyond the schema's field descriptions.

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

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

The description clearly identifies the tool as a quarterly-results calendar for Indian companies, explicitly tying it to exchange-published dates. It differentiates from siblings like ipo_pipeline and fpi_flows by naming a distinct resource and scope, despite not using an imperative verb.

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

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

It gives clear context: the default 60-day window and the factual-only boundary, warning that this tool is not for recommendations, price targets, or grey-market premiums. It does not name explicit sibling alternatives or say 'when not to use', but the scope and data policy are strong enough for an agent to select it correctly.

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 as read-only, idempotent, and non-destructive, and the description reinforces 'nothing is changed.' It adds important behavioral context beyond annotations: results are the holder's own arithmetic, must be reported as the holder's model, and MarketPing publishes no recommendations or targets.

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

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

The description is compact and front-loaded with purpose and outputs. The compliance sentence about not presenting output as MarketPing's view or a target is valuable for correct agent behavior, though it adds some length beyond the core mechanics.

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

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

For a single-parameter read-only tool with complete schema coverage, the description covers what output to expect, the prerequisite of a linked account, the idempotent behavior, and the important attribution caveat. No critical information needed to call the tool 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?

The schema has one parameter, 'model', with a description ('Model slug from list_models'), giving 100% coverage. The description adds model-type details but does not provide additional parameter syntax or restrictions beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Recompute') with a clear resource ('one of the account holder's saved models') and states the outputs: value per share, bridge, and projected years. It also names model types (DCF, excess return, sum of parts), distinguishing this from sibling tools like run_screener or list_models.

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

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

The description gives clear context: it applies to saved models, requires a linked account, and changes nothing. It does not explicitly name alternatives or state when NOT to use the tool, but the resource and output scope make the intended use obvious.

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, so the safety profile is covered. The description adds valuable behavioral context beyond that: it emphasizes the result universe, metrics coverage, and that output is factual only — no recommendations, price targets, or grey-market premium. This sets correct expectations without contradicting 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, all information-dense, with the primary action front-loaded, then use case, then the factual-data constraint. No filler or repetition of schema 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?

The description is complete enough for an agent to understand the tool's purpose, main input pattern, and constraints. It does not explain pagination or sort defaults, and there is no output schema, but the essential filter-construction guidance and factual scope are present. A small gap remains around result format and pagination behavior.

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 only 50% schema description coverage, the description compensates for the most important ambiguity: the `filters.field` property is a plain string, and the description directs agents to `screener_fields` for valid field names. It also conveys the breadth of available metrics (108 across named categories). It adds less for page/limit/sort parameters, but those are secondary to the core filtering workflow.

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

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

The description uses a specific verb ('Filter') and names the exact resource (MarketPing's universe of 5,400+ NSE/BSE companies) and scope (108 fundamental metrics). The 'find companies where…' phrasing makes its screening role unmistakable and distinguishes it from complementary siblings like `company_snapshot` or `screener_fields`.

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

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

It clearly states the intended use case: 'Use for find companies where… questions.' It does not explicitly name sibling tools to avoid, but the context is specific enough that an agent can route screening questions here. The factual-data caveat also helps prevent misuse for recommendation-style queries.

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 supply readOnlyHint, idempotentHint, and non-destructive status. The description adds valuable context: today's snapshot semantics, consecutive-day tracking, and a factual-only/no-recommendations stance.

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 front-loads the most important information: what the tool returns, followed by input requirement and caveats. The final disclaimer about MarketPing's policies is slightly redundant after 'never a rating' but still reinforces intended use.

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 enumerates the core return fields and input expectation well. It omits ordering or edge-case behavior, but those are not critical for a simple read-only lookup.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds meaning for the stack parameter by specifying it must come from list_stacks, which is useful provenance beyond the schema.

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

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

The description clearly states the resource (companies in one stack) and the returned fields, distinguishing it from list_stacks and stack_changes. It lacks an explicit verb like 'returns' or 'fetches', but the meaning is unambiguous.

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

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

It gives clear usage context: fetch a slug from list_stacks first, and treat membership as a fact about screens cleared today, not a rating. It does not explicitly name alternatives or when-not-to-use, but the boundaries are clear enough.

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, covering the safety profile. The description adds genuinely useful context beyond that: 'Factual data only — MarketPing publishes no buy/sell recommendations, no price targets and no IPO grey-market premium,' which discloses content boundaries an agent would otherwise learn only after calling the 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 zero waste: purpose/content in sentence one, usage timing in sentence two, content boundary in sentence three. The core purpose is front-loaded and every sentence 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 zero-required-parameter catalog tool, the description conveys what is returned ('labels, units and groups'), when to call it, and the factual-only scope. No output schema exists, so return format is lightly specified, but result size and pagination are minor concerns for a metadata catalog and the annotations cover safety.

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

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

Schema description coverage is 100%, and both parameters (group, featured_only) are well-documented in the schema itself. The description's mention of 'groups' as catalog content loosely ties to the group parameter but adds no operational 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?

The description states a specific purpose: enumerating the metrics available for filtering/sorting in run_screener, 'with labels, units and groups.' It explicitly names the sibling tool run_screener, making clear this is the catalog/reference tool while run_screener executes screens — no ambiguity about which sibling this is.

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?

'Call this before building a screen if you are unsure of a field name' gives explicit timing and the triggering condition for use. It stops short of naming when-not-to-use or listing alternative catalog tools, but the conditional is clear enough that an agent can decide correctly.

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, and non-destructive behavior. The description adds meaningful context beyond those annotations: results are factual-only, contain ids for fetch, and exclude recommendations, price targets, and grey-market premiums. This enriches the agent's expectations without contradicting the annotations.

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

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

The description is compact and front-loaded: it states the resource and verb first, then the id-to-fetch workflow, then the factual-data boundary. Every sentence serves a purpose, and no fluff or redundancy is present.

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 single-parameter search tool with rich annotations, the description is largely complete: it covers scope, return-value linkage to fetch, and content boundaries. It doesn't describe the exact response shape or define behavior relative to search_filings, but neither is essential for invoking this 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?

There is only one parameter, query, and the schema already describes it as 'What to search for' with 100% coverage. The description adds no additional syntax, format, or query-construction guidance, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource: search MarketPing's Indian stock market data, and enumerates the content types covered (companies, announcements, IPOs, annual reports, transcripts, presentations). It does not explicitly differentiate from the sibling search_filings, so it stops short of 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?

The description clearly communicates the intended workflow: search to get result ids, then pass those ids to fetch. It gives useful context about what to search but doesn't state when to prefer this over search_filings or other alternatives, so it lacks explicit 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 mark the tool as read-only, idempotent, and non-destructive, so the description's burden is lower, but it adds critical behavioral context: snippets are 'KEYWORD WINDOWS, NOT FACTS' and figures must not be cited from snippets. It also clarifies the data scope by stating that MarketPing publishes no recommendations, price targets, or grey-market premiums.

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

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

The description is compact and well-structured: it states the purpose first, then the output shape, then the critical snippet caveat, then the data scope. Every sentence earns its place, and the all-caps warning is an efficient way to emphasize a high-risk behavior.

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

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

For a two-parameter, read-only search tool with no output schema, the description is complete: it explains the search scope, return format, follow-up tool, snippet reliability limitation, and data boundaries. An agent has enough information to invoke it correctly and interpret results safely.

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; both query and company are already clearly described. The description adds useful context about the search corpus (annual reports, transcripts, presentations), but it does not need to explain parameter semantics further since the schema already does.

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

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

The description opens with a specific verb and resource: 'Full-text search across every page MarketPing holds', then enumerates document types (annual reports, earnings-call transcripts, investor presentations). It also names the exact return shape ({doc_id, page, snippet}) and points to read_pages as the intended follow-up, which clearly distinguishes it from generic sibling tools like search.

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

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

The description gives clear usage context: use it to search full text across MarketPing's document corpus, and follow up hits with read_pages. It does not explicitly state when not to use it or compare it against the sibling 'search' tool, but the follow-up routing provides enough practical guidance for an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the default date behavior, that it reports additions/removals/layer changes, and that results are factual data only with no recommendations. This goes beyond what annotations alone 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?

Two sentences, front-loaded with the core behavior and default, followed by a clear use case and a useful factual-data caveat. Every sentence earns its place with no redundant 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?

Given the tool has only two parameters, full schema coverage, and strong safety annotations, the description is largely complete. It explains the default date, scope of changes, and usage intent. It could clarify the term 'cleared more or fewer layers' slightly, but nothing essential is missing for an agent 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 schema documents both parameters well. The description adds extra meaning by explaining the default for `since` (previous daily snapshot) and clarifying `stack` as a slug from list_stacks, which helps the agent understand how to populate both fields correctly.

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 (a stack), the action (reporting what entered, left, or changed layers since a date), and the intended use case. It is distinguishable from siblings like list_stacks and run_stack by focusing on changes over time, though it does not explicitly name alternatives.

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

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

The description gives a concrete usage context: 'what is new in this list today / this week', and clarifies the default comparison point (previous daily snapshot). It does not explicitly state when not to use it or mention sibling tools as alternatives, but the context is clear enough.

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

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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds value beyond those by stating the linked-account requirement, plan limit, and that alerts are factual filings only—no recommendations, targets, or grey-market premium. It does not describe duplicate-company behavior, but idempotency is already annotated.

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

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

The first sentence front-loads the action and outcome, and the following sentences compactly cover account requirement, plan limit, and content type. The factual-data disclaimer is slightly broader than the tool itself but clarifies what alert content will contain, 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?

For a single-parameter, idempotent, non-destructive mutation tool, the description covers the action, effect, prerequisites, and constraints. It does not explain the response format, but with no output schema and low complexity, this is not a critical omission.

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 defines the single parameter as 'Company slug, NSE symbol, or UUID.' The description does not add parameter-specific meaning beyond naming the resource, 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?

Opens with a specific verb and resource ('Add a company to this MarketPing account's watchlist') and states the resulting effect (filings start arriving as alerts). This clearly differentiates it from sibling tools like watchlist_list, which lists the watchlist, even without naming them.

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 useful prerequisites and constraints: 'Needs a linked MarketPing account' and 'Subject to the plan's company limit.' However, it does not explicitly say when to use this tool versus alternatives like watchlist_list or resolve_company, nor does it provide any 'when not to use' guidance.

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

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

Beyond the annotations, the description reveals a hidden dependency on a linked MarketPing account and the assistant's connect-offer behavior. The 'factual data only' clause further clarifies content constraints and what the tool will not return. This is substantial value beyond 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?

Three sentences, each earns its place: what the tool returns, the prerequisite/assistant behavior, and the data fidelity caveat. It is 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?

For a zero-parameter, read-only tool, it covers purpose, prerequisite, and content limitations. With no output schema, it could specify the return shape or possible 'alert status' values slightly more, but it is sufficient 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?

The tool has zero parameters, so the baseline is 4; there is no parameter documentation burden. The description's account-level dependency is the only relevant semantic context and is adequately covered.

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: the companies the linked MarketPing account follows, along with their alert status. It avoids tautology by adding scope and content, though it lacks an explicit verb like 'list' and does not explicitly differentiate itself from sibling tools by name.

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

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

The description provides a concrete prerequisite ('Needs a linked MarketPing account') and a data limitation ('factual data only'), but it does not explicitly state when to use this tool versus alternatives such as watchlist_add or recent_alerts. The intended use is implied rather than spelled out.

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