Mfapi India

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by specifying the return format (per-model with score, confidence, signals, raw_response + combined view) and explaining the cost model for Anthropic. No contradictions with annotations.

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

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

The description is a single, dense paragraph of about 80 words. Every sentence serves a purpose: what it does, default behavior, optional configuration, return structure, and use cases. 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?

The description explains the return structure but omits details on score computation, signal types, error handling, rate limits, or data freshness. Given that there is no output schema, these gaps reduce completeness for a tool that sends external API 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 parameters are well-defined. The description adds practical context: default model is free, `_apiKey` is only for Anthropic, and `context` helps disambiguate. This goes beyond the schema's minimal 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 defines the tool's purpose: probing LLMs for entity knowledge and returning a visibility score per model. It uses specific verbs ('Probe', 'score') and distinguishes from sibling tools like 'deep_research' or 'scan_competitor_ai_presence' by focusing on quantitative scoring across multiple 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 provides clear usage context ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass the optional `_apiKey`. However, it does not explicitly state when NOT to use this tool or compare it with alternatives like `deep_research` or `entity_profile`, leaving some ambiguity.

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?

Description adds context beyond annotations: explains routing to specific tools, filling arguments, returning structured answers with citation URIs. Annotations already indicate non-destructive, read-only, idempotent behavior; description complements without contradiction.

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

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

Description is lengthy but well-structured: front-loads the key purpose, then provides usage guidelines, examples, and differentiation. Every sentence adds value, but could be slightly more concise by omitting some redundant examples.

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

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

Given the complexity (many sources, no output schema), description covers what the tool does, when to use it, how it works internally, and what the output contains (structured answer with citation URIs). No gaps for a tool of this nature.

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

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

Schema coverage is 100% with full parameter descriptions. Description adds value by stating the question is natural language and providing usage context, though schema already documents aliases. Slightly above baseline due to rich examples and guidance.

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 routes questions to 4,774 tools across 1,242 sources for authoritative structured data, distinguishing it from siblings like ask_pipeworx_grounded and deep_research. It uses specific verbs like 'routes' and 'returns' with a defined scope.

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

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

Explicitly tells when to use this tool (prefer over web search for factual questions) and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). Provides concrete examples of queries it handles.

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

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

The description adds significant behavioral context beyond annotations: it explains the internal process of tool selection and data fetching, the extraction of answers using only the tool result, and the explicit refusal reasons (not_in_source, no_tool_match, etc.). This complements the readOnlyHint and idempotentHint 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 relatively concise (5 sentences) and front-loaded with the core purpose. Every sentence provides useful information, though the list of refusal reasons could be slightly more compact.

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: it covers the return format (answer, evidence, confidence, etc.), refusal reasons, usage guidance, and cost. No output schema exists, but the description adequately documents expected outputs.

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 description does not need to add parameter detail. It does not go beyond the schema for individual parameters, which is acceptable. 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 clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads', specifying the verb 'ask' and resource 'pipeworx_grounded'. It distinguishes itself from its sibling 'ask_pipeworx' by emphasizing groundedness and refusal mechanisms.

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

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

The description explicitly states when to use (high-stakes reads where answers will be quoted or acted on) and when not to use (prefer ask_pipeworx for casual lookups), and mentions the cost trade-off of one extra LLM call.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: low-confidence resolution short-circuit, closed market handling, wide-spread market notes, resolution-rule risk, news fallback behavior, and parent event extraction. No contradictions with annotations.

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

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

The description is very long (multiple paragraphs) and exhaustive, which is helpful but not concise. It front-loads the purpose but then covers classifiers, fan-out examples, response shapes, resolver contract, etc., in a well-structured but verbose manner. Some information could be streamlined while retaining 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?

Given no output schema and moderate complexity (3 params, high schema coverage), the description covers every aspect: input formats, behavior, fan-out logic, response structure, edge cases (closed markets, low confidence, wide spreads), and safety warnings. It leaves no ambiguity for an AI agent to correctly invoke and interpret results.

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. Description adds value beyond schema by explaining the market input as accepting slug, URL, or question text, and by providing examples. It also clarifies the depth and include_raw parameters' behavior. However, the schema itself is already quite descriptive.

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

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

Description clearly states the tool researches Polymarket bets by pulling relevant data. It specifies multiple input formats (slug, URL, question text) and gives explicit use cases like 'should I bet on X'. This distinguishes it from siblings like polymarket_edges which focus on edge detection, and polymarket_arbitrage which focuses on spreads.

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

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

Description provides explicit use examples and fan-out scenarios. It does not explicitly state when not to use this tool versus alternatives, but the context signals include many sibling tools, and the description implicitly guides usage by its level of detail. A more explicit 'when-not' or alternative tool mention would elevate to 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 and idempotentHint, so safety is clear. The description adds valuable behavioral details: parallel call, off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is well-structured, starting with typical query phrases. It is comprehensive but not excessively long; every sentence adds value. Minor improvement could be tightening phrase examples, but overall efficient.

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 no output schema, the description covers return format ('paired data + pipeworx:// citation URIs'), explains data sources for both entity types, and specifies constraints (2-5 items). This provides complete context for agent 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%, but the description enriches semantics by explaining what each type pulls (e.g., 'type="company" pulls LATEST 10-K revenue + net income + cash + long-term debt') and that 'values' accepts tickers/CIKs or drug names. This goes beyond the schema.

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

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

The description explicitly states the tool performs side-by-side comparison of 2-5 companies or drugs, using phrases like 'compare X and Y' and 'head to head'. It distinguishes this from sequential single-entity lookups, making the purpose unmistakable.

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

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

The tool explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use. It does not discuss when not to use or alternative tools, but the primary use case is well-defined.

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

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

Adds significant context beyond annotations: account requirement, free/paid tiers, parallel decomposition, 15-60s response time, returns gaps[] for unanswerable facets, cites sources with pipeworx:// links, and notes that breaking news yields empty gaps. No contradiction with annotations.

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

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

Long (~200 words) but every sentence adds unique value. Front-loads critical info (account requirement, alternative tool). Could be slightly more concise, but complexity justifies length.

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?

Covers purpose, usage, prerequisites, behavior, limitations, expected latency, and output format. Given complexity and lack of output schema, description provides thorough guidance 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% but description adds value: explains each enum value's meaning (quick=3 facets, etc.), notes 'thorough' requires paid plan, and clarifies the question parameter accepts broad/multi-part natural language.

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?

Clearly states it performs grounded multi-source research across 1242 structured data sources, decomposes questions into facets, and returns a findings packet. Distinct from siblings like ask_pipeworx (single lookup) and ask_pipeworx_grounded.

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 instructs when to use (broad/multi-part structured data questions) and when not (single lookup: use ask_pipeworx; breaking news: prefer ask_pipeworx). Also mentions account requirement and alternative for unsigned users.

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, establishing safety. The description adds behavioral detail beyond annotations by specifying return format (top-N tools with names, descriptions, full input schemas with examples) and that results are ready to call directly. This enriches the agent's understanding of what happens when the tool is invoked.

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

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

The description is a single well-structured paragraph that front-loads the purpose, lists use cases, explains output, and gives a call to action. Every sentence adds value, with no redundancy or fluff. It is concise yet comprehensive.

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 that there is no output schema, the description fully compensates by clearly explaining what is returned (top-N tools with schemas and examples). For a discovery tool with 1 required parameter and clear annotations, the description covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all 6 parameters described). The description provides examples and clarifies that 'query' accepts aliases, but the schema already lists aliases with descriptions. The description adds minimal extra meaning for parameters; baseline 3 is appropriate as 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 clearly states the tool finds tools by describing data or task, listing many use cases and explicitly distinguishing it from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It uses specific verbs and defines the resource (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 says when to use this tool ('Use when you need to browse, search, look up, or discover what tools exist') and provides a clear directive to call it first for exploring options. It implies it is not for getting a single answer, which helps the agent decide against 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 indicate read-only, open-world, idempotent, non-destructive nature. The description adds details about fanning out across sources, soft-fail for patents, fallback for news, and parallel execution, going 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 lengthy but well-structured, starting with example queries, then usage advice, then details of sources and return fields. Every sentence adds value, though slightly verbose.

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 no output schema and the tool's complexity, the description comprehensively covers return fields, data sources, edge cases (patents soft-fail, news fallback, LEI), and parameter limitations, ensuring the agent understands the tool's capabilities fully.

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 good descriptions. The description adds context that type is currently limited to 'company' and clarifies that value can be ticker or CIK but not names, enhancing understanding beyond the schema.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with examples of user queries. It distinguishes from sibling tools like resolve_entity by specifying that names are not supported here.

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 advises to prefer this tool over chaining separate lookups for a holistic view, and instructs to use resolve_entity if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Description is consistent with annotations (destructiveHint=true). Adds context about clearing sensitive data, which annotations do not cover. No contradictions.

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

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

Two sentences that are front-loaded with the action, then usage context. 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 tool with full schema coverage and no output schema, the description is complete: it explains purpose, when to use, and how it relates to 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 coverage is 100% and the only parameter 'key' is well-described. The description adds no additional semantic information beyond 'by key'. 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 ('Delete') and resource ('a previously stored memory by key'). It clearly distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use ('when context is stale, the task is done, or you want to clear sensitive data'). Mentions pairing with 'remember' and 'recall', but does not explicitly exclude 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the fetch-and-extract process, the markdown output format, and deployment location. Does not contradict 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?

Concise, front-loaded with purpose, then process and output. Every sentence serves a function: what it does, how it works, what it produces, and example use cases. 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 low-complexity tool with rich annotations and full schema coverage, the description is mostly complete. It covers purpose, process, and output. Lacks edge-case behavior (e.g., unreachable sites, error handling), but these are minor given the tool's simplicity.

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 clear descriptions for both parameters. The description adds context by explaining how the URL is used (fetches page) and providing default/max for max_links. This enriches the schema without redundancy.

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

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

The description clearly states it generates a llms.txt file for any URL, listing specific actions (fetches page, extracts title/description/key links, emits markdown) and distinct use cases (client indexing, own project, competitor audit). It effectively differentiates from siblings like ai_visibility_check and scan_competitor_ai_presence.

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

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

Provides clear use-case examples ('getting a client's site indexed', 'drafting for own project', 'auditing competitor'), giving agents context on when to invoke. However, it lacks explicit exclusions or comparisons to alternative tools, leaving some room for ambiguity.

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, so the agent knows it's safe. The description adds value with 'newest first' ordering, listing return fields, and stating 'Keyless' (no authentication needed), which goes 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?

Two sentences: first sentence states purpose and result fields, second sentence provides usage hint. No waste, front-loaded with key 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?

Given the tool's simplicity (2 parameters, no output schema, well-covered by annotations), the description covers purpose, prerequisite, result ordering, and keyless access. It is complete enough for an agent to use 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 does not add additional meaning to parameters beyond what is in the schema; 'scheme_code' and 'limit' are adequately described in the schema itself.

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

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

The description clearly states it gets NAV history of a mutual fund scheme, listing specific fields (fund house, category, ISIN, latest NAV, recent NAV points) and distinguishes from the sibling tool 'latest_nav' which likely returns only the latest NAV. The verb 'get' with resource 'nav history' is specific.

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 advises using 'search_schemes' to find a scheme_code first, providing a clear prerequisite. It does not explicitly state when not to use it, but the context implies this tool is for history and 'latest_nav' for single point, which is adequate guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by noting the tool is 'Fast' and 'Keyless', giving the agent context about performance and access requirements beyond the 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?

The description is concise with two sentences: the first defines purpose and output, the second provides usage guidance. Every sentence adds value, and the most important information 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the purpose, output (NAV, date, metadata), parameter guidance, and hints about performance and access. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with one parameter that has a description. The description adds an example ('e.g. 118550') and directs to search_schemes for obtaining the code, which enhances understanding beyond the schema alone.

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 'lookup' and the specific resource 'latest NAV of a mutual-fund scheme'. It distinguishes itself from sibling tools like get_nav_history and search_schemes by specifying a single-value lookup and referencing the need to find a scheme_code first.

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 instructs to 'Use search_schemes to find a scheme_code first', providing clear guidance on prerequisite steps. However, it does not mention when not to use this tool or explore alternatives, but for a simple lookup this is adequate.

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. Description adds the returned fields and default active-only behavior, offering extra transparency 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?

Two sentences plus a usage sentence, all front-loaded and efficient with 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 list tool with annotations and high schema coverage, the description is complete – it covers purpose, usage, and return format.

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 the parameter. Description implies default behavior (active only) but does not add significant new meaning.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies returned fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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 suggests using this to review subscriptions before adding more or to find an id to cancel, providing clear when-to-use context.

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

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

The description discloses rate limiting (5 per identifier per day), cost (free), and quota impact (doesn't count against tool-call quota). It also explains how feedback is processed (team reads digests daily, affects roadmap). All annotations are false, and the description adds value beyond them.

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

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

The description is a single paragraph that efficiently covers purpose, usage guidelines, and constraints. Every sentence is informative, no fluff. It is front-loaded with the main purpose and then 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?

Given no output schema, the description explains what happens after submission (team reads daily, effects on roadmap) and provides all necessary context for the agent to use the tool correctly. It covers rate limits, quota, and what to avoid.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'type' enum usage in the context of scenarios, and for 'message' it specifies character limit (2000) and suggests 1-2 sentences. It also clarifies that context is optional and structured. This exceeds the schema's descriptions.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team, listing specific use cases: bugs, missing features, data gaps, and praise. It uses a specific verb 'tell' and resource 'Pipeworx team', and distinguishes from sibling tools by its unique 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 provides explicit guidance on when to use the tool for each feedback type (bug, feature, data_gap, praise) and explicitly states what not to do ('don't paste the end-user's prompt'). It also mentions rate limits and quota, giving clear context for usage.

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, etc. Description adds valuable behavioral context: data source (CF analytics-engine), no PII, structure (pack, tool, count), caching behavior (5min-1h). No contradiction with annotations.

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

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

Three sentences, front-loaded with main function, then use cases, then technical details. Every sentence adds value; no redundancy or fluff.

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

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

Despite no output schema, description explains output details (top tools, packs, call volume) and caching behavior. Annotations cover safety. All necessary context is provided for the tool's simplicity.

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% (one parameter with description). Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the enum 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?

Description clearly states the tool returns trending data (top tools, packs, call volume) from other AI agents, specifying the resource (calling data) and action (returns). It distinguishes from siblings like 'discover_tools' by focusing on aggregate usage trends.

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 provides three use cases: discovering hot data sources, confirming canonical tool choice, and checking use case alignment. Does not list when not to use or compare directly with 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?

Discloses detailed behavioral traits beyond annotations: semantic anchor (Jaccard similarity), partition filter for placeholder slugs, fill check against live CLOB depth, and conditions when trades are not advisable. Annotations declare read-only and idempotent, which align with the description's non-execution nature.

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 with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loads the main purpose. However, it is somewhat verbose; while every sentence adds value, it could be slightly more concise.

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

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

Despite the lack of an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill check) and covers complex behaviors like cross-event scanning, similarity thresholds, and placeholder filtering. It is complete for a sophisticated arbitrage scanning 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 100%, and the description adds substantial meaning beyond the schema: explains differences between event and topic modes, gives concrete input examples, and describes the internal processing (e.g., walking child markets, partition checks).

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing between no-args, event, and topic modes. It is specific and differentiates from sibling tools like polymarket_edges or polymarket_fill_risk.

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 when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Provides examples of event slugs and seed questions. Mentions when not to trade (realizable_edge_pp <= 0), but does not explicitly compare to sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint all false/true. The description adds significant behavioral context: caching (1h at KV level), detailed computation of edges, model families, tradeable-edge knobs, and diagnostic information explaining why segments might be empty. No contradictions with annotations.

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

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

The description is very long and contains extensive technical detail. While well-structured with sections in caps, it is not concise and may overwhelm quick comprehension. Every sentence adds value, but the overall length reduces efficiency.

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

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

Given the tool's complexity (9 parameters, multiple model families, nested response) and lack of output schema, the description comprehensively covers the return format, caching, diagnostics, Fed handling, and parameter knobs. It leaves no major gaps.

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 adds extra meaning by explaining knob interactions (e.g., min_kelly vs min_partition_leg_kelly) and use cases (e.g., 'Tradeable-edge filter' for max_spread_pp). This goes beyond the schema descriptions.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and resources ('Polymarket markets', 'opportunities'). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection from model disagreement.

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 targets 'what should I bet on today' and explains that Fed bets are excluded from ranking. However, it does not provide explicit guidance on when to use this tool versus siblings like polymarket_arbitrage, polymarket_edge_tracker, or polymarket_fill_risk, which limits differentiation.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: that data is built from daily snapshots, returns three arrays (tracked, expired, snapshot_dates), explains decay computation (on absolute value), and notes that gaps in snapshot_dates occur when no scan happened. No contradictions with annotations.

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

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

The description is relatively long but well-structured: a concise opening sentence, then explanation of the response structure (tracked, expired, snapshot_dates) each with clarifications, and finally limits. Every sentence adds necessary detail, though some minor redundancy could be trimmed. It is front-loaded with the core purpose.

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

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

Given the moderate complexity (time-series data, multiple response fields) and no output schema, the description is very complete. It covers the three return arrays, their subfields (trend, decay_pp_per_day, lifespan_days, etc.), and limitations (TTL, gaps). For a tool without an output schema, this level of detail is fully adequate.

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 descriptions for both parameters. The description adds value by clarifying the default values (days=14, window='1wk') and cross-referencing window to 'polymarket_edges window family', providing meaning beyond the schema. It also explains the clamp range for days and the interpretation of window as a snapshot family.

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

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

The description explicitly states that the tool provides 'edge persistence and decay telemetry' and answers a specific trading question: 'how long has this edge existed and is it shrinking?' It differentiates from sibling tools like polymarket_edges by focusing on historical tracking rather than current edges, and uses specific verbs ('track', 'answer').

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

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

The description gives explicit usage guidance: 'a fresh wide edge and a 3-week-old wide edge are different trades', implying when to use this tool (to assess edge age). It also includes a 'LIMITS' section describing history depth, snapshot TTL, and when data might have gaps, helping the agent understand constraints. Sibling tools like polymarket_edges are implicitly alternatives for current edges.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns by describing the tool as a check/analysis that does not modify state. It adds behavioral context: walks the ladder, returns fill details and a verdict, and warns about partial fills and forced directional risk. No contradiction.

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

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

The description is long but well-structured with clear sections for single-market and basket modes. It front-loads the key purpose and uses all-caps for critical instructions. Every sentence adds value, though some could be condensed slightly for a 400-char target. Overall, appropriate for the tool's complexity.

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

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

Given the tool's complexity (two modes, numerous return fields), the description is comprehensive. It lists return values like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for basket mode: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. Without an output schema, this is essential and 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%, but the description adds significant meaning: it clarifies the interpretation of `size_usd` in basket mode (settlement notional), explains the default `side` behavior for basket (auto from partition sum), and describes how each parameter affects the two modes. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) with specific use cases, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable) and warns about risks (partial basket fills convert arb into unhedged directional position).

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?

Discloses two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). Explains conditions for meaningless spreads. No contradiction with annotations (readOnly, openWorld, idempotent).

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 well-structured: definition, modes, response, safety fields. Slightly verbose but every sentence adds value. Front-loaded with purpose.

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

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

Given complexity, schema, and no output schema, description is thorough: covers input, behavior, output, edge cases, compatibility warnings, temporal alignment. Essential for correct usage.

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

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

Schema coverage is 100%, but description adds value by listing the ten pre-mapped topics, explaining the override mechanism, and giving examples. Provides meaning beyond property names.

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?

Clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' Distinguishes from sibling tools like polymarket_arbitrage. Specific verb+resource.

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

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

Explains two modes (topic shortcuts vs explicit tickers), warns that most pre-mapped topics return compatibility_warning, and details safety fields that indicate when spreads are not meaningful. Provides clear context on when to use and when spreads may be invalid.

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 and idempotentHint=true, so the description adds context about scoping to the agent's identifier and pairing with 'remember' and 'forget'. No contradictions and adds useful behavioral detail.

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 concise sentences: first explains functionality (retrieve or list), second explains use case and scoping. No unnecessary words, front-loaded with essential 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?

Given the simple schema (one optional param, no output schema), the description covers the tool's purpose, usage (omit key for list), scope, and pairing with siblings. It is complete for effective agent 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%, but the description adds meaning: omitting the key argument lists all keys. This clarifies behavior beyond the schema, which only shows examples. The description provides the intended usage for the optional parameter.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all saved keys when the key argument is omitted. It specifies verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools like 'remember' and 'forget'.

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 explains when to use: to look up context stored earlier without re-deriving it. It implies alternatives through pairing with 'remember' and 'forget', but does not explicitly state when not to use. The scope (by identifier) is mentioned, providing sufficient 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 indicate read-only and idempotent behavior. The description adds useful context about the return format, filtering, and the mark_read feature affecting subsequent calls. No contradiction with annotations.

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

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

Three concise sentences with no wasted words. Front-loaded with purpose, then details on return fields and filters, then mark_read and polling. Efficient and well-structured.

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

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

Given 5 optional params and no output schema, the description covers the core functionality, return format, filtering, and mark_read. It mentions an alternative endpoint. Minor gaps on limit and unread_only, but schema covers those.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by providing an example type ('sec_8k') and explaining the effect of mark_read, but does not elaborate on limit or unread_only 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 'Pull fired events from your subscription feed' with specific verb and resource. It mentions return fields and filtering, but does not explicitly differentiate from siblings like list_subscriptions or subscribe.

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 for retrieving recent alerts and notes that polls work fine, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it compare to 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 declare readonly, openWorldHint, idempotent, and non-destructive. The description adds detailed behavioral context: fans out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return structure with changes, total_changes, and citation URIs. No contradictions.

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

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

The description is relatively long but well-structured. It starts with example queries, explains sources, parameter details, and sibling guidance. Every sentence adds value, though it could be slightly more compact without losing 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?

Given no output schema, the description adequately explains what is returned (structured changes grouped by source, total_changes, citation URIs). It covers the `since` parameter format and sources. Minor gaps include error handling details, but overall complete for a tool of this complexity.

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

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

Input schema provides 100% coverage with descriptions. The description adds value by providing examples for 'since' (ISO date and relative shorthand) and typical usage ('Use "30d" or "1m" for typical monitoring'). This exceeds the baseline of 3 for full schema coverage.

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

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

The description clearly states it provides a change feed for a company, listing multiple natural language queries and detailing the sources (SEC, GDELT/GNews, USPTO). It explicitly distinguishes from sibling tool 'entity_profile', which returns static profiles.

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 includes explicit guidance on when to use this tool vs alternatives, such as 'Use entity_profile instead when you want the static profile...'. It also provides example queries and typical parameter values like '30d'.

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

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

Adds details beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations (idempotentHint=true, readOnlyHint=false, etc.).

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

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

Four sentences, front-loaded with purpose. Every sentence is informative and necessary. No fluff.

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

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

Given the tool's simplicity (no output schema, few parameters), the description fully covers usage, persistence, and integration with sibling tools. Complete and actionable.

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 already covers both parameters with descriptions. The description adds concrete examples for key (e.g., 'subject_property') and value ('findings, addresses'), enhancing 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 states 'Save data the agent will need to reuse later' with specific verb and resource. It gives concrete examples (resolved ticker, target address) and distinguishes from sibling tools like recall and forget.

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 says 'Use when you discover something worth carrying forward' and pairs with recall (retrieve) and forget (delete). Provides context on when to use and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds value by explaining internal cascading through lookup endpoints and detailing output formats (ticker, CIK, RxCUI, citation URIs), which goes beyond what annotations provide.

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

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

The description is well-structured with front-loaded example queries, followed by type details. Every sentence adds value—no fluff. It packs a lot of information (two entity types, input variations, output specifics, citation URIs) without being overly verbose.

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

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

Despite no output schema, the description fully explains return values for both entity types, including fields and citation URIs. It covers all necessary context for an agent to understand inputs (type, value) and outputs, making it complete 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% and already describes parameters. The description adds meaning by providing examples (ticker, CIK, drug names), clarifying acceptable inputs for each type, and explaining the output structure. This enriches the parameter semantics significantly.

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 specific verbs ('resolve', 'look up'), specifies the resource ('name to canonical/official identifier'), and distinguishes from other tools by stating 'Use FIRST whenever you have a name but need an ID.' It also lists example queries and supported types, making the purpose crystal 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?

Explicitly states 'Use FIRST whenever you have a name but need an ID,' providing strong when-to-use guidance. It also mentions that it replaces 2-3 manual lookups, implying efficiency. While it doesn't explicitly state when not to use, the directive 'FIRST' covers most 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?

The description discloses key behaviors: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. Annotations already declare read-only, idempotent, open-world; description adds context about the probing and ranking process without contradiction.

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

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

Four sentences, front-loaded with action and outcome, no unnecessary words. Every sentence adds value: first states purpose, second explains mechanism, third gives use case, fourth describes return format.

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

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

Despite having no output schema, the description fully specifies the return format (ranked list with score, confidence, signal density per entity). Annotations cover safety and behavior. The description is complete for a tool with this complexity and good 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?

Schema coverage is 100%, so baseline is 3. The description does not add additional parameter meaning beyond what the schema already provides (e.g., models, _apiKey, context, entities). It mentions context implicitly but not with extra detail.

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 it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This clearly differentiates it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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 it's useful for competitive AI-marketing audits (e.g., comparing brand recognition). It implies this is for multi-entity comparison, which distinguishes it from single-entity tools, but lacks explicit when-not-to-use or alternative recommendations.

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, openWorld, idempotent, and non-destructive. The description adds behavioral details about partial failures and latency on first bundlephobia measurement, which goes 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?

Description is informative and front-loaded with the core purpose, but slightly verbose. Every sentence contributes value, making it acceptable.

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 no output schema, the description fully explains the return structure (summary block, details, links, alternatives) and covers edge cases like partial failures, ecosystem limits, and latency.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful context for 'package' (scoped packages accepted) but repeats the schema's default behavior for 'version'. No additional semantics beyond what schema provides.

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

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

The description explicitly states the tool performs a composite check for npm packages, combining deps.dev and bundlephobia data, and clearly distinguishes its purpose from sibling 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?

Provides clear usage scenarios (e.g., 'is X safe / popular / small') and notes the NPM-only scope, but does not explicitly list when not to use it compared to direct deps.dev 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 declare readOnlyHint and idempotentHint, but the description adds crucial behavioral details: it downloads the full list (~16k schemes, 1-2MB) and filters client-side, and notes 'keyless' operation. 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 concise: a few sentences front-load the purpose and provide essential details without fluff. Every sentence adds value.

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

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

Given the tool complexity (searching through 16k items), the description covers purpose, behavior, usage, constraints, and relationship to sibling tools. No output schema, but return values are implied.

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 description does not repeat schema. However, it adds meaning to the query parameter by explaining the case-insensitive token match algorithm. For limit, defaults are already in schema. Overall adds value.

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

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

The description clearly states it finds Indian mutual-fund scheme codes by fund name, specifying verb 'search', resource 'scheme codes', and domain. It distinguishes from siblings by noting this is the way to obtain scheme_code for get_nav_history and latest_nav.

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

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

The description provides clear context on when to use this tool (to find scheme codes) and explains matching behavior. However, it does not explicitly state when not to use it or list alternative tools for similar purposes.

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 annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral details: embedding model (BGE-base-en), windowing (500-char overlapping), character offsets for verification, and a 200K char cap with truncation. No contradiction with annotations.

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

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

The description is front-loaded with the core idea, then progressively adds details. Every sentence serves a purpose without redundancy. Highly concise.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers output format (passages with offsets and scores), technical details (embeddings, windowing, cap), and usage pairing. It is fully adequate for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value with real-world examples for 'query' and clarifies the 'text' parameter's purpose ('the text you already pulled'). This extra context justifies a 4.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record', specifying the resource (record text) and action (search). It distinguishes from siblings like 'ask_pipeworx_grounded' by explaining the fetch-then-search workflow.

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 explains when to use the tool ('when the record is too big to cram into the prompt') and pairs it with 'ask_pipeworx_grounded'. It provides clear context but does not explicitly list exclusion scenarios.

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 idempotency and non-destructive. Description adds constraints like 10/day SMS cap, webhook auto-disable after 10 failures, and OAuth requirement, enhancing transparency.

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

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

Well-structured with key info front-loaded. Each sentence adds value, though slightly verbose due to type 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?

Fully covers parameters, delivery channels, constraints, and OAuth requirement. Even without output schema, return value is stated. Sibling tools provide lifecycle context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds detailed examples and validation rules beyond schema descriptions, such as phone verification and webhook signing.

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?

Clearly states it creates a subscription and returns an ID. Missing explicit differentiation from sibling tools like 'list_subscriptions' or 'unsubscribe'.

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 prerequisites (OAuth account) and lists supported types with examples. Does not explicitly state when not to use or compare to 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's additional details about returning example questions and being drawn from a live catalog add value without contradicting. No behavioral surprises 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 front-loaded with common user queries and is well-structured. While it is somewhat verbose, every sentence adds value, and it avoids redundancy with 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?

With only one optional parameter, no output schema, and rich annotations, the description fully covers the tool's purpose, usage, and expected output (example questions with tool+argument shapes). It is complete for an onboarding 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 100% with a description for the optional 'topic' parameter. The description adds extra meaning by listing example values and explaining that omitting it returns a cross-category spread, exceeding the schema's baseline.

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 it is the 'onboarding entry point' that returns category-bucketed example questions with exact tool and argument shapes. It clearly distinguishes from sibling tools like discover_tools and ask_pipeworx by being the first tool to use when the agent doesn't know what Pipeworx can do.

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 says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with or without the 'topic' argument. It mentions meta-tools but does not list explicit when-not-to-use scenarios or contrast with 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?

The description adds behavioral context beyond annotations: it explains that the subscription is deactivated (not deleted), and historical events remain available. This aligns with destructiveHint=false and idempotentHint=true.

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, front-loaded with the main purpose, and every sentence adds value 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 simple tool with no output schema, the description covers behavior and side effects well, but does not mention the return value or response format.

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, the baseline is 3. The description mentions 'by id' but does not add meaning beyond the schema's explanation of the id parameter.

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

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

The description clearly states the action ('Cancel a subscription') and the resource ('subscription'), and distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 when to use (to cancel a subscription) and includes a key constraint (ownership enforcement), but does not explicitly mention when not to use or list 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing the return format (verdict types, citation, percent delta) and domain constraints. No contradictions with annotations.

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

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

The description is front-loaded with use-case triggers and structured logically. While slightly verbose, it efficiently conveys key information 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?

Given the simplicity (one parameter, no output schema) and rich annotations, the description covers the return values, domain, and efficiency benefits comprehensively. No gaps remain for effective tool 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 description coverage is 100% with a clear description of 'claim' parameter including examples. The tool description reiterates the domain but adds no additional parameter semantics beyond the schema, warranting the baseline score.

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 defines the tool as a claim verifier using trigger phrases like 'fact check' and 'verify the claim that...' and specifies it supports company-financial claims. It distinguishes itself by replacing multiple sequential calls, making its 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 explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the domain limitation to company-financial claims. It implies when not to use by specifying v1 limitations, though it doesn't explicitly list alternatives.

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