Data Boston

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

Annotations already declare readOnlyHint and idempotentHint. Description adds details about default model and BYO key for Anthropic, which is useful but not critical 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?

Single paragraph, front-loads main action, then defaults, return, and use cases. Every sentence adds value 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?

With no output schema, description explains return format. Covers all parameters, usage scenarios, and prerequisites. Sufficient for a probing tool.

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

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

Schema covers all 4 parameters. Description adds context: default model, BYO key pass-through, and return structure (per-model {score, confidence, signals, raw_response}), enhancing parameter understanding.

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

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

Clearly states the action (probe LLMs), resource (business/brand/product/topic), and output (score 0-100 per model). Distinguishes from sibling tools like scan_competitor_ai_presence by focusing on per-model scoring.

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 use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains default vs. BYO model. Lacks explicit 'when not to use' or alternative tool references, but context is clear.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: it routes to one of 5,798 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It also discloses a limitation around cutting-edge science/medicine news by routing to news rather than guaranteeing the latest.

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: primary use, supported domains, routing mechanism, trigger phrases, examples, and escalation paths. It is front-loaded with the key directive "PREFER OVER WEB SEARCH." It loses one point because some phrasing is redundant (e.g., "Use whenever...", "START HERE", and the default-entry-point note overlap in purpose).

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

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

For a high-complexity router with no output schema, the description is remarkably complete: it explains the input contract, the routing behavior, the return shape with citation URIs, the scope of supported data, and the main alternatives. Combined with rich annotations and a fully documented schema, nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, and the schema itself fully documents the question parameter and all aliases. The description adds examples and trigger phrases, but it does not add parameter-level meaning beyond what the schema already provides. A baseline of 3 is appropriate because the schema carries the parameter-documentation burden.

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 is explicit and specific: it is a router that answers factual and data-oriented questions from authoritative sources, listing concrete domains like SEC filings, FDA data, economic statistics, patents, clinical trials, and news. It clearly distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell them apart even without inspecting those 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 precise when-to-use guidance: prefer over web search, use for factual/real-world questions, and use even when web search could answer. It also names alternatives for clear exclusion cases: search_within/remember for private data, ask_pipeworx_grounded for a single verifiable quoted answer, and deep_research for broad multi-part or cutting-edge questions.

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 behavior. The description adds valuable behavioral context beyond annotations: it is an experimental edge with candidate routing improvements enabled live, and currently no candidate is active so it matches ask_pipeworx exactly. This transparency about mutable routing behavior is useful and does not contradict 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 well-structured and mostly efficient: it establishes the beta relationship, current exact-match state, intended usage, and experimental purpose in a few sentences. The specific date and count of tools add some detail, but the description remains concise and front-loaded with the most important 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?

For a router tool with no output schema, the description covers the key practical points: what it does, how it differs from the stable version, current behavioral state, and how it should be used. The response shape is referenced as identical to ask_pipeworx but not detailed; still, the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, and the schema documents the question parameter along with all aliases. The description adds no detailed parameter semantics beyond stating that arguments are identical to ask_pipeworx, which is acceptable given the schema's completeness. 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 as a beta version of ask_pipeworx, explicitly stating it is an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable sibling by emphasizing the experimental routing edge and current exact-match behavior with 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?

The description gives explicit usage context: use it exactly like ask_pipeworx when the newest routing is desired. It also clarifies that results are compared against the stable router to inform merges. It does not explicitly enumerate when to avoid the beta or prefer a different sibling, but the experimental positioning makes the intended use reasonably 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 the annotations (readOnly, openWorld, idempotent), the description discloses rich behavioral detail: the exact success return shape, the refusal contract with five enumerated refusal reasons, the 'uses ONLY what the tool result contains' extraction rule, and the extra LLM call cost. No contradiction with annotations; it significantly augments them.

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

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

The description is long but every sentence earns its place: purpose, routing mechanism, return contract, refusal modes, use-cases, and cost trade-off are all functional. It could arguably be trimmed, but for a tool with this much behavioral nuance 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 fully documents the return shape and refusal contract. Given the tool's complexity (routing over 5,798 tools), the description covers purpose, mechanism, behavior, cost, and alternatives completely. 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?

Schema coverage is 100%, so the schema already documents the question parameter and all six aliases. The description adds modest context about appropriate question domains but doesn't need to compensate for a schema gap. 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 opens with a specific, scoped verb phrase — 'Hallucination-resistant answer mode for high-stakes reads' — then explains the mechanism (routes across 5,798 tools and extracts only from tool results) and names the sibling it derives from. It unambiguously distinguishes ask_pipeworx_grounded from ask_pipeworx and ask_pipeworx_beta.

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 when-to-use: 'whenever an answer will be quoted, cited, or acted on... must not invent facts' with concrete domains (financial, legal, medical, public statements). Explicit when-not-to-use: 'prefer ask_pipeworx for casual lookups' including the cost rationale (one extra LLM call). This is textbook-excellent usage guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, etc. Description adds extensive behavioral detail: low-confidence matches short-circuit with 'low_confidence_match' status, closed markets return 'market_closed_or_inactive', wide-spread markets carry 'illiquid_wide_spread' note, and cancellation rules are parsed. It also explains news fallback mechanisms and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long and packed with detail. While every section is justified (classifiers, fan-outs, response shapes, edge cases), it could be more concise. However, it is well-structured with clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable despite 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?

No output schema is provided, but the description extensively documents the return shape (result.market with bid/ask/spread, result.analysis with model probability, result.evidence keyed by source, parent_event extractor, news fields). It covers edge cases (low confidence, closed markets, wide spreads, cancellation rules, fallback mechanisms). For a complex tool, this is remarkably complete.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description goes beyond by explaining the 'market' parameter can be a slug, URL, or question text; the 'depth' enum options ('quick' vs 'thorough') with default; and 'include_raw' default false with guidance on when to use true. This adds significant value 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 starts with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists exact input types (slug, URL, question text) and explains the process (resolves, classifies, fans out). It distinguishes from sibling tools like polymarket_arbitrage by focusing on data gathering rather than arbitrage.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also details classifiers (crypto_price, fed_rate, etc.) and fan-out examples for different bet types, giving clear context. It explains blocking conditions (low-confidence, closed markets, wide spreads) that act as implicit when-not-to-use.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). Description adds that it returns dataset titles and resource ids, and links to boston_query, providing behavioral context beyond annotations.

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

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

Two concise sentences that front-load the purpose and provide essential details without waste.

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

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

Returns no output schema, but description explains return format (title and resource ids) and relationship to boston_query. Could mention pagination or resource id format, but adequately complete for a search 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 already provides 100% coverage with descriptions for both parameters. Description reiterates them and adds context (e.g., 'use with boston_query'), but does not add significant new semantic detail.

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

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

Clearly states it searches the City of Boston open-data catalogue by keyword, returns dataset titles and resource ids, and distinguishes from sibling tools like boston_query and boston_recent.

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 when to use (keyword search) and mentions boston_query for querying datastores, but lacks explicit when-not-to-use or alternative conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe query behavior. Description adds feature details (free-text, filters, sort, pagination) but no behavioral surprises or contradictions.

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

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

Two concise sentences with no fluff. Every sentence earns its place: first states core function, second lists supported features and guides to sibling tools.

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

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

Covers purpose, key features, and usage guidance. With schema providing full parameter details and annotations covering safety, description is complete enough. Lacks mention of rate limits or empty result behavior but acceptable given context signals.

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

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

Input schema has 100% coverage with descriptions for each parameter. Description summarizes the key parameters but does not add meaning beyond what schema provides, meeting 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?

Description clearly states verb 'Query' and resource 'City of Boston datastore resource by resource id (UUID)'. It distinguishes from sibling tools by referencing boston_datasets and boston_recent for finding resource ids.

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

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

Explicitly advises using boston_datasets to find a resource id and boston_recent for common ones, providing clear alternative usage. Does not explicitly state when not to use, but context is sufficient.

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, destructiveHint=false, idempotentHint=true. Description adds behavioral detail: returns latest rows newest-first, and provides free-text filtering. No contradiction with annotations.

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

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

Three sentences: first states purpose, second gives usage guidance, third explains parameters. Front-loaded with the main idea, no fluff.

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

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

Covers data source, behavior (newest-first), parameter usage, when to prefer, and sibling comparison. No output schema, but description hints at return format (rows). Lacks mention of pagination or rate limits, but sufficient for a simple retrieval tool.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds value by explaining that dataset names are friendly aliases (no CKAN resource ID needed) and that q is a free-text keyword filter, reinforcing schema details.

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

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

Clearly states the tool returns recent records from a City of Boston open dataset by friendly name, without needing CKAN resource IDs. It specifies that it returns the latest rows newest-first and distinguishes itself from boston_query (full control) and web search.

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

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

Explicitly advises to prefer this tool over web search for certain queries (e.g., 'recent crime in Boston') and directs users to boston_query for full control. Provides concrete examples of when to use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds value by detailing data sources: company pulls 10-K revenue/net income/cash/debt with correct fiscal year handling, drug pulls FAERS adverse-event counts and trial counts. No contradiction with annotations.

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

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

Description is relatively long but efficiently packed with examples, usage guidance, and behavioral details. Every sentence adds value. Could be slightly more structured but remains highly informative without redundancy.

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

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

Despite no output schema, description explains return structure: paired data + pipeworx:// citation URIs per entity, sorted by primary metric. Covers both company and drug types completely. Everything an agent needs to use the tool effectively 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% and parameters are defined. Description enriches by specifying that 'values' should be tickers/CIKs for companies and drug names for drugs, and that 'type' determines the data pulled. The enum is already clear in schema.

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

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

Description clearly states it compares 2-5 companies or drugs side-by-side, with example queries like 'compare X and Y' and 'rank these companies'. It distinguishes from sequential single-pack lookups by noting it replaces 8-15 sequential calls.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides clear context (comparing entities) and alternatives (sequential lookups). Also specifies it handles off-calendar fiscal years and primary metric sorting.

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 are read-only/idempotent/open-world, and the description goes well beyond them: it discloses the auth/paid requirement, 15-90s latency, gap[] behavior, contradictions[], fetchable citation_uri guarantee, and semantic excerpting of large records. This gives the agent a rich behavioral model without contradicting any annotation.

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 long, but each sentence carries unique information: auth, alternative, core mechanism, output packet, depth semantics, latency, citation guarantees. It is front-loaded with the most critical routing and auth info. A minor deduction for the wall-of-text formatting and slight redundancy in elaboration, but it remains appropriately sized for a complex tool.

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

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

With no output schema, the description takes on the burden of explaining return values—and it does: findings packet with verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop field, citation_uri. It also covers auth, latency, alternative routing, and depth behavior. An agent has everything needed to invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by tying the depth parameter to paid tier and latency expectations, and clarifying that the question parameter accepts broad/multi-part natural language. It doesn't repeat schema internals but adds operational context.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, and clearly distinguishes itself from open-web search and sibling ask_pipeworx. It also explains the decomposition and parallel routing behavior, leaving no doubt about what the tool uniquely 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?

Explicitly says 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx instead', plus an auth-based routing rule: if not signed in, use ask_pipeworx. It also explains when to pick depth levels, giving 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?

Annotations already indicate readOnly and idempotent. The description adds value by explaining that results include names, descriptions, and full input schemas with curated examples, and are ready to call directly.

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

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

Description is front-loaded with purpose, uses concise bullet-like lists for domains, and explains return value efficiently. Every sentence adds value without redundancy.

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

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

All essential aspects are covered: purpose, usage, return format, and integration with sibling tools. No output schema is needed because description explains what is returned.

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

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

Schema coverage is 100%, and the description provides additional context about the query parameter ('Natural language description...') and lists aliases. However, this is baseline since schema already covers all parameters.

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 'Find tools by describing the data or task' and lists numerous specific domains (SEC filings, financials, FDA drugs, etc.). It distinguishes this meta-tool from siblings by specifying it returns tool definitions for direct invocation.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds far more: parallel fan-out across sources, USPTO soft-failure timeline, sources_used/sources_failed semantics, expected-empty FDA sections, and private-company resolution behavior.

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

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

Long and single-paragraph, but densely packed and front-loaded with examples, the core purpose, and the usage preference before details. Some redundancy with the schema's parameter descriptions prevents 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?

For a complex tool with no output schema, the description covers all important behavior: source list, return field shape, failure modes, expected empty results, fallback chains, and accepted input variants. Agents can predict normal and edge-case behavior accurately.

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 documents both parameters well (100% coverage). The description adds value by explaining name resolution via SEC EDGAR, interchangeable type behavior, and resolved_from/resolved_to fields, going meaningfully beyond schema text.

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 pair: produces a 'full cross-source profile' of a US public company in one call. Lists exact sources and return sections, and contrasts itself with single-pack SEC/XBRL/news lookups, making its scope 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?

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies private-company requests return resolved:false rather than failing. It does not explicitly distinguish from close siblings like deep_research or compare_entities.

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 destructiveHint=true and readOnlyHint=false, so the description adds little beyond 'clear sensitive data' context. No contradictions, but the description does not disclose additional behavioral traits (e.g., idempotency nuance).

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

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

Two short sentences, front-loaded with the primary action. No wasted words; every sentence serves a purpose.

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

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

For a simple delete tool with one required parameter, strong annotations, and no output schema needed (deletion typically returns no structured result), the description fully covers the tool's functionality and usage 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% with a single parameter 'key' described as 'Memory key to delete'. The description adds an example ('user_research_topic'), but does not provide further semantic meaning beyond the schema.

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

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

The description explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by naming them, clarifying its unique role.

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

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

The description gives explicit when-to-use scenarios: 'stale context', 'task done', 'clear sensitive data'. It mentions pairing with remember and recall, but lacks explicit when-not-to-use or alternative instructions.

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 (readOnlyHint, idempotentHint, openWorldHint, non-destructive) already indicate safety; description adds context on fetching, extracting data, and output format. 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?

Three focused sentences with clear action, purpose, and output. Could be slightly more concise but no redundant information.

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

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

For a simple tool with 2 params and comprehensive annotations, the description covers the output format sufficiently. No missing details that would hinder agent understanding.

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

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

Schema covers both parameters (url, max_links) with descriptions. Description doesn't add meaning beyond schema; does not mention max_links or explain its effect.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, with specific verb and resource. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on 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?

Provides concrete use cases (getting client site indexed, drafting own project, auditing competitor) but doesn't explicitly state when not to use or name alternatives.

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

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

Annotations already provide readOnly and idempotent hints. Description adds that it returns specific fields and mentions 'active' vs 'include_inactive' behavior, enriching context 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?

Two sentences, no wasted words. First sentence states purpose and output, second provides practical usage 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?

For a simple list tool with one optional parameter, description covers purpose, usage context, and return fields. No output schema but fields are listed.

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

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

Schema has 100% coverage with clear description of include_inactive. Description reinforces 'active' default but adds limited meaning beyond schema.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Lists returned fields, distinguishing it from siblings like subscribe/unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' No exclusion but clear 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 only provide false hints, so the description carries the burden of explaining behavior. It discloses that filing returns a claim_token, that the token can be used later to check resolution status, that feedback is rate-limited to 5 per identifier per day, that it's free, and that the team reads digests daily. These are meaningful behavioral details not present in 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?

Although the description is long, it is dense with actionable information and every clause adds value: usage criteria, scope boundaries, token workflow, rate limit, and roadmap impact. The first sentence immediately states the core purpose, and the subsequent details are logically ordered. It is appropriately sized for a tool with this degree of operational nuance.

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

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

The tool has no required parameters, no output schema, and complex usage semantics. The description covers all essential aspects: what kinds of feedback to submit, how to scope it to the correct server, how to use claim_token for follow-up, and operational constraints like rate limiting. There are no obvious gaps that would prevent an agent from using the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds significant semantic value beyond the schema. It clarifies the meaning of claim_token ('Read the reply to a report you filed earlier'), provides guidance on message content ('don't paste the end-user's prompt'), and explains the context fields in terms of Pipeworx tools/packs. This elevates the parameter understanding beyond simple field definitions.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the tool's purpose and is easily distinguished from sibling tools like ask_pipeworx or discover_tools, which are about querying or discovery rather than submitting feedback.

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

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

The description gives explicit when-to-use scenarios: bug, feature/data_gap, praise, and also includes a clear exclusion—'ONLY for tools served by this Pipeworx connection'—and redirects to alternate support for other MCP servers. It also explains the optional claim_token workflow and rate limits, going well beyond simple usage 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 context beyond annotations: data source (CF analytics-engine), no PII, caching details (5min-1h). This explains behavior and limitations clearly.

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?

Efficient: three bolded sentences plus bullet points for use cases. No redundancy, well-organized, and front-loaded with the key 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?

Given low complexity (1 optional parameter, no output schema), description covers return values (tools, packs, call volume), use cases, caching, and data origin. Fully adequate.

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

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

Schema coverage is 100% with enum descriptions, but description adds semantic guidance: shorter windows surface hot trends, longer show steady-state demand, which improves parameter understanding.

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

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

Clearly states it returns top tools, top packs, and total call volume over a recent window. Distinct from siblings like discover_tools and ask_pipeworx by focusing on trending data.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case). Also provides guidance on window selection: shorter for hot trends, longer for steady-state.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. However, the description adds rich behavioral context: semantic anchor (Jaccard similarity >0.30), partition filter (drops placeholder slugs, null signal if >20% placeholder), fill check against CLOB depth, and details on response fields. No contradictions with annotations.

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

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

The description is long but well-structured: first sentence summarizes purpose, then detailed paragraphs for each mode, warnings, and response format. Every sentence adds value, but some details could be more concise. Still, it's front-loaded with the main purpose.

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

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

Despite no output schema, the description fully explains the response structure (opportunities[], partition_check fields, fill_check fields). It covers all edge cases (placeholder filtering, similarity threshold, fill risk) and suggests an alternative tool for custom sizing. Complete for a complex arbitrage detection 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% (both parameters have descriptions). The description goes beyond schema by explaining the mode difference, providing example inputs ('fed-decision-may-2026', 'Fed rate decision'), and noting that full Polymarket URLs are accepted for the event 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 function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (trending_scan, event, topic) with specific examples, and the purpose is distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also warns against trading when fill check shows non-realizable edge and recommends an alternative tool: '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?

Discloses caching at KV level keyed on all knobs, detailed response structure with diagnostics, and the tradeable-edge knobs. Annotations already indicate readOnly, openWorld, idempotent; description adds significant behavioral context beyond that, such as cache behavior and output segments.

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

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

The description is very long and detailed, containing extensive technical specifications about model families and response segments. While well-organized with bolded terms, it is verbose and could be more concise for a quick overview.

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 covers purpose, usage, behavioral details, parameter semantics, and response structure comprehensively. Despite no output schema, it explains the response top-level and diagnostics, making the tool fully understandable. No gaps given the complexity.

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

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

Each parameter's description in the schema is good, but the tool description adds even more context, explaining how knobs like min_liquidity and max_spread_pp serve as filters, and how min_partition_leg_kelly works with partition arbs. The description significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using specific verb 'scan' and resource 'Polymarket markets'. It distinguishes from siblings by focusing on edge detection with detailed model families.

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 'Built for "what should I bet on today"' and mentions agents discover opportunities without paging. Provides usage context with knobs like min_liquidity and max_spread_pp. Does not explicitly state when not to use or alternatives, but sibling list provides context.

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

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

The description goes well beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by detailing the return structure (tracked, expired, snapshot_dates), how decay is computed, and limitations like the 60-day snapshot TTL. 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 thorough but somewhat dense, interweaving purpose, parameter details, return format, and limitations. It front-loads the core question but could benefit from clearer sectioning. Every sentence adds value, making it informative yet not overly verbose.

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

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

Given the tool's complexity (no output schema, two parameters) the description comprehensively covers the return data (tracked, expired, snapshot_dates with details like trend, decay), usage context, and limitations. It is fully self-contained for an AI agent to understand what the tool does and how to interpret results.

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

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

The input schema already describes both parameters (days and window) with full coverage. The description adds value by specifying defaults (14 days, 1wk), clamping ranges (clamp 2-30), and explaining the meaning of 'window' as snapshot family, which aids understanding beyond the schema.

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

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

The description clearly identifies the tool as providing edge persistence and decay telemetry, answering a specific question about how long an edge has existed and whether it's shrinking. It distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on temporal analysis.

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 context on when to use the tool (e.g., distinguishing between fresh and old wide edges) and includes parameter defaults and ranges. However, it does not explicitly state when not to use it or suggest alternatives among the many sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description expands with specifics: walks the ladder, returns verdicts (clean|degraded|cannot_fill), per-leg fill detail, thin_legs, and forced_directional_risk. No contradiction.

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

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

Description is dense but well-structured with clear sectioning (SINGLE-MARKET, BASKET) and capitalization for key terms. Every sentence adds value with no fluff.

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

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

No output schema exists, but description thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, capture_ratio, per-leg fill detail, etc. for basket). Also covers risks and edge cases.

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

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

Schema coverage is 100% with descriptions. Description adds significant meaning beyond schema: explains size_usd for single-market as 'max spend on buys, target proceeds on sells' and for basket as 'settlement notional — shares per leg', and side default logic. Fully compensates.

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

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

Description clearly states 'realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two modes (single-market and basket) with distinct behaviors. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about partial basket fills converting an arb into an unhedged directional position. Provides actionable 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?

Annotations already indicate readOnly/openWorld/idempotent behavior, and the description adds substantial context beyond that: gross spreads without Kalshi fee modeling, compatibility_codes semantics, unknown legs never paired, skipped cross-type/subtype counters, and the meaning of null temporal_alignment. This is far more behavioral disclosure than the annotations alone provide.

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

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

The description is long but structured with labeled sections like RESPONSE, SAFETY FIELDS, and code explanations, and critical warnings are front-loaded. Every major sentence adds behavioral or usage value, though there is minor redundancy around temporal_alignment and compatibility warnings that prevents 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?

With no output schema, the description carries the burden of explaining the return shape, and it does so comprehensively: top_spreads_pp, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and compatibility codes. For a tool with this level of complexity, nothing essential to correct invocation or interpretation 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by explaining how topic maps to events, how kalshi_event_ticker and polymarket_event_slug override the mapped side, and that both modes run the identical token-overlap matcher. This clarifies parameter relationships beyond the schema's simple 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 states the core operation precisely: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes beyond a generic label by explaining the delta is a real signal only when bet shapes are equivalent, and that the tool says so otherwise. This clearly differentiates it from same-venue or single-venue tools like polymarket_arbitrage.

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 documents TWO MODES: pre-mapped topic shortcuts versus explicit event ticker/slug pairings, including the exact shortcut list and override semantics. It also warns that most pre-mapped topics are not currently tradeable, which is strong usage guidance. However, it does not explicitly contrast itself with sibling alternatives such as polymarket_arbitrage or polymarket_edges.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool is scoped to the user's identifier and pairs with 'remember' and 'forget'. This provides useful behavioral context beyond annotations, though the safety profile is already clear from 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 and front-loads the main purpose. It is concise but could be slightly tighter (e.g., the second and third sentences could be merged). Every sentence adds value, making it 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 the simple schema, no output schema, and annotations fully covering safety, the description provides complete context: retrieval behavior, listing mode, scoping, and pairing with sibling tools. No additional information is needed for an AI agent to select and use this tool correctly.

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

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

The input schema covers the single parameter with 100% coverage. The description adds semantic value by explaining the effect of omitting the 'key' argument (lists all keys) and clarifies its purpose in the context of memory storage. This goes beyond the schema's basic description.

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

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

The description clearly states the tool retrieves a value saved via 'remember' and can list all keys when the key argument is omitted. The verb 'retrieve' and 'list' specify the action, and the resource is 'memories'. It distinguishes itself from sibling tools 'remember' and 'forget'.

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

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

The description explains when to use the tool ('to look up context... without re-deriving it') and hints at when not to use by omission (e.g., not for saving or deleting). It also explains both modes (retrieve by key or list all keys). However, it does not explicitly state alternatives for retrieving context beyond this tool.

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

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

Describes return fields and mark_read mutation effect, but contradicts annotations: 'readOnlyHint=true' implies no state change, yet mark_read:true flags events as read (a write). This inconsistency reduces clarity.

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?

First sentence states purpose. Description is clear and well-organized, though slightly verbose. Could be more concise without losing key 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?

Covers return fields, filtering, mutation behavior, and alternative access. No output schema, but description sufficiently explains what the agent receives. Appropriate for a read-oriented 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?

Adds meaning beyond schema: explains mark_read effect on future calls, filter semantics (type, since), and describes return fields. Schema coverage is 100% but description enhances understanding.

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

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

Clearly states the tool pulls fired events from subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload). It's 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 context on filtering (type, since) and the mark_read feature. Mentions polling is fine and notes an alternative access method (GET registry...), but lacks explicit 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return structure (changes[], total_changes, citation URIs). No contradiction with annotations.

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

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

Front-loaded with example queries, then details sources, parameters, and return. Every sentence adds value. Slightly long but warranted given multiple data sources and fallback logic. Could be tightened slightly but still efficient.

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

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

Despite no output schema, the description explains return shape (changes grouped by source, total_changes count, pipeworx:// URIs). It covers all sources, fallback behavior, parameter formats, and explicitly contrasts with entity_profile. Completeness is high for a multi-source aggregation tool.

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

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

Schema covers all parameters with descriptions. Description adds context: type is only 'company', value can be ticker or CIK, and since accepts both ISO date and relative shorthand with recommendation for typical monitoring ('30d' or '1m'). This adds practical usage hints beyond schema.

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

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

The description starts with concrete query examples ('What's new with X', 'latest on Y') and states it's a change feed for a company over a time window. It explicitly distinguishes from sibling tool 'entity_profile', which serves a different purpose (static profile) regardless of window.

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 via example queries and recommends 'use entity_profile instead when you want the static profile'. Also explains fallback behavior between GDELT and GNews, and soft-fail for patents, giving clear context on when to expect results.

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

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

Annotations indicate it is not read-only, not destructive, and idempotent. The description adds value by explaining the key-value storage model, identifier scoping, and retention policies (persistent for authenticated, 24h for anonymous). No contradictions. The only minor gap is lack of explicit mention that overwriting an existing key is allowed (though idempotentHint implies it).

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

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

The description is concise and well-structured. It starts with the main purpose, then provides usage context, and ends with pairing suggestions. Every sentence is useful and there is no fluff.

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

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

Given the simplicity of the tool (2 simple params, no output schema), the description covers all necessary behavioral aspects: purpose, when to use, scoping, persistence, and how it relates to sibling tools. No additional information is needed.

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

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

Schema coverage is 100% with clear parameter descriptions for 'key' and 'value'. The description does not add significant detail beyond the schema's descriptions, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Save' and the resource 'data the agent will need to reuse later'. It distinguishes itself from siblings by explicitly mentioning 'recall' and 'forget' as complementary tools, making the purpose distinct and specific.

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

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

The description provides explicit guidance on when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also details scoping by identifier, persistence differences for authenticated vs. anonymous users, and partners with 'recall' and 'forget' for retrieval and deletion, covering both use and alternatives.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes well beyond that by disclosing cascading internal lookups, graceful degradation when GLEIF/OpenFIGI is unavailable, the `figi_candidates` behavior for ambiguous matches, explicit `unresolved` reporting, and the fact that it replaces multiple manual lookups.

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 and dense, but the complexity of the tool justifies most of the length. It is well-structured with clear labels, examples, and caveats, though a few sections could be tightened without losing essential 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 there is no output schema, the description does an excellent job of explaining expected results, edge cases, enrichment fallbacks, and identifier provenance. An agent has enough behavioral and contextual detail to invoke this tool correctly and interpret ambiguous or partial 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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: it explains input formats, accepted identifier types, exact-name-only guidance, the bond issuer caveat about trailing security-class words, and type-specific behaviors. This significantly helps agents construct valid `type` and `value` arguments.

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

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

The description states a precise purpose: resolving a user-spoken name to canonical/official identifiers that other tools require. It gives concrete query examples and names the supported entity types and identifier sources, making it clearly distinguishable from generic search or lookup tools.

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

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

The description explicitly says to use this tool FIRST whenever the user has a name but needs an ID, and provides examples of triggering queries. It does not explicitly name alternative sibling tools or state when not to use this tool, but the guidance is strong and context-rich.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it probes each entity with ai_visibility_check and returns a ranked list with score/confidence/signal density, transparently disclosing its composed, non-destructive behavior.

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

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

The description is two sentences, front-loaded with the core action, and efficiently conveys purpose, method, and use case without 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?

Despite no output schema, the description explains the return values and references the sub-tool used, making it complete for an agent to understand inputs and outputs. The tool's moderate complexity is well-covered.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the return format (score, confidence, signal density) not present in the schema, helping interpret the 'entities' parameter. This goes beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This differentiates it from the sibling ai_visibility_check (single entity) and other tools, providing a specific verb+resource with a clear competitive audit use case.

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 gives a use case ('competitive AI-marketing audits') and an example question, and implies when to use it (multi-entity comparison) vs. ai_visibility_check (single entity). However, it lacks explicit 'when not to use' or alternatives among other siblings like 'compare_entities'.

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?

Disclosed partial failures, bundlephobia timeout behavior (5-30s), and that sources_failed lists timeouts. Annotations already indicate read-only and idempotent; description adds valuable contextual behavior.

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

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

All sentences add value, front-loaded with core behavior and use cases. Slightly long but well-structured and informative.

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

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

No output schema, but description fully compensates by listing return fields (summary block, advisories, links, alternatives) and explains error behavior, making it complete 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% so baseline is 3, but description adds extra context about scoped packages and default version behavior, raising it slightly.

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: a composite check for npm packages using deps.dev and bundlephobia, and distinguishes from siblings by noting it's NPM-only in v1.

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

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

Explicitly tells when to use ('is X safe/popular/small') and when not (other ecosystems should use deps.dev directly), providing clear guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds substantial behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag, and that passages include offsets for verification.

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

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

Description is concise and well-structured. It front-loads the purpose and use case, then provides technical details and behavioral context. Every sentence adds value 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?

Despite lacking an output schema, the description explains return values (passages with offsets and similarity scores), embedding model, truncation behavior, and pairing advice. It fully addresses the tool's complexity and usage 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 covers 100% of parameters with descriptions. Description adds value by explaining the max char limit for 'text', giving natural-language examples for 'query', and clarifying default for 'limit'. This enhances understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and explicitly addressing the use case of large texts to save context.

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 when the record is too big to cram into the prompt' and explains benefits. It also mentions the truncation cap. Could be slightly improved by explicitly listing when not to use, but current guidance 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?

The description adds significant behavioral details beyond annotations, including authentication requirements, type-specific constraints, delivery channel limitations (10/day cap for SMS, phone verification, webhook auto-disable after 10 failures), and one-time webhook secret return. Annotations only provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false.

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

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

The description is comprehensive and well-structured, starting with purpose, then requirements, types, and delivery channels. While it is somewhat long, every sentence adds value; minor redundancy could be trimmed.

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

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

Given the complexity (multiple types, nested parameters, delivery options, authentication), the description covers all aspects: supported types with examples, delivery channel details and limitations, phone verification, webhook security, and return value. No output schema is needed as the return is just an id.

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 extensive meaning for each parameter, especially for nested objects (params and delivery). It provides type-specific filter examples, delivery options with validation rules, and webhook security details, going well 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It differentiates from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 requires a Pipeworx OAuth account (anonymous/BYO cannot persist) and lists supported types and delivery channels. It provides clear context for when to use, though it doesn't explicitly say when not to use alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds context that the examples are 'drawn from the live catalog of thousands of tools' and that the output includes 'exact tool + argument shape'. This provides meaningful behavioral insight 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 a single paragraph that front-loads example queries, then explains output, then usage. It's efficient and structured, though slightly dense.

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

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

Despite lacking an output schema, the description fully explains the return format (category-bucketed example questions with tool+argument shapes) and covers the tool's behavior, including its role in onboarding. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3. The description reiterates the optional nature and lists possible values, adding minimal extra meaning beyond the schema description.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like ask_pipeworx and discover_tools by being the onboarding entry point. The purpose 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also explains that calling with no arguments gives full spread, and passing a topic focuses the results. Clear when-to-use and how-to-call 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?

The description adds critical behavioral details beyond annotations (which include idempotentHint, destructiveHint): it explains that rows are deactivated (not deleted) and that historical events remain accessible via 'recent_alerts.' This provides transparency about side effects and data persistence.

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 action, and every sentence adds value (ownership, deactivation behavior). No wasted words.

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

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

For a simple one-parameter tool with no output schema, the description covers the key behavioral consequences (deactivation, historical availability). It could mention error handling or success confirmation, but is adequate for typical usage.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'id' parameter. The description does not add semantic value beyond what the schema provides (the id is a uuid from subscribe). 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 'Cancel a subscription by id,' using a specific verb ('cancel') and resource ('subscription'). It distinguishes itself from sibling tools like 'subscribe' (create) and 'list_subscriptions' (list) by noting ownership enforcement and deactivation rather than deletion, making its purpose unambiguous.

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

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

The description explicitly states the ownership constraint ('you can only cancel your own subscriptions'), which guides when the tool is applicable. However, it does not explicitly compare to alternatives or state when not to use it, though the context of cancellation is clear.

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

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

The description discloses rich behavioral context beyond the annotations: it explains the fallback routing pipeline, lists the full set of possible verdicts, defines the meaning of 'could_not_verify' with its verification_error payload and explicitly warns it is not evidence, and clarifies 'unsupported' as a coverage gap. It also mentions the citation format and the fact that it replaces multiple sequential calls, providing deep insight into the tool's runtime behavior.

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

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

The description is detailed yet dense, with every sentence serving a purpose. It front-loads the trigger phrases to aid pattern matching, then logically progresses from purpose to routing to verdict semantics to error handling. The use of semicolons and ellipses keeps it compact, and the final note on replacing sequential calls adds practical value without redundancy.

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

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

Given the tool's complexity (no output schema, 2 params, multiple verdicts, routing logic), the description is exceptionally complete. It explains return values (verdict, actual value, citation, reasoning), distinguishes between the two failure modes, and provides enough context for an agent to invoke the tool correctly and interpret results safely. No major gaps are apparent.

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

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

While the schema already covers 100% of parameters, the description adds significant meaning, especially for tolerance_pct: it explains the default behavior (implied by claim wording, capped at 5), the override capability, and recommended values for hallucination detection (1–2) with a clear rationale. This goes beyond the schema's basic description, though the error object's exact structure is not detailed.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with specific example triggers ("Is it true that…", "fact check"), and explicitly distinguishes it from general Q&A or research tools by stating it verifies claims against authoritative sources and returns a verdict. It also details the two operational paths (SEC EDGAR fast path for company financials, grounded pipeline for everything else), making the purpose and scope highly specific.

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

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

The description provides clear usage guidance: use whenever the agent needs to check factual correctness, and it explicitly routes company-financial claims vs other claims. It also clarifies critical interpretation rules (e.g., 'could_not_verify means the check did not happen... must not be shown as one') and notes that the tool replaces 4–6 sequential calls. However, it does not explicitly name alternative sibling tools for comparison, leaving the differentiation to the reader.

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