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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond those annotations: it routes to internal tools, 'returns the structured answer with stable pipeworx:// citation URIs', works on every tier, and is a single fast call. It also indirectly discloses that ask_pipeworx_grounded is 'hallucination-resistant', implying this tool may have limitations in that area, which is useful 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 lengthy but well-structured and front-loaded: it starts with a strong preference directive, explains functionality, gives concrete examples, and provides clear alternative guidance. Every sentence contributes value, though a slightly more concise version could be trimmed without losing important content.

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

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

The description is thorough for a default entry-point tool. It covers when to use, when not to use, alternatives, example queries, return behavior (structured answers with citations), and performance characteristics (on every tier, one fast call). Given the rich annotations and complete schema, no critical information is missing.

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

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

The input schema is fully documented with 100% coverage, listing six aliases for the question parameter. The description provides example queries that illustrate how to use the parameter, but it does not add additional syntax or formatting details beyond what the schema already provides. With complete schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it routes natural-language questions to the right tool among 5,501 tools across 1,441 verified sources, fills arguments, and returns structured answers with stable citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying different use cases for each.

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

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

The description provides explicit guidance on when to use this tool versus alternatives. It instructs to prefer this over web search for factual/structured data, states 'START HERE' as the default entry point, and gives concrete examples of when to step up to ask_pipeworx_grounded or deep_research. It also addresses breaking-news scenarios, covering both inclusion and exclusion criteria comprehensively.

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 rich behavioral context beyond the annotations: it reveals the beta/nature, the live testing of candidate routing improvements, the current inactive state, and that it's a complete working router. This complements the readOnly/openWorld/idempotent hints by explaining experimental variability and comparison against stable.

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 bit long but well-front-loaded with the core message ('Beta version of ask_pipeworx'). It packs necessary details about current state, usage, and experimental nature into three sentences, with no redundant fluff. Could be tightened slightly.

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

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

The description effectively covers purpose, usage, and behavior, and clarifies it's a fully functional router. It references 'same response shape' without detailing the response structure, but since it points to the sibling ask_pipeworx, this is acceptable. Missing explicit return-value description is a minor gap.

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

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

Schema description coverage is 100% (all 6 params are alias variants of 'question' with clear descriptions). The description only states 'same arguments' without adding parameter-level details, so it does not improve on the schema. Baseline 3 is appropriate.

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

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

The description clearly states this is the 'Beta version of ask_pipeworx: identical universal router' with the same 5,501 tools and arguments. It distinguishes from the stable sibling by explaining it's the experimental edge with 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?

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' It also clarifies that no candidate is currently active, so it matches the stable router exactly, and that it's a full working router rather than a fallback.

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 non-destructive nature. The description adds rich behavioral detail beyond that: it explains the refusal mechanism with specific reasons, that it 'EXTRACTS the answer using ONLY what the tool result contains,' and mentions the extra LLM call cost. 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?

Though longer than two sentences, every clause adds crucial information: purpose, mechanism, return format, refusal reasons, use cases, and cost tradeoff. It is well-structured, front-loaded with the core purpose, and contains zero filler or redundant 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 there is no output schema, the description compensates fully by detailing the success return structure and refusal reasons. It also covers the tradeoff versus the sibling tool, making it complete for an agent to decide when to invoke and what to expect.

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

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

Schema coverage is 100% with all parameters described as aliases of 'question.' The description adds no extra parameter-level meaning beyond the schema itself, which already fully documents the aliases. Baseline is appropriate given the high schema coverage.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' with specific verb and resource. It explicitly distinguishes itself from ask_pipeworx by mentioning 'Same routing as ask_pipeworx' and the extra LLM call cost, while noting to 'prefer ask_pipeworx for casual 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' Also gives an exclusion: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff, clearly indicating 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?

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?

Beyond the annotations, the description discloses a rich set of behaviors: decomposition into facets, parallel routing to 5,501 tools, the exact findings packet structure, gaps[] for unanswered facets, hop and citation_uri semantics, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. This is far beyond what annotations alone provide.

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

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

The description is long but every sentence carries necessary operational detail — account, purpose, output, alternatives, depth mechanics, and timing. It is dense and could be better structured with bullet points, but there is little fluff; the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates thoroughly by describing the findings packet, gaps[], contradictions[], and citation_uri semantics. It covers prerequisites, use cases, latency, and depth specifics, making the tool fully specified 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?

Even though the schema covers both parameters, the description adds significant meaning: it explains the 'standard' and 'thorough' depth behaviors (gap recovery, lead chasing, contradictions), provides example questions, and notes the paid requirement for 'thorough'. This guides the agent in choosing the right depth beyond the bare enum descriptions.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' in one call, explicitly noting it is NOT open-web search. It differentiates from siblings by contrasting with ask_pipeworx for single lookups and current-news topics, making its unique purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') with concrete examples, and when-not-to-use by directing users to ask_pipeworx for single lookups or breaking news. It also states account prerequisites and the paid plan requirement for 'thorough' depth, providing clear decision rules for an agent.

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

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

Annotations 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 goes far beyond annotations (readOnly, idempotent, non-destructive) by detailing response fields (leg-by-leg prices, spread, top_spreads_pp), compatibility warnings with two cases, temporal alignment, and skipped cross-type/subtype counters. It fully discloses the tool's behavior and edge cases.

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 organized: starts with purpose, then modes, then response details, then safety fields. Every sentence contributes crucial information for correct use. Could be slightly tighter but remains well-structured for a complex tool.

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

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

Given no output schema, the description adequately explains return values (leg prices, spread, top_spreads_pp, compatibility_warning, temporal_alignment). It covers edge cases like mismatched bet shapes and temporal misalignment. However, a more precise output structure would improve 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% with descriptions for each parameter. The tool description adds value by explaining the interaction: `topic` provides pre-mapped shortcuts, and explicit tickers override the mapped side. It also lists all valid topic values and provides examples. This meaningfully enhances what the schema alone provides.

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

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

The description clearly states it computes cross-venue spread between Polymarket and Kalshi for the same resolving question. It distinguishes itself from sibling tools (e.g., polymarket_arbitrage) by focusing on inter-venue comparison, and outlines two distinct modes of operation (topic shortcuts and explicit pairings).

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 two modes with clear use cases: topic shortcuts for common macro topics and explicit tickers for custom pairings. It warns that pre-mapped topics often return compatibility warnings, implying explicit mode is more reliable. However, it does not directly compare to sibling tools like polymarket_arbitrage or specify when not to use this tool.

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

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

Annotations already declare readOnlyHint 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it mentions the cascading internal lookup endpoints, the citation URIs (pipeworx://...), and the auto-disambiguation behavior. It doesn't fully describe edge cases or error behavior, but given the annotations cover risk, this is sufficient.

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

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

The description is somewhat long but every sentence delivers critical information. It uses a conversational query pattern upfront, then a clear 'Use FIRST' directive, and a structured SUPPORTED TYPES block. It could be slightly tightened, but the density of useful info justifies its length.

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

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

Given there is no output schema, the description fully compensates by specifying return values (ticker, CIK, company_name, RxCUI, citation URIs). It also explains the internal cascading behavior and how it replaces manual lookups. For a lookup tool with two parameters, this description is remarkably 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?

The schema already describes the 'type' and 'value' parameters at 100% coverage, but the description greatly enhances this. For example, it specifies that 'company' accepts ticker, CIK, or name, and details the exact output (ticker + CIK + company_name + citation URI), and for 'drug' it lists RxCUI + ingredient + brand. It also mentions auto-disambiguation. This is far beyond what the schema provides.

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

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

The description starts with concrete usage examples ('What's the ticker for…' / 'find the CIK for…'), then states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It clearly differentiates from sibling tools by specifying it provides IDs for companies and drugs, with exact return types (ticker, CIK, RxCUI). This is a specific verb+resource with strong distinction from 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?

The description explicitly says to 'Use FIRST whenever you have a name but need an ID.' It also clarifies that each call 'replaces 2-3 manual lookups,' implying it consolidates multiple steps. Supported types are fully enumerated with input/output examples. Although it doesn't list 'when not to use,' the guidance is unambiguous and practical.

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 mark it as read-only, idempotent, and non-destructive. Description adds valuable behavioral details: two processing paths (fast structured vs. grounded pipeline), verdict types, citation format, and efficiency gains. 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 a single dense paragraph but well-organized: starts with example invocations, then usage, then behavioral details, then return format. Slightly long but each sentence adds value; could benefit from bullet points but still 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?

Despite no output schema, the description clearly states return format (verdict, actual value with citation, reasoning). Input parameters are fully explained. Tool's complexity is moderate, and the description covers all necessary information.

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. Description further clarifies tolerance_pct default behavior (implied by wording, capped at 5) and the claim parameter expectation, adding significant meaning 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?

Description clearly defines the tool as a claim verifier against authoritative sources, with specific examples of invocations. It distinguishes itself from sibling tools by focusing on factual verification with two specialized paths.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' While no direct 'when not to use' is given, the context is clear and sufficient given the tool's specificity.

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