Bts

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds key behavioral details: default model, BYO key with direct cost to the user, return structure (score, confidence, signals, raw_response), and that it probes without side effects. 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 6 sentences, efficiently front-loading the main purpose, then covering default model, optional models, return format, and use cases. Every sentence adds value; no redundant or filler content.

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

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

Given the absence of an output schema, the description includes the return format (per-model and combined view). All 4 parameters are covered with context. The tool is moderately complex, and the description provides sufficient detail for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context: default model if models omitted, that _apiKey is only needed for 'anthropic', and that context helps disambiguate. This enriches the parameter semantics 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 probes LLMs for knowledge about a business, brand, product, or topic and scores visibility per model. It specifies the action (probe, score), the resource (entity), and distinguishes the tool from siblings like scan_competitor_ai_presence by focusing on visibility scoring and per-model results.

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

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

The description provides clear usage context (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to pass _apiKey for Anthropic. However, it does not explicitly mention when not to use this tool or compare it to alternatives like scan_competitor_ai_presence, which slightly reduces guidance completeness.

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 (readOnly, openWorld, idempotent) are fully consistent. Description adds operational details: routes to one of 4,774 tools across 1,242 sources, fills arguments, returns structured answer with stable citation URIs. No contradictions.

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

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

Long but well-structured: starts with key directive, explains routing, provides examples, then explicit alternatives. Every sentence serves a purpose, no fluff. Front-loaded with most important info.

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 format (structured answer with citation URIs) and mentions it works on every tier. For a broad tool covering many domains, this is remarkably complete and answers likely agent questions.

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

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

Schema coverage is 100% with clear descriptions for all 6 parameters (aliases). Description adds context by specifying natural language factual queries and providing concrete examples. Beyond schema, it clarifies input expectations and shows acceptable formats.

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 answers factual questions about current/historical data from authoritative sources, lists specific domains (SEC filings, FDA, FRED, etc.), and provides diverse examples. It explicitly distinguishes from sibling tools ask_pipeworx_grounded and deep_research.

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

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

Description gives explicit preference: 'PREFER OVER WEB SEARCH' and detailed guidance on when to use this tool versus alternatives. It specifies when to step up to grounded or deep research and mentions breaking news routing. Provides clear decision rules.

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, destructiveHint. The description adds critical behavioral details beyond annotations: the routing process, the extraction mechanism using only tool results, the structured return format including refusal reasons, and the cost implication (one extra LLM call). No contradiction with annotations.

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

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

The description is a single paragraph but is well-structured: it starts with the core purpose, then explains the mechanism, then lists return fields, then provides usage context. It is not overly verbose given the complexity, though a few phrases could be tightened.

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

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

Given the tool's complexity (high-stakes, refusal reasons, routing across many sources) and the absence of an output schema, the description is remarkably complete. It covers the return format (answer, evidence, confidence, source, fetched_at, refusal_reason), lists all possible refusal reasons, and explains the operational cost trade-off.

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

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

Schema coverage is 100%, so parameters are fully documented. The description mentions that the question is in natural language, which adds minimal meaning beyond the schema's description of 'Your question in natural language.' No deep semantic addition.

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 hallucination-resistant answer mode for high-stakes reads. It specifies the verb 'extract' and the resource 'tool results', and distinguishes it from the sibling tool 'ask_pipeworx' by emphasizing grounded extraction.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete example domains. Also provides a comparator: 'prefer ask_pipeworx for casual lookups', giving clear when-not and alternative.

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

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

The description goes far beyond the annotations (which declare read-only, idempotent, non-destructive) to detail the tool's behavior: market resolution, classification, parallel fan-out to specific data sources, response shapes, resolver contract, parent event extraction, news fallback fields, safety short-circuits (low-confidence matches, closed markets, wide spreads), 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 long but well-structured, front-loading the main purpose and use cases. It uses clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize details. Every sentence adds value for such a complex tool. However, it could be slightly more concise by removing some redundant explanatory notes, but overall it is appropriate for the tool's complexity.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers all major output sections (result.market, result.analysis, result.evidence), the resolver contract, parent event extraction, news fallback fields, and various edge cases (low-confidence matches, closed markets, wide spreads, resolution-rule risk). The agent has virtually all necessary information to use the tool correctly.

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

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

The input schema already describes each parameter (market, depth, include_raw) with their types, enums, and defaults. The description adds significant semantic context: market can be a slug, URL, or question text; depth default is thorough with explanation; include_raw controls response size with practical guidance ('When false... keeps responses under ~20KB. Pass true...'). This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies what it does (resolves, classifies, fans out to data packs, returns evidence packet + comparison). It also lists specific use cases ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'), making it easy for an agent to select.

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

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

The description provides explicit when-to-use guidance via the 'Use for' phrases. It also gives extensive context on how to interpret results (e.g., inspect market_match_confidence, check cancellation_rule before sizing sports bets). It mentions when to use include_raw=true and provides depth options. It does not explicitly state when not to use, but the guidance is sufficiently comprehensive.

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

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

Annotations indicate readOnly, openWorld, idempotent. Description adds value by explaining data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handling of off-calendar fiscal years, and result ordering. 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 somewhat lengthy but front-loaded with example queries. Every sentence provides useful information; could be slightly more compact but still effective.

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

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

Despite no output schema, description mentions return format (paired data + citation URIs) and covers key aspects of the tool's behavior, making it complete for agent usage.

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

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

Schema coverage is 100%, but description significantly enhances understanding: explains enum values, gives examples (tickers for company, names for drug), specifies min/max items, and clarifies what data is fetched per type.

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 specifies it performs side-by-side comparisons of 2-5 companies or drugs in a single parallel call, using example queries like 'compare X and Y'. It distinguishes from sibling tools such as entity_profile (single entity) and sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear when-to-use guidance and contrasting with the alternative of multiple lookups.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context that it's non-destructive and useful as a prerequisite step, but does not introduce new behavioral traits beyond what annotations imply.

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, front-loaded with purpose and key details. 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?

The tool has low complexity (1 param, no output schema, no nested objects). The description sufficiently covers what columns are returned (name, label, type) and the usage pattern (call before querying). Complete for its purpose.

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

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

The single parameter datasetId is fully described in the schema (name and description). The description adds extra semantic value by explaining it's 'Socrata 4x4 code from search_datasets', which helps the agent understand the source of the ID.

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 'List the columns of a data.bts.gov dataset' and specifies the returned attributes (field name, human label, data type). It distinguishes from sibling tools like query_dataset and search_datasets by indicating this is a schema discovery step.

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 'Call this before query_dataset so you know which fields exist' and provides guidance on datasetId being the 'Socrata 4x4 code from search_datasets'. Clearly defines when and why to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: account requirement, expected response time (15-60s), return structure (findings packet with gaps), and parallel execution. 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 effective but somewhat verbose. Front-loads important info (account required) but could be trimmed. Every sentence adds value, though some details (e.g., '4,774 tools IN PARALLEL') are less critical.

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

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

Given the tool's complexity and lack of output schema, the description fully covers account requirements, data sources, alternatives, expected behavior, response structure, and limitations. It leaves no critical gaps.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8), which the schema does not specify. It also clarifies that the question should be broad/multi-part.

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 does grounded multi-source research across Pipeworx's structured data sources, using parallel decomposition. It distinguishes from sibling tools like ask_pipeworx by specifying this is not open-web search and is for broad/multi-part questions.

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 (broad/multi-part questions over structured data) and when-not-to-use (single lookup, breaking/current news). Names alternative tools (ask_pipeworx) and explains why they are better suited in those cases.

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 safe read-only operation. Description adds what the tool returns (top-N tools with full schemas and examples, ready to call directly, no second lookup). This goes beyond annotations and fully discloses 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?

Description is moderately long but well-structured: main action, then usage context, return format, and directive. It earns its sentences without significant fluff. Could be slightly trimmed but effective.

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

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

Despite lacking an output schema, the description thoroughly explains what is returned (names, descriptions, schemas, examples) and that results are immediately usable. It also provides usage context and prioritization advice, making it complete for a discovery 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 6 parameters with descriptions (100% coverage). Description adds value by providing usage examples and listing aliases for the query field. Baseline 3 is appropriate, and the additional context justifies a 4.

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

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

Description clearly states it finds tools by describing a data or task, listing many domains. It distinguishes from sibling tools by acting as a meta-tool for discovery, none of the siblings do this.

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 'Call this FIRST when you have many tools available and want to see the option set'. Also provides specific use cases like browsing, searching, discovering tools for listed domains. While it doesn't explicitly state when not to use, the prioritization guidance is strong.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral context: returns specific fields, describes USPTO sunset and soft-fail behavior, and details data sources and sorting. 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 detailed but well-structured with examples upfront. Every sentence adds value, though it could be slightly more concise. Still, effective for the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (cik, filings, fundamentals, patents, news, LEI) and how data is sorted (e.g., period_end DESC). It covers fallback behavior and constraints, making it complete for an agent to invoke correctly.

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

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

Both parameters (type and value) have complete descriptions in the schema and description. The description explains the distinction between ticker and CIK, and clarifies that names are not supported. This adds meaning beyond the schema enum and type constraints.

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's purpose as 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes from siblings like resolve_entity by indicating name resolution is a prerequisite.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructive and idempotent. Description adds context about clearing stale/sensitive data, but doesn't specify behavior on missing key or permanent deletion.

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

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

Two efficient sentences: purpose, usage, and sibling pairing. 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?

Adequate for a simple tool with 1 param and no output schema. Covers purpose, usage, and some behavioral 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?

Single parameter 'key' with description matching schema. Schema coverage is 100%, so description adds no extra semantics 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?

Clear verb (delete) and resource (memory). Distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Provides explicit when-to-use conditions (stale context, task done, clear sensitive data) and mentions sibling tools for 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?

Description adds context beyond annotations: fetches page, extracts content, emits standard markdown format. Annotations already indicate safe, idempotent behavior. No contradictions found.

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 with clear flow: function, process, use cases. No redundant information.

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

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

Given no output schema, description adequately documents output format (text blob, standard llms.txt) and use cases. Covers all necessary context for an agent.

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

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

Schema coverage is 100%, and description does not add new meaning beyond what schema provides. Baseline 3 is appropriate as description reinforces but does not expand on 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?

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying verb and resource. It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than 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?

Provides clear use cases (client indexing, personal projects, competitor auditing) but does not explicitly contrast with sibling tools or state when not to use. Minor gap in exclusion criteria.

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

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

Description adds context beyond annotations: clarifies default behavior (active only unless include_inactive is true) and specifies return fields. Annotations already cover safety, so this is a strong addition.

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

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

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple list tool with full schema coverage and clear annotations, description provides return fields and usage hints, making it 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 covers the only parameter (include_inactive) at 100%. Description reinforces its effect by stating 'active subscriptions' and implying default false, adding useful 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?

Description clearly states 'List the caller's active subscriptions' and enumerates return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides the agent to appropriate contexts.

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

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

Annotations provide no behavioral hints, but the description fully compensates: it explains it is rate-limited (5/day), free, does not count against tool-call quota, and that feedback is read daily and impacts roadmap. No contradictions.

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

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

The description is a single, focused paragraph that front-loads the purpose and then covers usage, constraints, and quirk. Every sentence adds value, though it could be broken into bullet points for easier scanning.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers purpose, usage, and constraints thoroughly. No critical gaps remain; an agent can correctly invoke this tool.

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

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

Schema already has 100% coverage with descriptions for each parameter. The description adds value by explaining how to write the message (specific, 1-2 sentences) and clarifying that context is optional.

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 sends feedback to the Pipeworx team about bugs, missing features, etc. It distinguishes itself from all sibling tools, none of which serve a feedback purpose.

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

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

Explicitly lists when to use (bug, feature, data_gap, praise) and provides specific instructions on what not to include (end-user prompt). Also mentions rate limits and quota-free usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds valuable context: self-aggregating, no PII, derived from CF analytics-engine, cached. 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?

Two paragraphs, first paragraph immediately states core purpose. Every sentence adds value—no filler. Bullet points in lists enhance readability.

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

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

For a simple tool with one parameter and no output schema, description covers what is returned (top tools, packs, volume), time windows, caching, and data source. Comprehensive for its complexity.

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

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

Schema coverage is 100% for the single parameter window, with enum and description. Description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond the schema.

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

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

Description clearly states it returns 'top tools, top packs, and total call volume' over a recent window, specifying the verb (returns) and resource (trending data on Pipeworx). It distinguishes from siblings like ask_pipeworx and discover_tools by focusing on aggregate trending data rather than queries or discovery.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming popular tool, seeing alignment). Implicitly tells when not to use (for specific queries, ask_pipeworx is better). Mentions caching behavior (5min-1h) to set expectations. Could be improved by stating alternatives more directly.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: it details the two detection methods (monotonicity and partition sum), the sum check (should ≈1), the semantic anchor with Jaccard similarity, partition filter logic, response structure, and the fill check against live CLOB depth. It also warns about conditions that yield untradeable signals. No contradiction with annotations.

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

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

The description is lengthy but well-structured and front-loaded. The first sentence captures the core purpose, followed by clear sections for each mode. Every sentence adds value, though some details (e.g., internal algorithm descriptions) could be considered slightly verbose. However, given the tool's complexity, the length is justified, and it remains focused.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check object, fill check details). It covers edge cases (low similarity, placeholders filtered) and directs to a sibling tool for custom sizing. The description is comprehensive for an arbitrage detection tool with complex logic.

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

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

Schema coverage is 100% with descriptions for both parameters. The description goes beyond the schema by explaining the three modes (no args, event, topic), providing example values, recommending the event mode, and clarifying that full Polymarket URLs are accepted for event. It also explains the cross-event behavior and the internal logic, adding significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from siblings by mentioning the specific algorithms and referencing polymarket_fill_risk for custom sizing. The verb ('find') and resource ('Polymarket') are explicit, and the description outlines three different modes, making the purpose very 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 each mode: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. It explains the semantics of each parameter with examples, mentions limitations (Jaccard similarity, partition filter), and advises against trading when the fill check shows non-realizable edge. It also references a sibling tool (polymarket_fill_risk) for custom sizing, offering clear alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, etc.) by detailing five model families, response segments, diagnostics, caching, and edge cases like Fed bets. It discloses how opportunities are computed and what each field means, providing rich behavioral context without contradicting annotations.

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

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

The description is long but well-structured: a clear one-sentence purpose, then grouped by segment, then response format and caching. Every sentence adds value for a complex tool, though it could be slightly more concise by breaking into cleaner sections.

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

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

Given the tool's complexity (9 params, 3 model families, no output schema), the description is extremely complete. It covers behavior, return structure, diagnostics, caching, knobs, and special cases like Fed bets, ensuring an agent can use it correctly without gaps.

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

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

Schema coverage is 100% with good descriptions for all 9 parameters. The description adds extra context like 'TRADEABLE-EDGE KNOBS' and explains how knobs like min_liquidity and max_spread_pp affect realizable edge, which adds meaning beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly positions it for 'what should I bet on today'. The verb 'scan' and resource 'Polymarket markets' with a specific purpose distinguish it from siblings 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 states when to use the tool (discover betting opportunities with disagreement) and mentions built-in filters and knobs. However, it does not explicitly say when not to use it or compare it to alternatives like polymarket_arbitrage, so it lacks clear exclusions.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It explains the computation of trends and decay, data sources (snapshot family), and limitations (60-day TTL, no intraday data). No contradiction with annotations.

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

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

The description is thorough but somewhat verbose. It front-loads the main purpose but includes many details that could be streamlined. Every sentence adds value, but the length may reduce quick comprehension.

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

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

Given no output schema, the description fully details the response structure (tracked, expired, snapshot_dates) with field explanations. It covers limitations, data freshness, and edge cases, making it highly complete for a complex tool.

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

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

Although the schema already covers 100% of parameters, the description adds contextual meaning by explaining the purpose of days (lookback) and window (snapshot family) with defaults and constraints. This goes beyond the schema's descriptions.

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

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

The description uses specific verbs ('persistence and decay telemetry') and clearly identifies the resource (daily polymarket_edges snapshots). It answers a concrete question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than current edges.

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

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

The description explicitly states its purpose (understanding edge persistence and decay) and implies when to use it versus polymarket_edges, which likely provides current edges. It does not explicitly state when not to use it or alternatives, but the context is clear enough for an AI agent.

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

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

The description aligns with annotations (readOnlyHint, idempotentHint, openWorldHint, not destructive) by disclosing it's a read-only check that depends on live order book depth. It details behaviors like walking the ladder, returning verdicts, and identifying thin legs and directional risk, adding 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?

The description is well-structured with labeled sections (SINGLE-MARKET, BASKET) and front-loads the core purpose. It is relatively long but each sentence adds value; minor room for abbreviation.

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 comprehensively lists all return fields (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk) and explains risks (partial fills, directional exposure). It fully prepares the agent for the tool's complex output.

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

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

Input schema has 100% coverage with clear parameter descriptions. The description adds mode-specific semantics (e.g., size_usd interpreted as settlement notional in basket mode) and clarifies defaults and constraints (clamp 10–1,000,000). However, the schema already does much of the work, so a slight deduction.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and lists the returned fields for each, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause directional risk), giving clear when and when-not to use.

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

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

Annotations already declare readOnlyHint=true (safe read), but the description adds extensive behavioral details: two operational modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning), conditions for invalid spreads (non-equivalent bet shapes, temporal misalignment), and counters for skipped comparisons. 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 fairly long but well-structured: purpose, two modes, response fields, and safety fields. Every sentence adds value, but could be slightly more concise. 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?

Despite no output schema, the description explains the response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and their interpretation. It covers limitations (temporal misalignment, non-equivalence) and usage context. Complete for the tool's complexity.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: explains the two modes, provides example values for topic (e.g., 'fed', 'btc'), and clarifies that explicit parameters override topic-mapped sides. It also describes how parameters interact with response safety fields.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit), defines the spread as Kalshi − Polymarket, and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description provides explicit guidance on when to use each mode, warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable, and explains safety fields like temporal_alignment and compatibility_warning. It implicitly advises when not to use (when fields indicate non-equivalence or misalignment), though lacks an explicit 'when not to use' statement.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: default limit is 50, Socrata max per page is 50000, return format is an array of row objects keyed by field name, and explains SoQL clause behavior. 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 concise (around 100 words) and front-loaded with the main purpose. It lists SoQL clauses in a clear sequence. While a bulleted format could improve scannability, the current structure is effective and not verbose.

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

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

Despite lacking an output schema, the description adequately covers return format. It references sibling tools for context (dataset_columns, search_datasets) and explains the required parameter. The description is complete for a read-only query tool with moderate complexity.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema by providing examples for SoQL clauses (e.g., 'count(*)' for $select, 'date desc' for $order) and explaining the datasetId format. This 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?

The description clearly states the tool queries rows from a dataset using SoQL, specifying the resource (data.bts.gov) and the query language. It distinguishes itself from sibling tools like search_datasets (which finds datasets) and dataset_columns (which gets field names).

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

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

The description provides explicit usage guidance: it advises using dataset_columns first to learn field names. It explains SoQL clauses with syntax examples and notes the default limit. It could explicitly state when not to use this tool (e.g., for metadata), but overall it's 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 declare readOnlyHint, idempotentHint, destructiveHint. The description adds useful context: scope details, that omitting key lists all keys, and pairing with siblings. 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?

Three sentences, each serving a distinct purpose: core function, use cases, scope and pairing. Efficient and well-structured.

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

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

Complete for a simple read-only tool with one optional parameter. Covers usage, scope, and sibling relationships. Annotations handle safety, output schema not 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 a clear description for the key parameter. The description adds real-world examples (ticker, research notes) but does not significantly extend beyond 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?

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' and resource 'memory key/value'. It distinguishes from sibling tools remember (save) and forget (delete).

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: 'look up context the agent stored earlier'. Provides concrete examples (ticker, address, research notes) and mentions pairing with remember/forget. Also notes scope (anonymous IP, BYO key hash, account ID).

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 show readOnlyHint:true and destructiveHint:false. The description adds behavioral detail: mark_read flag changes read state, feed persists, and events carry specific fields. 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?

Three sentences, front-loaded with purpose and return fields, followed by filters and mark_read/polling details. Every sentence adds value; 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?

Despite no output schema, description covers return fields, filters, mark_read semantics, polling, and alternative access. Complete for a list 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. The tool description adds meaning by giving examples (e.g., 'sec_8k') and explaining mark_read behavior ('so the next call only shows newer ones'). Enhances schema, but schema already handles basics.

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

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

The description clearly states it pulls fired events from subscription feed, lists return fields (source, citation_uri, raw payload), and mentions filtering. This distinguishes it from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes).

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 'Polls work fine' and mentions an alternative endpoint (GET registry.pipeworx.io/alerts.json). It doesn't explicitly exclude cases, but provides good context for 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?

Beyond annotations (readOnly, idempotent, etc.), the description details the fan-out to multiple sources, fallback behavior, and API sunset caveat. This is thorough behavioral disclosure.

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

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

The description is a single dense paragraph but well-organized: purpose, sources, parameters, and comparison to sibling. It could be slightly more structured, but it's concise for the content.

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

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

Despite no output schema, the description explains the return structure (changes grouped by source, total_changes count, citation URIs). It covers all major aspects given the tool's complexity.

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

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

Schema already covers all parameters with descriptions. The description adds practical examples and explains the flexible format of the 'since' parameter, adding 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 clearly states the tool provides a change feed for a company in a time window, with multiple query patterns. It specifically differentiates from sibling tool entity_profile.

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 examples of when to use are given, including when to use entity_profile instead. The description tells the agent exactly when to choose this tool versus the alternative.

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 behavioral traits beyond annotations: key-value scoping by identifier, retention differences for authenticated vs anonymous sessions (persistent vs 24 hours). No contradictions with annotations (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?

Four sentences, front-loaded with purpose, no redundant information. Every sentence adds value: purpose, usage context, behavior notes, pairing advice.

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 key-value storage tool with no output schema, the description covers persistence, scope, and pairing with sibling tools. It is complete given the tool's complexity and the information available in annotations and schema.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds example key patterns (e.g., 'subject_property') and value types (findings, addresses), but does not add critical meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Save data the agent will need to reuse later.' It specifies the resource (data) and distinguishes from sibling tools like recall and forget, which are explicitly mentioned.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward...' and mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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, idempotentHint, openWorldHint, and destructiveHint=false. Description adds that each call cascades through multiple endpoints, replacing 2-3 manual lookups, and details return formats (ticker+CIK, RxCUI+ingredient+brand) with citation URIs. No contradictions.

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

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

Description is concise (~10 lines), well-structured with examples, usage guidance, and type details. Every sentence serves a purpose, 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 simple parameters, no output schema, and comprehensive annotations, the description covers purpose, usage, internal behavior, and return values. It addresses ambiguity ('auto-disambiguated') and replaced manual steps, making it fully informative.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches by specifying accepted input formats (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company) and what each type returns, adding 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 clearly states the tool resolves a name to an official identifier with specific examples ('ticker', 'CIK', 'RxCUI'). It uses action verbs like 'resolve' and 'look up', and distinguishes itself from sibling tools as the only entity resolution entry point.

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 FIRST whenever you have a name but need an ID.' Provides examples of when to use it ('What's the ticker for...') and details supported types. No alternative tool for this purpose among siblings, making guidance unambiguous.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context: the tool calls ai_visibility_check for each entity, ranks results, and returns scores, confidence, and signal density. It also explains optional model selection and API key usage. 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 concise with three sentences and a fragment. It front-loads the main action (compare side-by-side) and adds use-case context. No wasted words, but could slightly tighten the return format description. Overall efficient.

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

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

Given 4 parameters, no output schema, the description covers purpose, usage, return structure (ranked list with score, confidence, signal density). It lacks explicit mention of error handling or pagination, but for a simple comparison tool the completeness is sufficient.

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

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

Schema coverage is 100% with parameter descriptions. The description adds enrichment: explains that entities should be brand/business/product names, first is subject, context disambiguates common names. It also clarifies which models are supported and when _apiKey is needed. This goes beyond schema defaults.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. It specifically mentions using ai_visibility_check as a sub-tool, distinguishing it from single-entity probes. The purpose is precise and differentiates from sibling tools like ai_visibility_check and compare_entities.

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 tool is useful for competitive AI-marketing audits with a concrete query example. It implies it should be used for multi-entity comparison, but does not explicitly exclude cases where single-entity probe is sufficient or when not to use it. The context from siblings reinforces the differentiation.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds critical behavioral details: fans out to two sources, partial failures degrade gracefully with sources_failed field, bundlephobia can take 5-30s on first measurement. 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 a single dense paragraph that efficiently conveys all key points. It front-loads purpose and usage. While somewhat long, every sentence adds value. A slight structure improvement (e.g., bullet points for return fields) could earn a 5.

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

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

Despite no output schema, the description thoroughly explains the return structure (summary block with fields, per-advisory detail, links, alternative versions). It covers edge cases (partial failure, first measurement delay) and ecosystem limitations. Highly complete for a multi-source composite 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%, so baseline is 3. The description repeats schema info for both parameters (package name, version default) but adds no new semantic meaning. The version example '18.3.1' provides minor format clarity, but insufficient to raise score above baseline.

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

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

The description clearly states it is a composite check for npm packages, combining license, advisories, version history, and bundle size. It uses specific verbs ('scan', 'fans out') and distinguishes from siblings like 'scan_competitor_ai_presence' and 'validate_claim'.

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: when agent asks about safety/popularity/size of an npm package. Also specifies when not to use: for non-NPM ecosystems, directing to deps.dev:version directly. Provides clear context and alternative.

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 about portal coverage (aviation, freight, etc.) beyond annotations. 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?

Two sentences plus topic list, front-loaded purpose, no waste.

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

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

Fairly complete for a search tool with 3 params and no output schema; domain coverage and usage explained.

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 example queries and explains returned fields; schema already covers parameters well.

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 datasets on a specific portal, returns id, name, description, and distinguishes from query_dataset.

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

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

Explicitly says to use returned id with dataset_columns and query_dataset, and provides example queries. Could mention 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?

Adds rich detail beyond annotations: embedding model, window size, offset tracking, truncation behavior. No contradictions with readOnlyHint etc.

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

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

Four sentences, front-loaded with purpose, then usage, then technical details. No redundancy, every sentence adds value.

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

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

Despite no output schema, the description fully explains return values and technical implementation, making it self-sufficient for an AI agent.

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

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

Schema coverage is 100%, and the description adds examples for 'query', default for 'limit', and cap warning for 'text', plus explains output format (passages with offsets and scores). Enriches schema substantially.

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

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

The description uses a specific verb ('search') and resource ('inside a fetched record'), clearly distinguishing it from siblings like 'ask_pipeworx_grounded' by emphasizing inner-document search. No tautology.

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 ('too big to cram into the prompt'), provides a sibling alternative ('Pairs with ask_pipeworx_grounded'), and mentions limitations (200K char cap). 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?

The description discloses behavioral traits beyond annotations: return of subscription id, OAuth requirement, delivery channel limitations (email validation, SMS 10/day cap, webhook auto-disable after 10 failures). Annotations already set idempotentHint=true, openWorldHint=true, and destructiveHint=false, and the description aligns with no contradictions.

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

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

The description is well-structured and front-loaded: first sentence states core purpose, second addresses prerequisites, then types, then delivery channels. Every sentence adds unique 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 (three parameters, nested objects, multiple enum types) and absence of output schema, the description covers all types, params, and delivery options comprehensively. However, it omits potential error cases, rate limits beyond SMS, or behavior on duplicate subscriptions, leaving minor gaps.

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

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

Schema description coverage is 100%, and the description adds significant meaning: it explains type-specific params for each enum (e.g., sec_8k items codes, polymarket_edge topics, fred_series series_id) and elaborates on delivery sub-parameters (email, SMS, webhook) with examples and operational details like HMAC signing and auto-disable.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the return value ('Returns the new subscription id') and distinguishes from sibling tools like 'list_subscriptions', 'unsubscribe', and 'recent_alerts' 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 subscriptions)', providing clear guidance on who should use it. It lists supported subscription types with examples, but does not explicitly state when NOT to use this tool or provide direct alternatives, though sibling tools imply related actions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about output structure (category-bucketed questions with tool+argument shapes) and parameter behavior (no args for full spread, topic for focus). No contradictions with annotations; the description complements them well.

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

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

The description is a dense but well-structured single paragraph. It front-loads key usage examples and then explains output and parameter options. Every sentence adds value, though a bulleted list might improve scannability for agents. 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?

Given the tool's simplicity (1 optional parameter, no output schema, rich annotations), the description is complete. It covers purpose, output format, when to use, and parameter customization. The return format is explained adequately despite the lack of an output schema.

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

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

Schema description coverage is 100%, with the schema already describing the 'topic' parameter as an optional focus area. The description adds example values and context on usage, but does not significantly extend meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point, stating what it does: returns category-bucketed example questions with exact tool+argument shapes. It explicitly distinguishes itself from other tools by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you', differentiating it from siblings like ask_pipeworx or discover_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 provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains how to customize with the optional 'topic' parameter. While it doesn't list exclusions, the positive guidance is clear and 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 only indicate write operation and idempotency. The description adds crucial behavioral details: ownership enforcement (only cancel own subscriptions) and that the row is deactivated (not deleted) with historical events available via 'recent_alerts'. This disclosure goes beyond annotations.

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

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

Two concise sentences cover core action, constraint, and behavioral nuance without any unnecessary words. Every sentence earns its place.

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

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

Given the tool's simplicity (1 required param, no output schema), the description fully covers what the tool does, how to use it, constraints, side effects, and relation to sibling tools. No gaps remain.

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

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

Schema coverage is 100% with description of 'id' as 'Subscription id (uuid) returned by subscribe.' The description adds little new information beyond restating 'by id,' but it confirms the id origin 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 the verb 'Cancel' and the resource 'subscription', distinguishing it from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description explicitly says to use the tool to cancel a subscription by id, mentions ownership constraint, and points to 'recent_alerts' for historical events. However, it lacks explicit directives on when not to use or alternatives like 'subscribe' for creation.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds significant context: returns verdict types, extracted structured form, actual value with citation, and percent delta. It also explains the underlying data sources (SEC EDGAR + XBRL) and current limitations (only company-financial claims), which is beyond the annotations.

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

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

The description is moderately concise and front-loaded with trigger phrases, followed by details on domain, output, and benefits. Every sentence adds value, though it could be slightly tighter. It effectively communicates the tool's essence without unnecessary fluff.

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

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

For a tool with a single parameter and no output schema, the description is remarkably complete. It specifies the input format, domain scope, output elements (verdict types, citation), and the underlying data sources. It also explains the tool's efficiency gains, making it fully self-contained for an agent.

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

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

Schema coverage is 100% with a clear description of the 'claim' parameter. The description adds value by providing example claims and explaining the natural-language format. This reinforces the schema and clarifies the expected input beyond the schema's minimal 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's purpose: 'natural-language claim verification against authoritative sources.' It provides trigger phrases ('Is it true that…', 'fact check') and specifies the domain (company-financial claims). It distinguishes from siblings by noting it replaces multiple 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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It defines the scope (company-financial claims) and mentions it replaces multiple calls. While it doesn't explicitly list exclusions, the context is sufficient for an agent to decide when to invoke.

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