Abs Au

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 context beyond annotations: the default model being free, the option to pass `_apiKey` to probe Anthropic with direct billing to the user, and the return structure. This helps the agent understand cost implications and external dependency, going beyond the basic safety profile.

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

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

Three sentences, each earning its place: first states the core function, second gives key configuration details (default model, API key, billing), third lists use cases. No filler, front-loaded with the action.

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 compensates by specifying the return format: 'per-model {score, confidence, signals, raw_response} + a combined view'. It also covers default model and cost implications. It doesn't explain what 'signals' contains or potential rate limits, but for a read-only probe tool this is adequate.

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

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

Schema description coverage is 100% for all 4 parameters, so the baseline is 3. The description adds the default model behavior and the fact that `_apiKey` is passed through, but it does not materially add meaning beyond what the schema already explains for each parameter.

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

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

The description clearly states the tool's action ('Probe one or more LLMs for what they know') and resource ('business/brand/product/topic'), with specific output (visibility score 0-100 per model). It is specific enough to understand what it does, but it does not explicitly distinguish from sibling tools like scan_competitor_ai_presence, so it misses the 'distinguishes from siblings' criterion.

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

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

Provides clear use-case context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not mention when not to use this tool or direct to alternatives, but the stated use cases give the agent a clear sense of when to select it.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes beyond by stating that the tool routes across 5,767 tools, auto-fills arguments, and returns structured answers with stable pipeworx:// citation URIs, plus enumerating the knowledge categories it covers. No behavioral ambiguity or 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 front-loaded with the key 'PREFER OVER WEB SEARCH' instruction, but it is somewhat repetitive: 'Use whenever' appears twice and the 'even if web search could also answer it' point echoes the opening clause. The examples and sibling routing are valuable, but the text could be tightened.

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 by explaining the return type: a structured answer with stable pipeworx:// citation URIs. It also covers when to use it, what kinds of questions fit, and which siblings to choose for narrower or broader tasks. It does not discuss failure modes or ambiguous input handling, but for a general routing tool this is reasonably 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 input schema fully documents the single required `question` parameter and its aliases, so the baseline is 3. The description adds meaning beyond the schema by giving concrete question examples and enumerating the kinds of factual lookups it handles, which helps the agent formulate valid natural-language inputs.

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

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

The description states a specific action: route a natural-language factual question to one of thousands of verified data tools and return a structured, cited answer. It also distingushes itself from web search and names sibling tools (ask_pipeworx_grounded, deep_research), so an agent can tell immediately what this tool is for.

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

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

It explicitly says 'PREFER OVER WEB SEARCH', lists when to use it, and gives concrete routing guidance: use ask_pipeworx_grounded for single-fact low-ambiguity questions, use deep_research for broad/multi-part questions, and notes that breaking-news is already handleed by pipeworx's news feeds. This is clear when-to-use and when-not-to-use guidance.

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

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

Discloses behavior beyond the readOnly and idempotent annotations: it is a beta router with candidate improvements only when under test, currently has no active candidate, and never falls back—it is a full working router. This experimental-state and merge-comparison detail is important context that annotations alone do not provide.

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

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

Four sentences, each adding value: definition, current status, usage rule, and reassurance that this is a working router. It is slightly longer than strictly necessary but stays focused and front-loads the beta-vs-stable distinction.

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 what the tool is, how it differs from its stable sibling, current behavior, and how to invoke it (same as ask_pipeworx). Return format is referenced via 'same response shape', and the schema handles input, so nothing critical is missing for correct invocation.

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

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

The schema provides 100% description coverage, documenting every parameter as an alias for 'question', so the schema already fully explains parameter semantics. The description adds no extra parameter detail beyond saying arguments match ask_pipeworx, which does not improve on 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?

Clearly explains the tool is a beta version of the stable ask_pipeworx router, detailing that it includes the same 5,767 tools, arguments, and response shape. It distinguishes itself as the experimental edge with candidate routing improvements, so an agent can tell it apart from the stable sibling.

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 it exactly like ask_pipeworx when you want the newest routing', giving a clear selection condition. It also notes that the stable router is used for comparison and that currently no candidate is active, so the beta tool matches ask_pipeworx exactly, guiding when it is safe 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 cover read-only, idempotent, non-destructive, and open-world hints. The description adds substantial behavioral context: it refuses when data doesn't answer, explains the extra LLM call cost, enumerates refusal reasons including data_truncated and tool_error, and exposes the fetched_at/evidence structure. No contradictions; it complements annotations rather than repeating them.

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

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

The first sentence states the core behavior and differentiator. Every subsequent sentence earns its place: return shape, refusal shape, high-stakes use cases, and cost tradeoff with sibling preference. It is dense but not bloated, front-loaded, and uses line breaks to separate success vs refusal vs guidance.

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

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

Given that the output schema is absent, the description fully compensates by specifying return fields ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and refusal reasons. It covers selection criteria, cost, and behavioral boundaries. An agent has everything it needs to invoke and interpret this tool.

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

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

Schema coverage is 100% and every parameter is an alias for the same 'question' concept, so the schema already documents semantics fully. The description itself doesn't describe parameter syntax, but it doesn't need to — the schema carries the entire burden here. Baseline 3 is appropriate given high 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 opens with a clear verb ('hallucination-resistant answer mode'), states the resource (Pipeworx grounded reads), and explicitly differentiates from ask_pipeworx by naming the same routing but different output mode. It also names its exact output/refusal shapes, which leaves no ambiguity about what the tool does.

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

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

It explicitly says when to use ('whenever an answer will be quoted, cited, or acted on... financial verdicts, legal claims, medical lookups, public statements') and when not to ('prefer ask_pipeworx for casual lookups'), and it names the sibling alternative. This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds extensive behavioral detail: resolver contract (market_match_confidence, alternatives), safety short-circuiting (low_confidence_match, market_closed_or_inactive), wide-spread tradeability flags, cancellation-rule parsing with ev_impact, news fallback fields, and parent-event extractor behavior. It even notes a recurring pure-rules loss from void settlements, going far beyond the annotation hints.

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

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

The description is very long, but every section earns its place by covering a distinct aspect: classifiers, fan-out examples, response shapes, resolver contract, parent events, news fallback, safety, and cancellation risk. It is well-front-loaded with the core purpose in the first sentence. While it could be condensed, the structured sections make it navigable and not redundant.

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 must explain return values and edge cases, and it does thoroughly. It details result.market, result.analysis, result.evidence, the resolver contract, parent_event, news fields, status codes, wide-spread handling, and resolution-rule risk. The tool is complex, and the description provides complete context for an agent to understand 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?

The input schema covers all three parameters (market, depth, include_raw) with descriptions and examples, giving 100% schema coverage. The description adds some context around how the market parameter is used (resolution, classification) and mentions depth indirectly via fan-out, but it does not materially improve on the schema's parameter meanings. Baseline 3 is appropriate when schema handles the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further clarifies the inputs (slug, URL, question text) and what the tool produces (evidence packet + market-vs-model comparison). This distinguishes it from siblings like polymarket_edges and deep_research by focusing on the full research workflow.

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

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

The description explicitly states when to use it: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides rich context on inputs and fan-out behavior. However, it does not mention when not to use it or alternative tools (e.g., polymarket_edges for pure edge calculation), so it lacks explicit exclusions or 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?

Adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. The annotation readOnlyHint=true is consistent with the non-mutating nature described. 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 long but every sentence adds utility, covering usage triggers, data sources, and output. It is front-loaded with examples and key emphasis. Slightly verbose but not wasteful for a multi-purpose 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 the tool's complexity (2 entity types, multiple metrics, sorting), the description covers essential aspects: input constraints, data sources, sorting behavior, and output format. It also explains why this tool exists (replacing 8-15 sequential lookups). No output schema exists, so the description's return-value note is sufficient.

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

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

Schema already covers both parameters, but the description adds practical meaning: 'type' determines data source and 'values' expectations for companies vs drugs. Examples for tickers and drug names go beyond the schema's abstract descriptions. Slight gap: description does not map every schema detail, but adds enough 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 performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides specific verbs ('compare', 'rank') and distinguishes from sequential lookups, making its purpose unambiguous.

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

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

Explicitly instructs to always prefer this over sequential single-pack lookups when comparing entities. Provides example query patterns and explains what each entity type yields. This gives clear when-to-use guidance and names the alternative approach.

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, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context about the ordered nature of dimensions and the significance of that order for constructing dataKey, which goes 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 two sentences, front-loaded with the core function, then immediately provides usage context. No filler or 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?

For a simple tool with two parameters and no output schema, the description provides sufficient context: what it returns, how it relates to get_data, and the ordering requirement. Some detail on output structure could be added, but the essential information is present.

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 both dataflowId and maxCodesPerDimension described in the schema. The description reinforces dataflowId's role but does not add significant meaning beyond the schema, so a 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: 'return its ordered dimensions and the valid codes for each' for one ABS dataflow. It also distinguishes itself from siblings by explicitly linking to get_data as a prerequisite, making its unique purpose evident.

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 when-to-use guidance: 'Call this before get_data' and explains how to use the output to build a dataKey. It does not mention alternatives or when-not-to-use, but the directive is clear and actionable.

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

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

Annotations already carry readOnly/openWorld/idempotent hints, and the description adds far more without contradicting them: account/paid-tier requirements, parallel routing to 5,767 tools, never-invented findings with explicit gaps[], contradictions[] on standard/thorough, resolveable citation_uri semantics, hop field, semantic excerpting of large records, and 15-90s latency. This is rich behavioral context well beyond the structured hints.

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

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

Long, but information-dense — the account gate and sibling routing are front-loaded before behavioral details. Every sentence carries decision-relevant content; only mild redundancy with the schema's depth description and two ask_ipeworx routing notes prevent a 5.

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

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

With no output schema, the description fully compensates by specifying the findings packet shape (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), latency expectations, caveats (news topics return empty gaps[]), and citation resolveability. An agent can decide, invoke, and interpret results without any missing context.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3; the description adds incremental value by mapping depth levels to behavioral outcomes (gap-recovery, contradictions scan, up to ~90s) and disclosing that 'thorough' requires a paid plan. The schema's own depth description is already detailed, so the added value is real but modest.

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

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

States a specific verb+resource: grounded multi-source research across Pipeworx's 1506 structured data sources in ONE call, with the explicit warning 'this is NOT open-web search'. Distinguishes itself from siblings by naming ask_ipeworx as the alternative for single lookups and news, so an agent can tell them apart immediately.

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

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

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_ipeworx', 'For BREAKING or collquial CURRENT-NEWS... prefer ask_ipeworx'), plus a hard account gate ('If you are not signed in, use ask_ipeworx instead — it works on every tier'). No usage inference is left to the agent.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds meaningful behavioral detail about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the response structure and that no follow-up is needed.

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 four sentences, each serving a purpose: purpose, use case, return behavior, and when to call. The domain list is long but informative, and there is no redundant or filler content. It's well-structured and front-loaded with the core verb.

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

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

Despite no output schema, the description fully covers the tool's purpose, input semantics, output characteristics, and usage context. It also integrates self-referential guidance ('Call this FIRST') which makes it self-contained. Annotations cover the safety profile, and the description fills in the rest.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters with clear descriptions and examples. The description's 'describing the data or task' aligns with the query parameter, and 'top-N' relates to the limit, but it doesn't add substantial new meaning beyond the schema's existing parameter documentation. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It enumerates specific domains and explains it returns relevant tool schemas, which distinguishes it from sibling tools like get_data or deep_research that would retrieve data or research rather than tool metadata.

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 when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This positions it against alternatives and tells the agent to invoke it as an initial discovery step.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: parallel fan-out across sources, soft-failure for sunset patents, expected empty FDA sections, and sources_used/sources_failed semantics. No contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose and routing guidance before enumerating return fields. Each section contributes needed details for a complex tool; it could be slightly tightened, but the density is justified.

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

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

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: cik, company_name, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, plus sources_used/sources_failed. It also covers edge cases like private companies and expected-empty sections.

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

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

Schema coverage is 100%, so baseline is 3. The description adds beyond schema by explaining zero-padded CIK format, name resolution via SEC EDGAR, and that ticker/company types are interchangeable, which helps an agent format `value` correctly.

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

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

The description opens with concrete user intents ('Tell me about X', 'research Acme') and then states the precise resource: 'full cross-source profile of a US public company in ONE parallel call.' This clearly separates it from single-purpose lookups, even without naming sibling tools directly.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is direct when-to-use guidance. It also clarifies accepted input forms and the private-company fallback, leaving little ambiguity about invocation.

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

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

Annotations already signal destructive and idempotent behavior. The description adds context about what gets destroyed (a previously stored memory) and the rationale (clearing sensitive data), which goes beyond the raw annotations. It doesn't detail edge cases like missing keys, but the idempotent hint covers that.

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

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

The description is three concise sentences, front-loaded with the purpose, followed by usage guidance and complementary tools. Every sentence earns its place with no fluff or redundancy, making it efficient and easy to parse.

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

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

For a simple one-parameter destructive tool with strong annotations, the description provides purpose, usage triggers, and related tools. The lack of an output schema is acceptable for a delete operation, and the idempotent/destructive hints cover behavioral expectations, so the description is 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 coverage is 100% with the property 'key' described as 'Memory key to delete'. The description's 'by key' merely restates the schema. No additional semantic value is added beyond what the input schema already provides, so the baseline of 3 applies.

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

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

The description explicitly states 'Delete a previously stored memory by key', which is a specific verb (delete) and resource (memory by key). It clearly distinguishes from siblings like 'remember' (store) and 'recall' (retrieve), leaving no ambiguity about the tool's function.

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 when-to-use scenarios: 'context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), giving clear guidance on placement in a workflow.

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, open-world, idempotent, and non-destructive. The description adds behavioral context by stating it 'Fetches the page, extracts... and emits...' This clarifies the network operation and output format, which goes beyond the annotations. It doesn't disclose error handling or rate limits, but the safety profile is well covered.

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 well-structured sentences followed by a bulleted list of use cases. Every sentence contributes value, with the main purpose front-loaded and no redundant information. It is concise and easily scannable.

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

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

For a tool with 2 parameters and no output schema, the description covers the essential aspects: what it does, the process, output format, and typical use cases. It does not elaborate on edge cases or failure modes, but given the simplicity and existing annotations, the information is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, with both parameters (url and max_links) already documented clearly. The description does not add additional parameter-specific meaning beyond what the schema provides, aligning with the baseline of 3 for 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 the tool's function: 'Generate a production-ready llms.txt file for any URL' and details the process (fetches page, extracts title/description/key links, emits standard markdown). This is a specific verb+resource that distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on analysis rather than file generation.

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.' This gives clear context for when to use the tool, though it doesn't explicitly exclude alternatives or name sibling tools for comparison, leaving a minor gap.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds scale warning ('can be large') and return format, but it says 'Pass "all" to fetch everything' without clarifying that maxSeries (default 100) still caps decoded series. This creates a potential misunderstanding about whether 'all' bypasses the cap. No contradiction exists, but the disclosure is incomplete.

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

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

Four sentences, each earning its place: purpose, dataKey syntax, 'all' option, return format, and prerequisite. Front-loaded with the core action and no redundant words. Very efficient for the complexity it conveys.

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

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

The tool is complex due to dataKey construction, but the description covers the essential context: prerequisite dataflow_structure, return format (decoded series, dimension labels, time-indexed values), and scale warning. With no output schema, it gives enough return information. However, it omits the interaction between 'all' and maxSeries, which is a relevant caveat even though the schema documents maxSeries, so slight deduction from a perfect score.

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 (100% coverage), so baseline is 3. The description significantly enhances dataKey semantics by explaining the SDMX dot-separated filter syntax, wildcards, '+'-joined codes, and the need to consult dataflow_structure for dimension order. This goes well beyond the schema's generic 'Dot-separated dimension filter' and is essential for 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 opens with 'Fetch observations from an ABS dataflow' – a specific verb ('fetch') plus resource ('observations') and scope ('ABS dataflow'). This clearly distinguishes it from sibling tools like dataflow_structure (which fetches dimension metadata) and list_dataflows (which lists available dataflows).

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

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

The description gives explicit usage guidance: 'Fetch dataflow_structure first to learn the dimension order and valid codes,' which directly instructs the agent to use a prerequisite sibling tool. It also explains the role of dataKey and the 'all' option, making it clear when to use this tool for retrieving observations.

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

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

Annotations already cover read-only, idempotent, and open-world hints. The description adds useful behavioral context: returns IDs and descriptive names, supports case-insensitive substring matching, and provides concrete ID examples. It does not go into pagination or edge cases, but the annotations reduce the burden.

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

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

The description is three sentences, front-loaded with the main purpose and followed by essential details. Every sentence adds value—no filler or redundancy.

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

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

For a simple list tool with no output schema, the description adequately covers the return concept (IDs + names) and how the output is used. It lacks explicit mention of pagination or limit behavior, but that is already in the schema. Given the tool's simplicity, this is sufficiently 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 coverage is 100% with well-documented parameters. The description adds only marginal value beyond the schema, such as example IDs and the notion of case-insensitive search, which the schema already states. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Browse or search') tied to a clear resource ('ABS datasets (dataflows)'). It distinguishes itself from siblings by explicitly stating that returned IDs are used with dataflow_structure and get_data, making the tool's role 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 clearly establishes when to use this tool: to discover dataflow IDs before querying with dataflow_structure or get_data. It gives context on the search filter but does not explicitly mention alternative listing tools or when not to use it, leaving a minor gap.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it returns only the caller's subscriptions and filters to active ones by default. It also discloses the exact return fields, which is valuable given no output schema.

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

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

The description is two sentences, front-loaded with the core purpose, followed by return-field details and usage guidance. Every word earns its place with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the return structure, default filtering, caller scope, and use cases. Critical information is present; nothing essential is missing.

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

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

The sole parameter include_inactive is fully documented in the schema with its meaning and default. The description adds no further parameter details, so with 100% schema coverage, the baseline score of 3 applies.

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

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

The description uses the specific verb 'List' with resource 'subscriptions', scoped to 'the caller's active subscriptions'. It also enumerates returned fields, clearly distinguishing it from sibling tools like subscribe/unsubscribe and other list 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 gives explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. This clearly frames when to use the tool, though it doesn't explicitly name alternatives or conditional exclusions.

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

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

Annotations only indicate readOnlyHint=false, etc., so the description carries the burden. It discloses rate limiting (5/identifier/day), cost/free quota, the claim_token return behavior, and the team's daily digest process. No contradictions with annotations; all behavioral traits are clearly surfaced.

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?

Every sentence earns its place: purpose, use cases, exclusions, content guidance, claim_token workflow, operational facts, and rate limits. The description is information-dense and front-loaded; 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?

Given the tool's complexity (4 params, nested object, no output schema), the description fully covers the filing and recall lifecycle, limitations, and expectations. It explains the return behavior (claim_token) and the resolution process well enough 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 coverage is 100%, so baseline is 3. The description adds meaningful beyond-schema value by explaining how to use claim_token for follow-up reads, how to structure context (pack/tool/vertical), and what type values map to real-world scenarios. It does not redefine each parameter but enriches the workflow semantics.

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?

Explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete use cases (bug, feature/data_gap, praise) and clearly distinguishes itself from sibling tools like ask_pipeworx by scoping to Pipeworx tools only. The verb+resource+scope 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?

Provides explicit when-to-use guidance for each feedback type, a clear when-not-to-use exclusion (other MCP servers), and a fallback for identifying Pipeworx tools. Even covers content guidance ('don't paste the end-user's prompt') and the claim_token recall workflow for follow-up.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses useful behavioral details: 'Cached 5min-1h depending on window', 'derived from CF analytics-engine, no PII, just (pack, tool, count)'. These add transparency about data freshness, source, and privacy. 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 three sentences, front-loaded with the core purpose and then supported by use cases and context. The use case list is slightly extended but each item earns its place by explaining practical applications. No wasted words, though it could be slightly more compact.

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

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

With no output schema, the description adequately explains what the tool returns: 'top tools, top packs, and total call volume' and 'just (pack, tool, count)'. It also covers caching behavior, making it complete for a simple single-parameter read-only tool. It doesn't need to explain return formats in more depth given the tool's simplicity.

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

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

The schema already provides 100% coverage for the 'window' parameter, including enum values and trade-off explanations. The description merely repeats the window options ('24h, 7d, or 30d') without adding new meaning, so it meets the baseline but adds no extra semantic 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's purpose: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume.' This specifies the verb (returns), resource (trending aggregates), and output (tools, packs, volume). It also distinguishes itself from sibling tools like discover_tools by focusing on real-time aggregate usage rather than tool discovery.

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 use cases: discovering hot data sources, confirming a canonical tool, and aligning with agent needs. This provides strong contextual guidance. However, it does not mention when not to use this tool or explicitly reference alternative sibling tools, so it falls short of a 5.

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

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

Even though annotations already mark the tool as read-only and idempotent, the description adds rich behavioral context beyond those tags. It discloses conditions like 'deviations >3pp emit a BUY/SELL EVERY LEG signal', 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it', and the semantic anchor threshold of 0.30 Jaccard similarity. It also specifies the partition placeholder filter behavior, giving the agent concrete decision-relevant details.

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 clause earns its place given the tool's complexity. It uses scannable labels like 'SEMANTIC ANCHOR', 'PARTITION FILTER', and 'FILL CHECK' to structure information. However, it is still a dense block of text; a few sentences could be compressed without losing meaning, so it stops short of a perfect score.

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

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

Despite lacking an output schema, the description completely specifies the return values in prose: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and 'partition_check{sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade}'. It also explains the fill-check pricing behavior and edge cases like placeholder fraction limits. For a tool with two optional parameters and three modes, this is exceptionally 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 coverage is 100% with both parameters described, so the baseline is 3. The description adds significant meaning beyond the schema by explaining what each parameter does in context: 'event' walks child markets and computes partition_check, while 'topic' flattens markets and runs the comparator on the union. It also provides concrete examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal', which enrich the schema's bare 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 opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from sibling tools like polymarket_fill_risk and polymarket_edges by naming the specific analysis techniques and modes (trending_scan, event, topic), 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?

It provides explicit mode selection guidance: 'Call with NO args for a trending_scan... pass event for... or topic for...' It also recommends 'event (recommended for a specific market)' and explains when cross-event mode is preferable ('catches ... patterns that single-event misses'). Finally, it directs users to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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 readOnlyHint/idempotentHint annotations, the description discloses caching ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, _diagnostics), and caveats like the 24h-move warning and Fed signal unreliability. It also explains why certain gates exist (placeholder-slug filter, rare longshot triggers), providing deep 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 extremely long and dense, essentially a mini-spec for the tool, which makes it less concise than ideal. While it is structured with numbered segments and clear categories, many sentences cover algorithmic details (lognormal barrier, alpha values, gate relaxations) that could be obtained elsewhere, so not every sentence earns its place in a quick-reference description.

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

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

The description thoroughly covers output structure (by_segment, fed_candidates, _diagnostics), parameter effects, edge case handling, and caching, leaving no obvious gaps. Since there is no output schema, the detailed description of response fields and diagnostics is essential and fully provided.

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 descriptions already cover 100% of parameters with defaults and examples, satisfying the baseline of 3. The description adds value by explaining how knobs interact (e.g., 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable') and the special behavior of min_partition_leg_kelly for basket trades, exceeding the baseline.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' which clearly states the tool's verb, resource, and specific scope. It also identifies a targeted use case ('what should I bet on today') distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

It explicitly states the intended use case ('Built for what should I bet on today') and explains it avoids paging hundreds of markets, giving clear context. However, it does not name alternative tools or explicitly state when NOT to use it, so it stops short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false, so the safety profile is clear. The description adds substantial behavioral detail: snapshots only written on cache-miss (so gaps mean no scan), 60-day TTL bound, decay computed from daily closes net of default slippage, and a detailed breakdown of response fields. This goes far beyond annotation hints.

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

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

The description is long but well-structured with ARGS, RESPONSE, and LIMITS sections. Every sentence adds value—purpose, args, response schema, and limitations—without fluff. It is front-loaded with the core value proposition and then details.

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

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

Given no output schema, the description fully compensates by enumerating tracked[], expired[], and snapshot_dates[] fields, including what each contains (full time-series, first_seen, trend, decay_pp_per_day, lifespan_days). It also covers history depth limits and data generation nuances, making it complete for agent decision-making.

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 both parameters have clear descriptions in the schema. The description repeats the defaults and limits (days default 14 max 30, window default '1wk') but does not add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It contrasts with sibling tools like polymarket_edges by focusing on historical persistence ('how long has this edge existed and is it shrinking?'), making the differentiation explicit.

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 strong usage context by framing the core question and explaining why it matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly state when NOT to use the tool or name alternatives, but the contrast with polymarket_edges is implied through the snapshot-based telemetry context.

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

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

Annotations already declare read-only and idempotent, and the description adds context about live CLOB depth checks, walk-the-ladder behavior, return verdicts, and the dominant loss mode (partial fill unhedged directional position). 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 a dense single paragraph with many clauses and all-caps emphasis; while every sentence adds value, it is not concise and would benefit from structured bullets or mode-split sections.

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 enumerates return fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and basket-specific fields), plus per-leg details and risk indicators, making the tool fully self-describing for invocation.

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

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

Schema coverage is 100%, so baseline 3; the description enriches parameter semantics by explaining size_usd's dual interpretation (max spend vs target proceeds vs settlement notional) and the auto default for basket side, going beyond the schema's field-level 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 opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from sibling tools by naming polymarket_arbitrage and polymarket_edges as tools to precede, establishing unique purpose.

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

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

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.' Also explains the rationale (theoretical overround not capturable, partial basket fills create unhedged directional risk).

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 label this read-only, open-world, idempotent, and non-destructive, but the description adds substantial behavioral detail beyond that: compatibility_warning and compatibility_codes can be non-empty even when matched_pairs > 0, pairing_unverified is always set, temporal_alignment null means unknown rather than aligned, and spreads are gross because Kalshi fees are not modeled. This is exactly the caveat-heavy disclosure an agent needs for comparative market data.

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

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

The description is long, but every section earns its place: modes, response shape, safety fields, code meanings, per-entry flags, skipped legs, temporal semantics, fees, and the final tradeability caveat. It front-loads the purpose and uses clear labels like TWO MODES, SAFETY FIELDS, and Codes to keep dense material navigable.

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?

Since there is no output schema, the description must explain return values and edge cases itself, and it does so thoroughly: top_spreads_pp, flags, compatibility codes, skipped counters, fees_note, temporal_alignment, and the distinction between low_confidence_pairs and matched pairs. An agent has enough information to call the tool correctly and interpret ambiguous or warning-laden results.

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

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

The schema already documents all three parameters, but the description adds crucial semantics beyond the literal schema: topic is a pre-mapped macro shortcut, the two explicit parameters override the topic-mapped side, and both modes run the identical token-overlap matcher. It also clarifies that no parameters are required and that explicit parameters enable custom pairings, which is meaningful invocation knowledge.

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 opening sentence names the exact operation and resource: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It is specific enough to distinguish this from generic research or single-venue tools and immediately conveys the core output (venue price delta) and the existence of compatibility warnings.

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

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

The description clearly explains the two invocation modes: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairings, and states the precedence of the explicit parameters. It also gives practical usage caveats like 'pre-mapped ≠ tradeable' and that most topics currently return a compatibility warning, but it does not explicitly route the agent to any sibling tool when a different kind of comparison is needed.

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 important context beyond annotations, including the scoping mechanism ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the optional key omission for listing. It does not disclose error handling or return format, but for a simple lookup tool this is sufficient.

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

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

The description is two concise sentences, front-loaded with the primary action and a clear alternative. Every phrase adds value, including the scoping detail and the pairing guidance, without any redundancy.

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

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

For a tool with one optional parameter and strong annotations, the description covers all necessary context: purpose, usage examples, behavioral scope, and how it fits with sibling tools. The absence of an output schema is not an issue here since the return values are straightforward.

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

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

Schema coverage is 100% and already describes the key parameter as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this by mentioning 'omit the key argument' and adds the context that values are 'previously saved via remember', but this is a minor addition 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's function with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys'. It also distinguishes from sibling tools like remember and forget by explicitly mentioning them and the relationship.

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

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

It provides explicit usage context: 'Use to look up context the agent stored earlier' and gives examples of what to store. It also names alternatives and pairings: 'Pair with remember to save, forget to delete,' which helps the agent choose 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?

Annotation Contradiction: The description states 'Set mark_read:true to flag returned events read' which is a state-changing operation, while the annotations declare readOnlyHint: true. This directly contradicts the read-only annotation, making the behavioral disclosure unreliable.

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

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

The description is three sentences with no wasted words. Each sentence has a distinct role: purpose, return format, filtering, mark_read semantics, and polling/alternative access. It is front-loaded and 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 no output schema, the description compensates by explaining return contents (source, citation_uri, raw payload). It covers all parameters, side effects, polling suitability, and a direct HTTP alternative. For a read-oriented tool with one mutation flag, this is exceptionally 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 coverage is 100%, but the description adds valuable context beyond the schema by explaining the mark_read side effect ('so the next call only shows newer ones'), giving a concrete type example ('sec_8k'), and clarifying the 'since' filter compares against fired_at. This goes beyond what the property descriptions provide.

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 the subscription feed and returns the most recent alerts. It distinguishes itself from siblings like list_subscriptions by focusing on alerts rather than subscription management, with specific mention of return fields (source, citation_uri, payload).

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 for when to use (to retrieve recent alerts) and offers an alternative HTTP endpoint for scripts and dashboards. It does not explicitly compare to sibling tools like list_subscriptions or recall, but the purpose is evident enough to guide selection.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive; the description goes further with concrete behavior: parallel fan-out, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail after sunset, and structured grouped output with citation URIs. This exceeds annotation coverage.

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

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

The description is dense but every clause earns its place: user intents, source fan-out, fallback logic, parameter formats, return shape, and the alternative tool. No filler or redundant restatement of the title.

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

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

For a multi-source, fallback-rich tool with no output schema, the description fully covers inputs, source behavior, output shape (changes[] grouped by source, total_changes, citations), and the alternative static-profile path. There are no critical gaps.

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

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

Schema description coverage is 100% and already includes examples for `since` (ISO or relative) and `value` (ticker or CIK). The description repeats the `since` formats but adds no new parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool provides a change feed for a company over a time window, naming specific source types (SEC EDGAR, GDELT/GNews, USPTO). It differentiates itself from the sibling entity_profile by explicitly telling when to use that instead.

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

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

It gives example user queries, provides typical values for the `since` parameter, and explicitly contrasts with entity_profile ('Use entity_profile instead when you want the static profile'). This is strong when-to-use and alternative 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?

Adds useful nuance beyond annotations: memory is 'scoped by your identifier,' authenticated users get persistent memory, and anonymous sessions retain for only 24 hours. This informs lifetime and visibility expectations. No contradiction with annotations (readOnly=false, idempotent=true) is present.

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

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

Three sentences, front-loaded with the primary purpose, followed by use cases and storage details. Every sentence contributes something important; no filler.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, persistence behavior, and sibling relationships. It is fully self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3, but the description reinforces key semantics by giving example keys and values and noting the key-value pair is 'scoped by your identifier,' which clarifies key uniqueness. This adds value beyond the bare 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 opens with a specific action and resource: 'Save data the agent will need to reuse later' plus scope ('across this conversation or across sessions'). It clearly distinguishes from siblings by naming recall and forget as complements, so the agent knows exactly what this tool does relative to others.

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 when you discover something worth carrying forward...' and provides concrete examples (ticker, address, preference). It also says 'Pair with recall to retrieve later, forget to delete,' giving clear routing to alternative tools.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavioral detail beyond that: internal cascading lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting, `figi_candidates` when matches are ambiguous, and source-labelled identifiers. This is rich 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 dense and front-loaded with purpose and usage guidance, and nearly every sentence adds information. However, the company-type section is one long unbroken parenthetical paragraph that could be better organized with bullets or separate paragraphs, slightly reducing readability.

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: it explains return expectations (canonical identifiers, `unresolved`, `figi_candidates`), source provenance, supported entity types, and degradation behavior. For a tool this complex, nothing essential for correct invocation is missing.

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

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

Although schema coverage is 100%, the description goes far beyond the schema by giving concrete query examples, explaining accepted input formats for each entity type, and warning against including trailing security-class words in bond issuer names. This materially improves an agent's chance of passing correct parameter values.

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

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

The description opens with concrete user phrasings and states a specific verb: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes the tool's resource (entity identifiers) and lists supported types, making its purpose unmistakable even among many 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?

It explicitly says to use this tool 'FIRST whenever you have a name but need an ID,' and gives rich context about when each case applies. However, it does not explicitly name alternatives or state when NOT to use it, so it lacks the full when/when-not structure of the highest tier.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context by stating it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density—details not present in annotations. 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?

Four concise sentences, each serving a distinct purpose: main function, method of operation, use case, and return value. No fluff or redundancy; the key purpose is front-loaded.

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

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

For a tool without an output schema, it adequately describes the return format (ranked list with score, confidence, signal density) and internal behavior (use of ai_visibility_check). It also provides a clear usage scenario, making it sufficiently complete for an agent to select and invoke properly.

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

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

Schema description coverage is 100% and all parameters have meaningful descriptions (e.g., entities as subject vs competitors). The description does not add significant parameter-level meaning beyond the schema, only reiterating the multi-entity concept. Baseline of 3 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 the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes itself from sibling ai_visibility_check by emphasizing multi-entity comparison and ranking, and provides a concrete use case ('competitive AI-marketing audits').

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

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

The description gives a clear context for when to use it ('competitive AI-marketing audits') and provides an example query, implying it is for comparing your brand against competitors. However, it does not explicitly state when not to use it or mention alternative tools (e.g., compare_entities), so it lacks exclusion guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses multi-source fan-out behavior, graceful degradation on partial failures ("sources_failed will list it if it times out, the rest still returns"), and a notable latency caveat ("bundlephobia's first measurement on a new version can take 5-30s"). This significantly enriches the annotation data without contradiction.

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

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

The description is dense but every sentence earns its place: purpose, usage, return value, ecosystem limits, and failure behavior. It is front-loaded with the core purpose, uses compact lists and parentheticals, and avoids filler. Appropriate length for a composite 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?

Despite lacking an output schema, the description thoroughly explains the return structure (summary block fields, per-advisory detail, links, alternatives) and behavioral edge cases (NPM-only, timeout handling). For a multi-source composite tool with partial failures and latency, this is a complete and actionable description.

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

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

Schema description coverage is 100%, with both 'package' and 'version' already well-documented in the schema. The description adds minor context (e.g., scoped packages accepted, version defaults to latest) but does not materially enhance parameter meaning beyond what the schema states. Baseline 3 is appropriate as the schema carries the load.

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

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

The description opens with a specific, composite purpose: "Composite 'should I add this npm package to my project' check in ONE call" and lists concrete data sources (deps.dev, bundlephobia) and checks (license, advisories, bundle size, etc.). It clearly distinguishes from siblings by emphasizing the compound nature and NPM scope, avoiding ambiguity with tools like 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?

Explicit usage triggers are given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also provides exclusions and alternatives: "NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly", directing agents to the correct tool for non-NPM packages.

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

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

Annotations cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds critical behavior: 200K char cap with truncation flag, 500-char overlapping windows, BGE-base-en embeddings with cosine similarity, and output including character offsets and similarity scores. This is substantial disclosure 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?

Well-structured and front-loaded: purpose, usage, technical details. Every sentence adds information (offsets for verification, cap, model, pairing with another tool) without redundancy. Length is justified by the density of useful detail.

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

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

No output schema exists, but the description specifies return format (top-N passages, offsets, similarity scores) and limitations (truncation). It also provides a cross-tool workflow with ask_pipeworx_grounded. This makes the tool fully comprehensible and safely invocable.

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 parameters at 100%, so baseline is 3. The description adds value by clarifying 'text' is already-fetched content with examples, enriching 'query' with natural-language examples, and noting the truncation behavior for 'text'. However, 'limit' semantics are fully in the schema, so this is solid but not exceptional.

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 'Semantic search INSIDE a fetched record' – a specific verb and resource. It distinguishes from siblings by focusing on already-pulled text and returning passages with offsets, clarifying it is not a whole-document search like ask_pipeworx.

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

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

It states 'Use when the record is too big to cram into the prompt' and gives a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is explicit when-to-use and how it complements other 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?

With annotations present (write operation, open world, idempotent), the description adds valuable context: auth requirement, no persistence for anonymous/BYO, delivery channel details, phone verification, 10/day SMS cap, and webhook auto-disable on failures. This goes well beyond what annotations alone convey.

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

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

The description is dense but well-organized, with every sentence earning its place. It is front-loaded with purpose and uses specific examples without unnecessary fluff.

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

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

Despite the complexity (nested params, enum types, multiple delivery channels, no output schema), the description covers prerequisites, return value, supported types, delivery options, and operational limitations, making it fully self-contained 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 coverage is 100% and descriptions are already rich. The tool description adds a few extra specifics (e.g., 'items:["5.02"] = officer change', phone verification URL, feed retrieval endpoint), providing marginal value over the schema.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'), names the return value, and distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_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?

The description provides strong contextual guidance: it explains the prerequisite (OAuth account), differentiates subscription types, and mentions the always-on feed as a pull alternative. However, it doesn't explicitly say 'use this when you want X, use list_subscriptions to view' or mention explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds meaningful behavioral context: returns category-bucketed example questions, includes tool+argument shape, and draws from live catalog. 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 dense paragraph, but every sentence delivers value. It is somewhat long but front-loaded with example queries and structured information about output.

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 explains what the tool returns, when to use it, and optional parameters. No output schema exists, but the description adequately covers return value structure in prose.

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 'topic' parameter is described in both schema and description with examples ('finance', 'pharma'), adding practical usage meaning beyond the bare 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's purpose with specific verbs ('onboarding entry point') and resource ('Pipeworx' capabilities), and distinguishes it from siblings by positioning it as the FIRST tool to use when unfamiliar, while mentioning meta-tools like ask_pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you') and describes optional topic filtering. While it doesn't explicitly contrast with discover_tools, the use case is well contextualized.

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 destructiveHint=false and idempotentHint=true, but the description adds meaningful behavioral detail: it is a soft-delete ('deactivated, not deleted') and enforces ownership. This goes beyond the annotations and gives the agent a clear mental model of what happens on invocation.

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

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

Three short sentences, each with a purpose: the action, the ownership rule, and the side effect. No fluff or repetition. The structure is front-loaded with the primary action first.

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

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

For a simple one-parameter operation with no output schema, the description is adequate. It covers the what, the constraint, and the persistence behavior. It doesn't mention the return value, but that's not critical for a cancel operation and the annotation set is strong. It also ties to recent_alerts for historical events, which completes the context.

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

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

The schema already documents 'id' as a subscription uuid returned by subscribe, which is high coverage. The description adds semantic constraint that the id must belong to the current user, which is not in the schema. This helps the agent understand a critical validation rule.

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

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

The description clearly states the action verb 'Cancel' and the resource 'subscription by id', which immediately distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'. It also adds scope ('Ownership is enforced') which clarifies the exact operation.

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

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

Provides clear context about when to use this tool (to cancel a subscription by id), including an important constraint (only own subscriptions) and a side-effect clue (deactivation not deletion). It doesn't explicitly name alternatives, but the implicit reference to 'recent_alerts' and the contrast with 'subscribe' makes the usage context 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behavioral nuances: that 'could_not_verify' means the check never happened and must not be treated as evidence, while 'unsupported' means no source covers it. It also reveals internal mechanics (SEC EDGAR fast path vs. grounded fallback) and explicitly warns callers about error handling.

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

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

The description is dense but every sentence serves a purpose: usage triggers, routing logic, return values, error semantics, and efficiency gains. It is front-loaded with user-phrase examples and maintains a clear structure despite 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?

With no output schema, the description fully explains what the tool returns: verdict categories, actual value with citation, and reasoning. It also covers edge cases (could_not_verify vs. unsupported) and integration notes (replaces multiple sequential calls), making it complete for an AI agent to invoke and interpret results reliably.

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 valuable context: it provides concrete example claims, explains how tolerance_pct overrides implied wording, and suggests values (1–2) for hallucination detection. This goes beyond the raw schema descriptions, though the schema itself is already quite clear.

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

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

The description uses a specific verb+resource: 'natural-language claim verification against authoritative sources.' It clearly distinguishes itself by listing natural-language triggers and stating it replaces 4-6 sequential calls, making its purpose unmistakable even among many 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates two routing paths (company-financial vs. any other factual claim), giving clear guidance on when this tool applies versus needing a fallback pipeline.

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