Bnm My

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details that the default model is Workers AI Llama-3.3-70b (free), Anthropic requires a BYO key, and returns per-model and combined views. No annotation 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 two sentences, front-loaded with core action and output, then adds cost details and use cases. Every sentence earns its place; no redundancy.

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

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

No output schema, but the description specifies return format (per-model data + combined view). Missing details like error handling or rate limits, but annotations (idempotent, readOnly) mitigate this. Overall sufficient for an AI agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model, why _apiKey is needed, and that context helps disambiguate common names. This enhances understanding beyond 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 tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model, specifying the default model and optional Anthropic. This differentiates it from siblings like deep_research or 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?

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and distinguishes usage (default free model vs paid Anthropic). It lacks explicit when-not-to-use guidance but provides adequate 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes to sub-tools, returns structured answers with pipeworx:// citation URIs, works on every tier, and is a single fast call. It does not mention any side effects, which is consistent with a read-only tool. Slight deduction because it doesn't detail error behavior or rate limits, but these are minor given the read-only 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?

Though long, every sentence carries information: prioritization, scope, examples, alternatives, and default status. It is front-loaded with 'PREFER OVER WEB SEARCH' to immediately convey the tool's role. The structure flows from 'what' to 'when' to 'alternatives', with no filler.

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

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

There is no output schema, so the description compensates by stating it returns 'structured answer with stable pipeworx:// citation URIs'. It also covers tier compatibility, speed, and alternative tools. For a meta-query tool of this complexity, the description provides everything an agent needs to decide and invoke it correctly.

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

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

Schema coverage is 100% with all aliases documented. The description adds semantics by giving concrete example questions ('What was Apple's revenue in 2024?') and explaining that the question is accepted in natural language. It doesn't need to explain parameter formats because the schema is complete. The examples effectively illustrate usage, which raises it above baseline 3.

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

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

The description states a specific verb ('routes the question') and resource ('5,724 tools across 1497 verified sources'), clearly differentiating it from web search and siblings. It explicitly says 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA, FRED, etc.) that make the purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Use whenever the user asks...' with examples. It also gives when-not-to-use: 'Step up only when needed' for ask_pipeworx_grounded and deep_research, naming alternatives and the conditions that select them. This is comprehensive routing 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 handle safety traits (read-only, idempotent, non-destructive), and the description adds meaningful behavioral context: it reflects the experimental edge, the current state of no active candidate, and that it is a full working router rather than a fallback stub. No contradiction exists.

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

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

The description is compact and front-loaded: the first sentence states the core purpose and relationship to ask_pipeworx, and each following sentence adds useful context (current state, usage, comparison purpose, fallback clarification). Minor redundancy in repeatedly emphasizing parity with ask_pipeworx keeps it from being a 5.

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

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

For a tool with rich annotations and full schema coverage, the description covers the essential invocation context: what it does, how to use it, its current experimental state, and how it differs from the stable router. It does not detail return formatting, but it states the response shape matches ask_pipeworx, which is sufficient given no output schema.

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

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

Schema coverage is 100% and all six parameters are documented as aliases for the required 'question' field. The description mentions 'same arguments' but adds no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

Clearly identifies its role as a beta version of ask_pipeworx, the fact that it is a universal router, supports 5,724 tools, and shares the same arguments and response shape. The description distinguishes it from the stable ask_pipeworx by labeling it experimental and noting candidate routing improvements.

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

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

Provides explicit usage context: use this when you want the newest routing, and results are compared against the stable router. It does not list formal exclusions or compare to ask_pipeworx_grounded, but the guidance about identical usage and current parity with ask_pipeworx 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses the strict no-invention constraint, the explicit refusal mechanism with specific refusal_reason values, the exact success return shape, and the extra LLM call cost. This is substantial behavioral context that annotations alone would not 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 dense but every sentence earns its place: mode, behavior, return shape, refusal reasons, usage guidance, and cost comparison. Key constraints are front-loaded ('only what the tool result contains'), and the sibling comparison is included 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 question-answering tool with no output schema, the description fully covers the success contract, refusal contract, and selection criteria. The agent has everything needed to invoke it correctly and interpret its result.

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 all six parameters documented as aliases for the natural-language question. The description adds no parameter-specific semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains the full behavior: same routing as ask_pipeworx, then extraction 'using ONLY what the tool result contains.' This clearly differentiates it from ask_pipeworx and the siblings without requiring schema inspection.

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

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

Explicit guidance is given: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This directly tells the agent both when to choose this tool and when to choose its sibling, with concrete examples like financial verdicts and legal claims.

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 extensively details behaviors beyond annotations: low-confidence short-circuits, closed market handling, wide spread illiquidity, resolution-rule risk, parent event extraction, news fallback fields. Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, none of which are contradicted.

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-organized with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Every sentence adds value for understanding complex behavior. Slightly verbose but appropriate given tool 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?

Despite lacking an output schema, the description fully covers return structure (result.market, result.analysis, result.evidence, match confidence) and edge cases (closed markets, low confidence, wide spread, cancellation rules). No gaps for an agent to invoke correctly.

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

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

Schema covers 100% of parameters with descriptions. The description adds context: default depth is 'thorough', include_raw=false recommended to keep responses under 20KB, and explains how parameters affect behavior (e.g., raw data size).

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 researches Polymarket bets by pulling Pipeworx data, specifies input types (slug, URL, question text), and outlines the output (evidence packet + comparison). It distinguishes from sibling tools like polymarket_edges by focusing on comprehensive research with fan-out to multiple data sources.

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

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

Explicit use cases are provided: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also gives fan-out examples per classifier and instructs to inspect result.market_match_confidence before trusting analysis, including handling of low-confidence matches.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds behavioral context about returning an array of bank entries and that no parameters are required, which is useful beyond the annotations.

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

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

The description is mostly concise but contains a redundant fragment 'Malaysian financial institutions to Bank Negara Malaysia.' This adds no value and disrupts flow. The first two sentences are clear.

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 the return is an array of bank entries with current rate levels and lists three specific rates. However, it does not detail the fields within each entry, leaving some ambiguity about the data structure.

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 zero parameters, the schema coverage is 100%. The description confirms no parameters are required, which is sufficient. Baseline for 0 params is 4.

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

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

The description clearly states it fetches the latest Base Rate, Base Lending Rate, and indicative effective lending rate for Malaysian financial institutions. The tool name and title align, and it is distinguishable from sibling tools like bnm_exchange_rates and bnm_policy_rate_opr.

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 use for retrieving Malaysian base rates but does not explicitly state when to use this tool versus alternatives like bnm_policy_rate_opr or bnm_exchange_rates. No exclusions or context about preconditions are provided.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds detail about returning raw data and confirmed live paths, which aids reliability without contradicting 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 a single paragraph, efficiently stating purpose, examples, and usage notes. It front-loads the core action and provides necessary detail without verbosity.

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 role as a catch-all for BNM endpoints, the description covers base URL, valid paths, and query parameter usage. It lacks specifics on error behavior or rate limits, but annotations and sibling context reduce the need for such details.

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

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

Schema has 100% coverage with descriptions for both path and query. The description adds concrete examples (e.g., interest-rate, exchange-rate/USD) and clarifies formatting (no leading slash), enhancing clarity 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 calls any confirmed BNM public endpoint by path and returns raw data. It lists multiple specific paths (e.g., interest-rate, kl-usd-reference-rate) and distinguishes itself from dedicated tool siblings.

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

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

Explicitly says to use this tool for paths not covered by a dedicated tool, e.g., 'if you need a path not covered by a dedicated tool.' Provides confirmed live paths as examples, but does not explicitly state when not to use it 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that rates are per session and quote basis, returns buying/selling/middle rates, and clarifies default behavior (all currencies) and constraints (date requires currency). 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, front-loaded with main purpose and immediate details. Every sentence adds value with no waste.

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

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

Covers all key aspects: source, currency options, date, session, quote basis, output types. With annotations providing safety profile and no output schema, it is sufficiently complete for an agent to use.

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 detailed parameter descriptions. The description adds context about session snapshots, quote basis, and output rates, providing 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 the tool retrieves foreign exchange rates against MYR from Bank Negara Malaysia. It specifies options for latest rates, one currency, or historical date, distinguishing it from sibling tools like bnm_base_rate or bnm_gold_kijang_emas.

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 (latest rates, by currency, historical date) with examples. It does not explicitly state when not to use or compare to alternatives, but it is adequate for an AI agent to select correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that prices are in MYR, by coin size, and that latest prices are returned by default or historical per year+month. 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?

Two sentences: first defines what is returned, second explains default vs historical. Front-loaded, no waste, every sentence earns its place.

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

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

No output schema; the description does not explain return structure (e.g., format of prices per coin size). Could be improved by specifying whether buying/selling prices are separate fields or showing an example.

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 year and month. The description reinforces that without parameters gives latest prices, adding slight value but not significantly beyond 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 it returns buying and selling prices of Kijang Emas gold coins in MYR by coin size. It specifies default latest prices or historical with year+month, distinguishing it from sibling BNM tools like bnm_exchange_rates.

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 implicitly indicates use for gold coin prices, but does not explicitly state when not to use it or mention alternatives like bnm_exchange_rates. However, the context of sibling tools makes it clear.

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

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

The description adds behavioral context beyond annotations by stating the default behavior (latest decision) and the additional fields returned when a year is specified ('change_in_opr', 'new_opr_level'). 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 two concise sentences, front-loading the core purpose and then explaining the parameter's effect. No redundant 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 tool with one optional parameter and no output schema, the description fully covers the needed context: default behavior, optional year, and what data is returned. It is complete for an agent to invoke correctly.

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

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

The description adds significant meaning to the year parameter: omitting it returns the latest OPR level, while including it returns every decision for that year with change and new level. This goes beyond the schema's description, which only defines the parameter as 'Four-digit year'.

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

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

The description clearly identifies the tool as retrieving Overnight Policy Rate (OPR) decisions from Bank Negara Malaysia, specifying the resource (OPR) and action (retrieve). It distinguishes from sibling tools like 'bnm_base_rate' by explicitly naming OPR and referencing benchmark monetary policy.

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: default returns the latest OPR decision, while providing a year returns all decisions for that year with change and new level. It does not explicitly state when not to use it, but the context is sufficient for a simple retrieval 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?

Beyond annotations, the description discloses sorting by primary metric, handling of off-calendar fiscal years, and the inclusion of pipeworx:// citation URIs. 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 well-structured and front-loaded with trigger phrases, but slightly verbose. Every sentence adds value, yet minor trimming could enhance conciseness 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 sufficiently covers return format (paired data + citations), entity scope, and data sources. It addresses when to use, parameter details, and behavioral notes, making it complete for the tool's 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?

Although schema coverage is 100%, the description adds significant meaning: for type='company' it details the financial data (10-K revenue, net income, etc.) and for type='drug' it specifies FAERS data, FDA approvals, and trials. Values parameter is clarified with examples (tickers vs drug 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?

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, specifying the data pulled for each type. It distinguishes itself from sibling tools like entity_profile by noting it replaces multiple sequential lookups.

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 natural language triggers ('compare X and Y', 'which is bigger') and instructs to 'ALWAYS PREFER over sequential single-pack lookups', giving clear when-to-use guidance 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?

The annotations already mark it read-only, idempotent, and non-destructive, so the description adds substantial behavioral context: account and paid-tier requirements, parallel tool routing, findings packet structure, gap[] behavior that never invents answers, contradiction scans, excerpting of large records, and expected latency. 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 long but information-dense; it front-loads the critical account requirement and the main alternative before explaining mechanics. Every major clause contributes distinct operational or selection guidance, though a little trimming and structuring could make it easier to scan.

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 thoroughly explains the return format (verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop field), access constraints, latency, and fallback paths. Nothing essential is missing for an agent to both select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: depth:'quick' is effectively a single hop, 'standard' is the default with gap recovery, and 'thorough' is paid and chases leads. It also clarifies that the question can be broad and multi-part because decomposition is the point, reinforcing 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 states a specific verb and resource: multi-source research across Pipeworx's structured data sources, decomposing questions and routing to parallel tools. It explicitly distinguishes itself from open-web search and from sibling ask_pipeworx, so an agent can select it accurately.

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

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

Provides explicit when-to-use and when-not-to-use guidance: best for broad/multi-part questions over structured data, use ask_pipeworx for single lookups and for breaking/current-news topics, and use ask_pipeworx if not signed in. It also explains depth-tier selection for further usage direction.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds behavioral details: returns top-N tools with schemas and examples, ready to call directly. 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 information-rich and front-loaded with purpose. Every sentence adds value, though slightly verbose. Could be trimmed slightly but still 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?

Despite no output schema, the description explains the return format clearly (top-N relevant tools with schemas and examples). Complete for a tool-discovery function.

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%. Description provides example query values but adds no semantic meaning beyond what the schema's parameter descriptions already convey.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself as a discovery tool vs. siblings that are concrete 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?

Explicit guidance: 'Use when you need to browse, search, look up, or discover...' and 'Call this FIRST when you have many tools available and want to see the option set.' Clearly differentiates from directly answering a single question.

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

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

Annotations already mark it as readOnly, openWorld, idempotent, non-destructive. The description adds detailed behavior: fan-out across multiple sources, output fields, URIs, caveat about patents sunsetting, and soft-fail behavior. 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 and front-loaded with example queries, but it is somewhat long. Every sentence adds value, but could be slightly more condensed without losing clarity.

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 fully covers the tool's purpose, usage, input constraints, output expectations, and edge cases (e.g., patent sunset). It references sibling tools appropriately. No gaps given the complexity and lack of output schema.

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

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

Schema coverage is 100% with clear descriptions. The description adds context: type is limited to 'company', value must be ticker or CIK (not name), and directs to resolve_entity for name resolution. This enriches the schema information.

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 in ONE parallel call' and gives specific example queries. It distinguishes itself from chained lookups and references sibling tools like resolve_entity for name resolution.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and warns about input restrictions: 'names not supported (use resolve_entity first if you only have a name).'

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 destructiveHint=true, so the description does not need to repeat that. It adds context about why to use it (clear sensitive data) but does not disclose behavior for missing keys or side effects beyond deletion.

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

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

Two sentences, zero wasted words. The first sentence states the action, the second adds usage guidance. 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 the tool's simplicity (one parameter, no output schema, annotations present), the description is fully complete. It covers what, when, and how, leaving no ambiguity for a retrieval-augmented agent.

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

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

Schema coverage is 100% and the description of the 'key' parameter is identical to the schema's description. No additional semantic value beyond what the schema provides, so 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 uses a specific verb ('Delete') and resource ('previously stored memory') with the method ('by key'), making the action unmistakable. It also implicitly distinguishes from siblings 'remember' and 'recall' by focusing on deletion.

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 (stale context, task done, clear sensitive data) and pairs with related tools ('remember' and 'recall'), providing good context. Lacks explicit when-not-to-use, but that is clearly implied.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and outputs a single text blob in standard llms.txt markdown format. This aligns with the annotations and provides useful behavioral context beyond what annotations offer.

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 highly concise: two sentences plus a bullet list of use cases. Every sentence adds value, and the primary purpose is front-loaded. No extraneous 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 and the presence of annotations and a complete schema, the description adequately explains the output format (single text blob) and input requirements. It covers the main behavioral aspects and use cases, leaving no critical gaps for an AI agent to invoke it correctly.

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

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

Schema description coverage is 100%, meaning parameters are already well-documented in the schema. The description does not add significant semantic meaning beyond what the schema provides, though it implies usage of 'url' and 'max_links' via context. 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 action ('generate a production-ready llms.txt file'), specifies the target resource (any URL), and explains the process (fetches, extracts, emits). It distinguishes itself from siblings by being unique in function; no other sibling appears to generate llms.txt files.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). While it does not explicitly mention when not to use or alternative tools, the context is clear enough for an agent to determine appropriate 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?

Beyond the annotations (readOnly, idempotent), the description adds that it returns specific fields, defaults to active subscriptions, and is scoped to the caller. 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, no wasted words. The most critical info (action, output, usage) is front-loaded. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It covers purpose, usage, behavioral traits, and parameter semantics. Pagination or limits are not needed here.

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

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

The description clarifies the default behavior (active subscriptions) and ties the parameter include_inactive to that default. While the schema describes the parameter, the description adds context by stating the default assumption, which aids correct invocation.

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 (List), resource (subscriptions), and scope (caller's active). It also lists the returned fields, making it distinct 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?

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use it relative to subscribe and unsubscribe.

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

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

Beyond the annotations (which are all false and provide no safety hints), the description discloses important behavioral details: filing returns a `claim_token` that can be used later to check status, rate-limit of 5 per identifier per day, no quota impact, and that the team reads digests daily. This gives agents a complete picture of side effects and follow-up behavior.

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

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

Though longer than average, every sentence earns its place: purpose, usage, exclusions, follow-up, rate limits, and quota are all covered without redundancy. The description is front-loaded with the core purpose and structured so that critical constraints (e.g., only for Pipeworx tools) appear early.

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?

This tool has 4 parameters, no output schema, and uninformative annotations (all false), so the description must carry full weight. It covers what the tool does, when to use it, what to include, the return behavior (claim_token), and limitations (rate limit, quota). This is comprehensive for a feedback/submission tool and leaves no major operational 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?

The schema already provides 100% coverage of all 4 parameters, so the baseline is 3. The description adds valuable extra semantics, particularly for `message` (e.g., 'don't paste the end-user's prompt') and `claim_token` (the workflow of passing it back later), which elevates it above baseline but does not fully reinvent parameter documentation.

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

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

The description opens with a direct, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly defines the tool's purpose and distinguishes it from sibling tools like ask_pipeworx, which are about asking questions rather than providing feedback.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion for tools from other MCP servers and points to the appropriate alternative ('file it with that server instead').

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. The description adds valuable behavioral context: caching intervals (5min-1h), data derivation (CF analytics-engine, no PII), and return structure (tools, packs, volume). 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 a single paragraph of four sentences, front-loading the core function. It is informative without being verbose, though it could be slightly more structured with bullet points.

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 optional parameter, read-only, no output schema), the description covers all essential aspects: return values, use cases, data source, caching, and privacy. No gaps remain.

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

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

The single parameter 'window' is fully described in the schema with an enum. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps agents choose the appropriate 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 the tool returns top tools, top packs, and total call volume over a recent window. It provides specific use cases (e.g., discovering hot data sources, confirming canonical choice), making the purpose unambiguous and distinct 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?

The description explicitly lists three scenarios for using the tool (discovering hot data sources, confirming canonical tools, aligning use cases). While it doesn't state when not to use it, the context is clear enough for an agent to decide.

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

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

Annotations declare readOnlyHint=true. Description adds extensive behavioral context: monotonicity violation detection, partition-sum checks, semantic anchor for Jaccard similarity, partition filter for placeholders, and fill check against live book depth. 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?

Information-dense but somewhat long. Well front-loaded with core purpose. Each sentence adds value, though some detail could be streamlined without losing clarity.

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

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

No output schema, but description fully explains response structure (opportunities array, partition_check details, fill check results). Covers edge cases like placeholder slugs and low similarity. Very complete for a read-only 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% with good descriptions. Description adds substantial meaning: event accepts full URLs, topic is a seed question, and explains how each mode works in depth, including internal processing details.

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 the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes: no args for trending scan, event for specific event, topic for cross-event scanning. Specific and 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?

Provides explicit guidance on when to use each mode: event recommended for specific markets, topic for cross-event scanning. Includes fill check warning and references sibling tool polymarket_fill_risk for custom sizing. Also explains when not to trade.

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 true, and destructiveHint false. The description adds substantial behavioral detail: caching at KV level for 1 hour, detailed algorithm for five model families, edge calculation with slippage and Kelly, response structure with diagnostics, Fed bet exclusion, and caveats about data reliability. 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 the core purpose and then organized into clear segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) with bullet-like formatting. While lengthy, every sentence adds value; the structure aids readability for an AI agent. Could be slightly shorter but remains effective.

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, response structure), the description is thorough: it explains input knobs, algorithm details, response top-level (including diagnostics and Fed note), and caching. No output schema exists, but the description compensates by detailing the output structure.

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 parameter descriptions. The description adds value by explaining how parameters interact (e.g., 'min_partition_leg_kelly applies to per-leg Kelly inside top_legs') and providing context like 'Polymarket has zero trading fees but bid/ask typically eats 20-50bp' for slippage_pp. 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It targets the specific use case of 'what should I bet on today' for agents, distinguishing it from sibling tools like polymarket_arbitrage or polymarket_fill_risk by emphasizing discovery and Pipeworx data.

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

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

The description provides clear usage context: 'agents discover opportunities without paging hundreds of markets' and mentions knobs like min_liquidity and max_spread_pp for filtering. However, it does not explicitly state when to use alternatives or provide exclusions, relying on implicit differentiation from sibling tools.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds significant behavioral context: explains limits (60-day snapshot TTL, start date dependency), data gaps (snapshots written on cache-miss), and decay computation methodology (daily closes, not intraday). This provides transparency beyond the annotations.

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

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

The description is lengthy but well-structured: a clear one-sentence purpose, followed by response format details, and a separate limits section. Every sentence adds value, though some details (like signed edge_pp_net) could be condensed. Front-loading the core question works well.

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

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

No output schema is provided, so the description must fully document return values. It does: explains tracked[], expired[], and snapshot_dates[] with fields like trend, decay, first_seen, lifespan_days. This is comprehensive for a complex analytical tool, covering edge cases like expired opportunities and data 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 coverage is 100%, so the baseline is 3. The description restates parameter defaults (days=14, window='1wk') and adds context (days max 30, window as 'snapshot family') but does not significantly enhance understanding 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 the tool tracks edge persistence and decay from daily snapshots, answering the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from sibling polymarket_edges (which likely provides current edges). The verb 'tracker' combined with the resource 'edge persistence and decay telemetry' is specific and 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 explains the tool's purpose and response format but does not explicitly state when to use it versus alternatives like polymarket_edges or polymarket_arbitrage. The context implies it supplements current-edge data with historical trends, but no direct guidance on when to prefer this tool is provided.

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, indicating safe read-only behavior. The description adds important behavioral context: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and warns about partial basket fills converting arbitrage into unhedged directional positions. 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?

Description is long but well-structured with clear sections for SINGLE-MARKET and BASKET modes, separated by line breaks. It uses bold headers and bullet-point-style lists for outputs. While every sentence is informative, it could be more concise; however, it avoids unnecessary repetition.

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

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

Given no output schema, the description fully enumerates return values for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs[], max_clean_notional_usd, forced_directional_risk for basket. It also covers edge cases like thin books and partial fills, providing comprehensive guidance for a complex 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 good parameter descriptions. The description adds significant meaning: explains how size_usd is interpreted differently between single-market and basket modes (max spend vs. target proceeds vs. settlement notional), clarifies side defaults for basket ('auto from partition sum'), and states the mutual exclusivity of market/event parameters. This is well beyond schema information.

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

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

Description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market, basket). It names specific outputs and correctly differentiates 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overrun not capturable, partial fills cause directional risk), providing clear context and exclusion reasoning.

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 is exceptionally transparent about behavior beyond the annotations. It discloses matching methodology (token-overlap, not shared resolution source), exclusion of unknown metric_type/match_subtype legs, all compatibility_codes and their meanings, the fee schedule omission, and the gross-vs-net caveat. This gives an agent a clear mental model of when results can be trusted.

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 labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence carries substantive information. It is long, but that length is largely justified given the tool's complexity and the absence of an output schema. A small amount of repetition — 'in EITHER mode' and the pre-mapped caveat — keeps it from a perfect score.

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

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

Given the tool's complexity, no output schema, and three optional parameters, the description covers everything an agent needs: how to invoke either mode, what the response contains, which safety fields must be read, the meanings of compatibility and temporal flags, fee limitations, and how unclassifiable legs are handled. The repeated emphasis on reading compatibility warnings even when matched_pairs>0 is a valuable safety guard.

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 already 100%, but the description adds real semantic value: it explains that `topic` auto-fetches the matching event on each venue, that the explicit tickers/slugs override the mapped side, and that both modes run the identical token-overlap matcher. It also lists the exact valid topic values, going beyond the schema's enum-free definition.

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

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

The description immediately names the exact function: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It goes well beyond the title by explaining the two modes, the 10 macro shortcuts, and the response output, leaving no ambiguity about what the tool does. This also differentiates it from sibling Polymarket tools like polymarket_edges or polymarket_arbitrage by its explicit cross-venue 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?

The description gives clear when-to-use context: use `topic` for pre-mapped shortcuts and explicit tickers/slugs for custom pairings. It also warns that pre-mapped topics often return compatibility warnings and that spreads are gross, not net tradeable edges. However, it does not explicitly name sibling alternatives or state conditions for choosing this tool over them.

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. Description adds scoping ('Scoped to your identifier') and explains the listing behavior when key omitted. Provides moderate extra context 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?

Three sentences, no fluff. Core function is in the first sentence. Every phrase earns its place (purpose, usage, scope, pairing). Exemplary conciseness.

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?

Simple tool with one optional param, good schema and annotations. The description covers all needed info: purpose, usage context, scope, dual behavior, and relationship to siblings. No gaps given the tool's 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 has 100% coverage with description for the single parameter. Description reinforces 'omit the key argument' and clarifies the dual behavior. Baseline 3 plus added clarity justifies 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?

Clearly states it retrieves a saved value or lists all keys. Explicitly differentiates from sibling 'remember' (save) and 'forget' (delete). The verb+resource combination is precise.

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 to look up context the agent stored earlier' and pairs with 'remember' and 'forget'. The description gives clear context and points to alternatives, fulfilling both when-to-use and when-not-to-use guidance implicitly.

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 reveals mark_read:true flags events as read, a mutation, contradicting the readOnlyHint:true annotation. This functional detail should be harmonized.

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

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

Four concise sentences, front-loaded with main purpose, then filtering, mutation, and alternative access. 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?

Without output schema, the description specifies return fields, filtering, mutation behavior, polling suitability, and alternative access URL, covering all necessary context for an agent.

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

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

Schema covers all 5 parameters with descriptions. The description adds marginal context (e.g., effect of mark_read on subsequent calls) but largely restates schema info.

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 pulls fired events from a subscription feed, specifies returned fields (source, citation_uri, payload), and distinguishes from siblings like recall and list_subscriptions by focusing on alerts.

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 filtering guidance (type, since), explains mark_read usage, and mentions polling suitability. Does not explicitly contrast with alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes far beyond by detailing the exact data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail note), the fallback mechanism, and the return format (changes[] grouped, total_changes count, citation URIs). This provides full behavioral transparency.

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

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

The description is detailed but front-loaded with concrete examples. Every sentence adds value (source details, fallback, parameter guidance, alternative tool). It is not overly verbose given the complexity. One could argue minor trimming, but overall 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 no output schema, the description covers return structure (changes[] grouped, total_changes, citation URIs). It explains the data sources and their behavior (GDELT preferred, GNews fallback, USPTO soft-fail). It even notes PatentsView API sunset. For a tool with three parameters and multiple sources, this is fully complete.

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

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

Schema covers 100% of parameters, but the description adds meaningful context: it explains the `since` shorthand formats (ISO date, relative like '7d', '30d', '3m', '1y'), gives a recommended default ('Use "30d" or "1m" for typical monitoring'), and clarifies that `value` accepts tickers or CIK. This adds value 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 begins with concrete example queries like 'What's new with X' and clearly states it returns a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It explicitly distinguishes from sibling tool 'entity_profile' which provides a static profile. This makes the purpose highly specific and distinguishable.

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

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

The description gives explicit usage context: it is for temporal, news-like queries about recent changes. It also includes a concrete alternative: 'Use entity_profile instead when you want the static profile'. This tells the agent exactly when to use this tool versus a sibling.

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 idempotentHint=true and destructiveHint=false. The description adds further context: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This covers scoping and retention. 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 well-structured: starts with purpose, then usage guidelines, then behavioral details. It is concise with no redundant sentences, though could be slightly tighter.

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

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

Given the simple two-parameter input, no output schema, and clear annotations, the description fully covers what the tool does, when to use it, parameter semantics, and behavioral context (scoping, persistence). It is complete for an agent to select and invoke correctly.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds meaningful examples and context (e.g., 'Memory key (e.g., "subject_property")'), reinforcing usage beyond schema basics.

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: 'Save data the agent will need to reuse later'. It specifies the verb 'save', the resource 'data' (memory), and provides concrete examples like 'resolved ticker, target address, user preference'. This differentiates it 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?

The description explicitly states when to use: 'when you discover something worth carrying forward'. It also tells when not to use alternatives by mentioning pairing with recall and forget, and distinguishes between authenticated (persistent) and anonymous (24-hour) sessions.

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, the description discloses graceful degradation (EDGAR identifiers still return if GLEIF/OpenFIGI unavailable), ambiguity behavior (asserts nothing and returns figi_candidates), and the explicit unresolved field. It also reveals internal cascading lookups, giving the agent realistic expectations about cost and behavior.

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

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

The description is long, but every section earns its place: usage examples, primary trigger, detailed type semantics, degradation behavior, and parameter semantics. It is front-loaded with the core directive and uses explicit type labels to organize dense 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 complexity and lack of an output schema, the description adequately covers return behavior: labeled identifier sources, unresolved results, figi_candidates, and exactly what resolves for each type. An agent has enough context to invoke it correctly and interpret its likely output.

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 already 100%, but the description adds substantial semantics: accepted input forms (ticker, CIK, ISIN, name), the critical instruction to pass only the issuer name and not trailing security-class words, and entity-specific examples such as ISIN-to-LEI resolution. This materially reduces misparameterization.

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

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

The description states a precise verb-object relationship: resolve a user-spoken name to canonical/official identifiers needed by other tools. It enumerates supported entity types (company, drug) and concrete outputs (CIK, ticker, LEI, FIGI, RxCUI), clearly distinguishing the tool from profile/validation-focused siblings.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' and explains it replaces 2-3 manual lookups. It does not explicitly contrast the tool with siblings such as entity_profile or compare_entities, so the when-to-use guidance is clear but lacks explicit exclusions.

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

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

Annotations already declare the tool as read-only, idempotent, and not destructive. The description adds behavioral context: it internally calls 'ai_visibility_check' for each entity, ranks results, and requires an API key for certain models. This enriches the transparency without contradicting annotations.

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

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

The description is three well-structured sentences: the first states the core action, the second explains the process, and the third gives a use case. No redundant or wordy phrases; each sentence earns its place.

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

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

Given there is no output schema, the description adequately describes the return value ('ranked list with score, confidence, signal density per entity'). All inputs are covered in the schema with additional semantic details in the description. The tool's complexity is moderate and is fully addressed.

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%, yet the description adds crucial semantic context: the first entity is treated as the 'subject', context disambiguates common names, and it explains the role of models and _apiKey. This goes beyond the schema's parameter 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 a specific verb ('compare') and resource ('AI visibility across multiple entities'), distinguishes from the sibling 'ai_visibility_check' by focusing on side-by-side comparison, and provides an example use case ('does Claude know about us as well as our competitors?') and output description.

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

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

The description explicitly states it is 'useful for competitive AI-marketing audits' and implies comparison of multiple entities, which differentiates it from single-entity tools like 'ai_visibility_check'. However, it does not explicitly list when not to use or name alternative tools beyond the implied sibling.

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 (readOnly, idempotent), description discloses graceful degradation, potential 5-30s delay for bundlephobia first measurement, and that sources_failed will list timeouts. 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?

Description is moderately long but efficiently packed with critical details. Front-loaded with main purpose, then lists return fields and caveats. Some redundancy could be trimmed but overall 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 complexity (composite tool, no output schema), description thoroughly covers return value structure, failure modes, and ecosystem scope. No gaps for an agent to understand what the tool does and returns.

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. Description adds context about version default but doesn't significantly improve understanding beyond schema. Baseline of 3 is appropriate.

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

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

Description clearly states it's a composite check for adding npm packages, specifying data sources (deps.dev, bundlephobia) and what it returns. Uniquely identifies its purpose among siblings.

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

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

Explicitly tells when to use ('is X safe / popular / small') and what not to use for (non-npm ecosystems) with alternatives mentioned. Provides perfect when-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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds significant behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K), and truncation behavior. 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 well-structured: begins with core purpose, then usage context, then pairing advice, then technical details. It is concise without being terse; 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?

Despite no output schema, the description explains what is returned (top-N passages with character offsets and similarity scores). It covers core behavior, constraints, and usage context comprehensively for a tool with 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?

Schema coverage is 100% with descriptions for all three parameters. The description adds value by providing concrete query examples, explaining the purpose of 'text' (document to search), and specifying limit range (1-20) and default (5).

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, with specific verb (search), resource (record), and concrete examples (SEC 10-K body, article). It also distinguishes from siblings by mentioning pairing with 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 states when to use: 'when the record is too big to cram into the prompt.' Provides rationale (saves context, returns relevant passages) and mentions a companion tool. Lacks explicit when-not scenarios, but the guidance is clear.

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: required account type, delivery channel behavior (feed always on, optional email/sms/webhook), webhook auto-disable after 10 failures, and return of subscription id. 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 well-structured and front-loaded with the core purpose. It includes detailed examples and constraints, but could be slightly more concise. However, 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 no output schema, the description adequately explains return value (subscription id). It covers all types, delivery channels, and constraints. However, it doesn't mention behavior for unsupported types or error handling, which would be beneficial for completeness.

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

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

Schema coverage is 100%, but the description enriches each parameter with examples and constraints per type (e.g., sec_8k: {ticker, items}, delivery: {sms, email} with phone verification). It clarifies that 'params' is type-specific and explains the format, adding 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (create) and resource (subscription), and distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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 specifies prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'. It lists supported types with examples, delivery channel options, and constraints (SMS verification, 10/day cap). However, it doesn't explicitly contrast with sibling tools like 'recent_alerts' for reading alerts.

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=false. The description adds value by disclosing that the output includes exact tool + argument shapes drawn from a live catalog, and describes the category structure. 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 comprehensive but not overly verbose. It front-loads example questions and clearly separates the argument behavior. Some redundancy in listing categories twice could be trimmed, but overall well-structured.

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

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

Given the tool's simple 1-parameter schema, no output schema, and annotations covering safety, the description fully covers purpose, usage, and behavioral detail. It is complete for its role as an onboarding and exploration 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 'topic'. The description adds context by listing the optional focus areas (finance, pharma, etc.) and clarifying that omitting the parameter gives a cross-category spread. This goes beyond the schema description.

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 returns category-bucketed example questions for what to ask Pipeworx, and distinguishes it from siblings like ask_pipeworx and entity_profile by noting it's the onboarding entry point. The verb 'suggest_questions' is clear and the resource 'what can I ask' is well-defined.

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?

Directly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to use no arguments vs a specific topic, and lists example topics for focus.

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

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

Goes beyond annotations by detailing ownership enforcement and deactivation instead of deletion. Annotations indicate write, non-destructive, idempotent; description confirms and adds context.

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

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

Two sentences, no fluff. Front-loaded with action and resource, then conditions and behavior. Highly 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 simple tool with one parameter, full schema coverage, and annotations, the description covers all necessary aspects: what it does, constraints, and side effects.

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 parameter description. Description adds no new info about the parameter beyond what schema provides, so baseline 3 is appropriate.

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

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

Clearly states 'Cancel a subscription by id.' with specific verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions by describing 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?

Explicitly says 'you can only cancel your own subscriptions' and explains the row is deactivated not deleted, guiding when to use and what to expect. Lacks explicit 'when not to use' but clear enough.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds critical behavioral detail: the SEC EDGAR fast path, the fallthrough to the grounded pipeline with verbatim evidence, and the crucial caller warning that 'could_not_verify means the check did not happen... it is NOT evidence for or against the claim.' This significantly 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?

Though long (~200 words), it is well-structured and dense: trigger phrases, core use case, claim-type routing, verdict list, caller warning, and efficiency note. Every sentence carries information, and it is front-loaded with the purpose and trigger examples. 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?

Given there is no output schema, the description fully specifies return values (verdict enums, actual value with citation, reasoning) and explains failure modes (could_not_verify vs unsupported). It also covers the distinction between financial and non-financial claims, making it complete for a complex verification 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 covers both parameters with helpful descriptions, but the description adds practical value: for tolerance_pct it explains 'set 1–2 for hallucination detection where any material error must be refuted,' and for claim it gives concrete examples. This enriches the schema and guides correct parameter usage.

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

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

The description opens with trigger phrases and states 'natural-language claim verification against authoritative sources.' It clearly differentiates from siblings like ask_pipeworx_grounded by focusing on claim verification and explicitly says it 'Replaces 4–6 sequential calls,' positioning it as the dedicated fact-checking tool.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims and all other factual claims, explaining the routing to SEC EDGAR vs the grounded pipeline. This gives clear guidance on when to invoke and what to expect, beyond generic alternatives.

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