Govtrack

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

Annotations already indicate safe, non-destructive, idempotent behavior. The description adds context: default model, payment for Anthropic, return structure (per-model score, confidence, signals, raw_response + combined view). This extra detail enhances transparency.

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

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

The description is concise, well-structured, and front-loaded with purpose. Every sentence adds value: purpose, default model, optional key, return format, and use cases. No unnecessary 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 has 4 parameters, 1 required, and no output schema, the description adequately explains the return format (per-model and combined view) and covers default behavior, optional parameters, and use cases. It is complete for an AI agent to understand tool functionality.

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. Description adds minimal extra meaning beyond schema—e.g., examples for entity and clarification that _apiKey is passed straight through. It does not significantly enrich parameter understanding.

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

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

The description explicitly states the tool probes LLMs for knowledge about an entity and scores visibility. It uses specific verb 'Probe' and resource 'LLMs', and distinguishes from siblings by focusing on AI visibility audits, brand checks, etc.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model and API key requirement for Anthropic, but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds context that the tool uses 3,745 tools across 884 sources, fills arguments, and returns structure with citation URIs. No contradictions. Adds useful behavioral insight 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 somewhat lengthy but front-loaded with the most important guidance. Every sentence adds value, including examples. Could be slightly more concise, but overall well-structured.

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

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

Given no output schema, the description explains the output format (structured answer with URIs). Covers purpose, usage scope, input semantics, and output expectations comprehensively.

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

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

Schema coverage is 100% and already describes the question parameter and its aliases. The description reinforces that the input is a natural language question and provides examples, but does not add new semantic information beyond what schema provides.

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

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

The description explicitly states the tool routes questions to an extensive set of sources, returning structured answers with citation URIs. It distinguishes itself from web search and gives concrete examples, making the purpose very clear.

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

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

Directly says 'PREFER OVER WEB SEARCH' and lists specific data types (SEC filings, FDA drugs, etc.) where the tool is superior. Provides examples of query phrasing ('what is', 'look up', etc.) and example questions, giving unambiguous when-to-use guidance.

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

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

Annotations already provide read-only, idempotent, open-world hints. The description adds crucial behavioral context: hallucination-resistant, uses only tool result, returns explicit refusal reasons, and details the return object (answer, evidence, confidence, source, fetched_at, refusal_reason). 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 focused paragraph that front-loads purpose, explains process, return format, and usage guidelines. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description fully covers return values in both success and failure cases, explains cost trade-off with sibling, and provides enough context for an AI agent to select and use the tool appropriately for high-stakes queries.

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

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

Schema coverage is 100% with all parameters aliased to 'question' and described. The description does not add meaning beyond the schema, so baseline 3 is appropriate. It lists aliases but no new semantic value.

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

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

The description clearly states the tool's purpose: hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling 'ask_pipeworx' by noting it costs an extra LLM call and is for scenarios where answers must be cited or acted upon, avoiding fact invention.

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 (quoted/cited answers, high-stakes domains like financial/legal/medical) and when not to use (prefer ask_pipeworx for casual lookups). Also explains refusal reasons, helping the agent decide if the tool can satisfy its needs.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic, resolver contract with confidence scores, parent event extraction, news fallback mechanisms, safety short-circuits (low confidence, closed markets), liquidity warnings, and resolution rule risk. No contradiction; all disclosures are 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 lengthy but well-structured with bold section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the core purpose and input types. While verbose, every sentence provides necessary detail for safe tool use. A slightly tighter edit could improve conciseness.

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

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

No output schema is provided, so the description must explain return values. It does so comprehensively: result.market (bid/ask/spread/liquidity), result.analysis (model prob/edge/kelly, 24h move warning), result.evidence (keyed by source), resolver contract, parent event extractor, news fields, safety mechanisms, and resolution rule risk. All edge cases are covered.

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

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

Schema coverage is 100% (all three parameters described). The description adds meaning beyond the schema: for 'market', it explains slug/URL/question text variants; for 'depth', it clarifies quick vs thorough; for 'include_raw', it explains default summary vs raw payload and size implications. This adds value, though the schema already covers basics.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from sibling tools like polymarket_edges and ask_pipeworx by focusing on a single bet with full fan-out and resolver logic.

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 specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and advises inspecting resolver fields before trusting analysis. It does not explicitly exclude sibling tools, but the context is clear. A minor improvement would be to mention when not to use it (e.g., for quick quotes without bet context).

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are present and the description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), off-calendar fiscal year handling, sorting by primary metric, and citation URIs. No contradiction.

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

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

The description is front-loaded with common query patterns and instructions, making it easy to scan. While slightly verbose due to detailed explanations for two entity types, every sentence adds value. Could be trimmed slightly but not overly long.

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: financial metrics for companies, adverse-event/approval/trial counts for drugs, sorted by primary metric, with citation URIs. This is complete for a comparison tool of 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 coverage is 100% and the description adds meaning beyond the schema: explains 'type' enum values with what data is pulled, and 'values' array with examples and constraints (tickers/CIKs for company, drug names for drug). This fully compensates for any gaps.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data sources and output. It distinguishes from sequential single-entity lookups and sibling tools like 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?

Explicitly lists query patterns ('compare X and Y', 'X vs Y', 'rank these companies') and provides preference instruction over sequential lookups. Also explains per-type data behavior, giving clear context for when 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 significant behavioral details beyond annotations: parallelism across 3,745 tools, 15-60s latency, citation format, explicit gaps for unanswered facets, and pre-verified findings.

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

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

Well-structured and front-loaded with core function, then details. Length is justified by complexity but could be slightly tighter.

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

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

Completely describes the research process, output structure (findings packet with evidence, confidence, source, etc.), and constraints (account, depth pricing). No 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%. Description adds meaningful context: explains depth enum values (quick=3, standard=5, thorough=8) and clarifies question is natural language with broad/multi-part acceptable.

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 performs grounded multi-source research in one call, decomposing questions into facets. Distinct from sibling ask_pipeworx, which is for single 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 tells when to use (broad/multi-part questions) and when not to (use ask_pipeworx for single lookups). Also notes account and payment requirements.

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, and non-destructive behavior. The description adds that results include full input schemas with curated examples and are 'ready to call directly', which provides useful behavioral context beyond annotations. There is 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 fairly concise with a clear front-loaded purpose statement. It includes examples and domain list, which are helpful but slightly lengthy. Every sentence adds value, but could be trimmed slightly.

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

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

Given the tool's complexity (6 parameters, 1 required, no output schema), the description provides essential context: specifying return format (names, descriptions, schemas), usage guidance, and aliases. It is complete enough for an agent to understand what the tool does and how to use it.

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

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

Schema coverage is 100% with all parameters described. The description adds context about the query parameter accepting natural language and aliases, but these are already mentioned in the schema. Baseline 3 is appropriate as the description does not significantly enhance 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?

The description starts with a specific verb 'Find tools by describing the data or task', clearly defining the tool's function. It lists numerous concrete use cases (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a discovery/search tool, not a query-specific tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use guidance. Also implies that for specific queries, other tools would be used after discovery.

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

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

Annotations already mark read-only, idempotent, non-destructive. Description adds behavioral details: fans out across multiple sources, returns specific data (CIK, filings with URIs, fundamentals, patents with soft-fail note, news fallback, LEI). 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 verbose, mixing many example queries and detailed return fields. Front-loaded with examples helps, but could be more structured and concise.

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 complexity (multiple sources, fallbacks, sunsetting), description covers main outputs and limitations. No output schema exists, but listing return fields compensates.

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

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

Schema coverage is 100%. Description adds meaning: zero-padded CIK requirement, ticker format, and reinforces that names are not supported. Provides context beyond schema.

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

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

Description starts with clear example queries ('Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company in ONE parallel call.' Verb+resource is specific, and it distinguishes from sibling tools by explicitly naming resolve_entity for name resolution.

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

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

Explicitly advises to prefer this tool over chaining individual lookups for holistic views. Also states when to avoid (names only) and directs to resolve_entity, providing 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description confirms deletion ('Delete') but adds no additional behavioral details beyond what annotations provide.

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

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

Three sentences: first states purpose, second provides usage guidance, third mentions paired tools. No wasted words, front-loaded with essential 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?

Given the simplicity (1 param, no output schema, annotations present), the description covers purpose, usage, and pairing. It could mention error handling (e.g., if key doesn't exist), but overall it's 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% and the description of the 'key' parameter is 'Memory key to delete,' which adds no extra meaning beyond the schema's 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?

Description clearly states 'Delete a previously stored memory by key.' It specifies the action (delete) and resource (memory by key), distinguishing it 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?

The description provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', giving clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This explains the process beyond what annotations provide. No mention of rate limits or auth, but not needed given the simple read operation.

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

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

The description is three sentences: first states purpose and audience, second describes the process, third lists use cases. Every sentence adds value, no filler. Well-structured and front-loaded with the most important information.

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

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

For a simple tool with two parameters and no output schema, the description is complete. It explains what it does, how it works (fetching and extracting), the output format ('standard llms.txt markdown format', 'single text blob'), and use cases. No gaps given the tool's complexity.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' described in the schema. The description adds only a default and max for 'max_links', which is already in the schema. Baseline 3 is appropriate as the schema already handles parameter documentation adequately.

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 generates 'a production-ready llms.txt file for any URL' for specific AI crawlers. The verb 'generate' and resource 'llms.txt' are specific, and it distinguishes from sibling tools like 'scan_competitor_ai_presence' which don't mention llms.txt generation.

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

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

The description lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' While it doesn't explicitly state when not to use it, the use cases are clear and imply appropriate contexts. It does not name alternative tools but the context signals show many sibling tools.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds that it returns specific fields and defaults to active subscriptions. Adds value 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 sentences, no wasted words. Purpose front-loaded, efficient and clear.

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

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

For a simple read-only list tool with good annotations, the description covers purpose, usage, and return fields. No 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% (include_inactive described). Description implicitly references it via 'active' vs 'cancelled' but does not add new meaning beyond 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?

Clearly states 'List the caller's active subscriptions.' Verb (list) and resource (subscriptions) are specific. Distinguishes from siblings 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 states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides context and implies alternatives.

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

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

Annotations indicate non-readOnly, non-destructive, non-idempotent, non-open world. The description adds valuable behavioral details: rate-limited (5 per identifier per day), free, doesn't count against tool-call quota, and signals that feedback affects the roadmap. 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 extremely concise—four sentences that front-load the purpose and immediately provide actionable guidance. Every sentence adds value, with no redundancy or 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 feedback submission tool with no output schema, the description covers all necessary aspects: what to use, when to use, what to include (be specific, relate to Pipeworx tools/packs), and constraints (rate limits, no quota impact). No missing information 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 description coverage is 100% (all parameters have descriptions). The description adds extra context: explains enum values for type (bug, feature, data_gap, praise, other) in more detail, and provides message length guidance (1-2 sentences, 2000 chars max). While the schema already describes the parameters, the description adds practical usage tips, justifying a score above the baseline of 3.

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

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

The description clearly states the action ('Tell the Pipeworx team') and the resource (feedback). It explicitly lists the types of feedback (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by framing it specifically as feedback to the Pipeworx team.

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

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

The description provides explicit when-to-use scenarios: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a when-not-to-use directive: 'don't paste the end-user's prompt.' This perfectly guides the agent.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant context: data source (CF analytics-engine), no PII, caching (5min-1h), and self-aggregating signal. 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 with core purpose upfront and bullet-pointed use cases. While it provides substantial information, it remains efficient without unnecessary verbosity.

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

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

Despite no output schema, the description clearly states what is returned (top tools, top packs, total call volume). It also addresses caching behavior. For a simple tool with one optional parameter, this is fully complete.

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

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

Schema has 100% coverage for the single parameter with enum and description. The description adds extra meaning by explaining the effect of window choice on results ('hot right now' vs 'steady-state demand'), going 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 it returns top tools, top packs, and total call volume, with specific verb 'Returns' and resource identification. It distinguishes from siblings by specifying 'What other AI agents are calling on Pipeworx right now' and provides three concrete use cases.

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 includes three explicit use cases and explains window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). It does not explicitly mention when not to use or name alternatives among siblings, but the context is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description details the algorithm steps, including Jaccard similarity thresholds, placeholder filtering, partition checks, and fill verification using live book depth. It also explains response structure and failure conditions (e.g., low similarity, placeholders).

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, starting with a requirement and then progressing through modes, filters, and response details. Every sentence adds necessary information given the tool's complexity, though it could be slightly more concise.

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

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

Despite the absence of an output schema, the description thoroughly covers return values (opportunities array, partition_check, fill check) and edge cases (cross-event similarity failures, placeholder filtering). It references a sibling tool for custom sizing, ensuring the agent has all needed 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?

Both parameters are described in the schema, but the description adds significant meaning: it explains that 'event' expects a slug or URL for a specific market, while 'topic' expects a seed question for cross-event scanning. It also clarifies how each mode processes data and what to expect.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (single-event and cross-event), which differentiates it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly requires one of 'event' or 'topic' and provides examples for each. It recommends event mode for a specific market and topic for scanning related events, and directs users to polymarket_fill_risk for custom sizing. However, it does not explicitly state when not to use the tool, but the guidance is otherwise 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, and non-destructive behavior. The description goes far beyond by detailing caching (1h KV-level), response structure (by_segment, diagnostics), model families, edge calculation (e.g., slippage, Kelly fractions, 24h-move warning), and filter knobs. 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 dense and comprehensive, but somewhat verbose. It front-loads the purpose well but includes extensive technical detail (e.g., per-sport alpha values, placeholder filter logic) that could be trimmed or moved to a separate section. It is structured but not maximally concise.

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 (by_segment with three segments, diagnostics, Fed note) and edge calculations. It covers caching, filter behavior, and edge cases (e.g., why Fed markets are excluded). Given the tool's complexity and 9 parameters, the description is exceptionally complete.

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

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

Input schema covers all 9 parameters with descriptions (100% coverage). The description adds valuable context beyond schema, such as explaining tradeable-edge knobs (min_liquidity, max_spread_pp as filters), min_partition_leg_kelly usage, and default values with rationale. This lifts the score above baseline 3.

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

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

The description opens with a clear verb-resource statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately signals the tool's purpose for discovering betting opportunities, distinguishing it from siblings like polymarket_arbitrage and bet_research by emphasizing its unique data-driven edge detection.

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 states it's built for 'what should I bet on today' and that agents avoid paging hundreds of markets, providing context for when to use. However, it does not explicitly mention when not to use it or name alternatives among siblings (e.g., polymarket_arbitrage). Some guidance is present but incomplete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: limits on history depth (60-day TTL, snapshot start date), that decay uses daily closes, and that gaps mean no scan occurred. This adds significant value.

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 long but well-structured: core purpose first, then answer to the question, then detailed response fields, then limits. Every sentence adds value. Could be slightly more concise, but the structure is logical and front-loaded with the 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?

Given no output schema, the description compensates by fully explaining the response structure (tracked[], expired[], snapshot_dates[] with field details). It covers edge cases (gaps, limits, decay computation) and provides sufficient context for an agent to understand the tool's complexity and output. Complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by repeating default values (14 for days, '1wk' for window) and constraints (max 30 for days). It explains that 'days' is the lookback and 'window' selects the snapshot family, providing context beyond the schema descriptions.

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

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

The description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' clearly specifying the verb (telemetry) and resource (edge persistence/decay). This distinguishes it from sibling tools like 'polymarket_edges' (likely raw current data) and 'polymarket_arbitrage' (arbitrage opportunities).

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 what question the tool answers and contrasts use cases: 'a fresh wide edge and a 3-week-old wide edge are different trades.' It implies when to use it (persistence analysis) but does not explicitly state when not to use it or name alternatives. Clear context but lacks explicit exclusion.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) indicate a safe, read-only check. The description goes beyond by detailing behaviors like walking the order book, returning verdicts (clean|degraded|cannot_fill), and highlighting risks such as thin books and forced directional 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 comprehensive and well-structured, with clear section headings (SINGLE-MARKET, BASKET) and capital emphasis for key points. It is slightly verbose but every sentence contributes essential information. It earns a 4 for being informative without redundancy.

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

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

Despite the tool's complexity (two modes, multiple return values), the description covers all aspects: required parameters, mode-specific behavior, return fields, and risk explanations. No output schema exists, so the description adequately explains outputs like top_of_book, vwap_fill_price, capture_ratio, etc. It is fully self-contained.

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 has 100% description coverage, so the baseline is 3. The description adds value by explaining the default 'auto' side for basket mode and clarifying that size_usd for basket is 'settlement notional'. However, the schema already describes each parameter adequately, so the increment is modest.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and lists specific return values, making the purpose highly specific and distinct 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?

The description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing clear when-to-use guidance. It also explains why (theoretical overround not capturable, partial fills convert arb to directional position), which is excellent for decision-making.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant context: compatibility_warning conditions (cross-type mismatch, no match), temporal alignment issues, skipped_cross_type/subtype counters. 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 thorough but slightly verbose; however, every sentence adds necessary detail about modes, response fields, and safety fields. Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Minor room for trimming.

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 covers usage, behavior, edge cases, and result interpretation comprehensively. Explains response contents and warning field meanings thoroughly.

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%. The description adds value beyond schema by explaining how topic maps to events, that tickers override mapped sides, and provides examples. Enhances understanding of parameter interactions.

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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two modes: topic shortcuts and explicit tickers. It 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?

Provides explicit guidance: when to use (checking spread between venues), when not to rely on output (compatibility warning fired), and warns that pre-mapped topics often are not tradeable. Offers alternatives implicitly by explaining limitations.

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 valuable context: listing all keys when key is omitted, scoping per identifier, and the relationship with remember/forget.

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 (two sentences plus a clarifying note) and front-loaded with the core action. 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?

Covers purpose, usage, scoping, and sibling tools. However, it does not describe the return format or output structure, which would be helpful given no output schema.

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

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

Schema coverage is 100%, and the schema description already states 'omit to list all keys'. The tool description largely repeats that, adding no new parameter-level insight beyond what the schema provides.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys if the key argument is omitted. It distinguishes itself from sibling tools 'remember' and 'forget' by positioning itself as the retrieval operation.

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

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

Provides concrete use cases (ticker, address, notes) and explicitly pairs with remember/forget. However, it does not explicitly state when not to use this tool or detail exclusion conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds concrete behavioral details: mark_read flagging, poll friendliness, and return field structure, which enriches 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?

Relatively concise at ~80 words. Front-loaded with main action and key fields. A bit dense but every sentence adds value.

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

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

Given no output schema and 5 parameters, description covers purpose, return content, filtering, side effects, polling, and alternative endpoint. No obvious gaps for typical usage.

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

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

Schema coverage is 100% so parameters are already documented. Description adds minimal extra meaning: clarifies mark_read side effect (flags returned events as read) and notes limit range (1-200).

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 pulls fired events from the subscription feed and specifies key return fields (source, citation_uri, raw payload). Implicitly distinguishes from siblings like list_subscriptions and recent_changes by focusing on alerts and feed 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?

Provides context on when to use (polling works fine) and mentions alternative access via URL. Lacks explicit guidance on when not to use or direct comparison to sibling tools.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds rich behavioral context: fan-out strategy, fallback from GDELT to GNews, USPTO soft-fail, relative date handling, and structured return format.

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 every sentence adds value. Front-loads with common query patterns. Could be slightly tighter but not wasteful.

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 details return structure (changes grouped by source, total_changes, citation URIs). Covers fallbacks and edge cases (rate-limits, sunset). Completeness is high for a complex tool.

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

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

Schema coverage is 100%, but description adds meaning: explains 'since' accepts ISO or relative with defaults, clarifies 'value' accepts ticker or CIK. Provides example inputs like "30d" and "AAPL". Slightly above baseline 3.

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

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

The description clearly states it provides a change feed for a company, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool entity_profile by contrasting windowed vs static 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?

Explicitly lists common user queries ("What's new with X", etc.) and provides a clear when-not-to-use example: use entity_profile for static profiles regardless of window.

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 (idempotentHint=true, destructiveHint=false), the description adds details about key-value scoping by identifier, 24-hour retention for anonymous, persistent for authenticated users, and no contradictory claims.

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

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

The description is three efficient sentences: main action, when to use, storage behavior. Front-loaded with the core purpose, no wasted words.

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

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

For a 2-parameter tool with no output schema, the description covers purpose, usage, persistence, and pairing with sibling tools. No missing critical context.

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

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

Schema coverage is 100% with descriptions. The description adds naming conventions (e.g., 'subject_property') and clarifies the value as any text, providing moderate additional meaning beyond the schema.

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

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

The description explicitly states 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference). It distinguishes from sibling tools like recall and forget by mentioning pairing with them.

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

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

It clearly states when to use: 'Use when you discover something worth carrying forward' and contrasts with anonymous vs authenticated sessions. It also recommends pairing with recall and forget for full lifecycle.

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 behavior. The description adds that each call 'cascades through several lookup endpoints internally,' replacing 2-3 manual lookups. This provides useful behavioral context beyond annotations, but the core safety traits are already captured.

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 examples, a summary, and detailed type breakdowns. Each sentence contributes meaning, though it is slightly verbose. The front-loaded usage tip and clear bullet-like formatting for types aid 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?

Despite lacking an output schema, the description fully explains return values for each entity type, including citation URIs. It also notes internal cascading behavior. The tool is simple with only two parameters, and the description covers all necessary context for correct invocation.

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

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

Schema description coverage is 100%, and the description adds significant value: it provides example values for 'type' and 'value,' explains how each type processes input (e.g., company accepts ticker, CIK, or name), and details the return format (ticker, CIK, company_name, citation URI). This fully illuminates parameter purpose and behavior.

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

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

The description begins with concrete user queries, clearly stating it resolves names to official identifiers. It explicitly distinguishes from siblings by specifying 'use FIRST whenever you have a name but need an ID' and outlines supported entity types and outputs, making the purpose unmistakable.

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

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

The description includes explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides clear context for when to invoke the tool. However, it does not mention when not to use it or explicitly compare to sibling tools like 'entity_profile', which could perform similar 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specific behavioral details: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density.

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 well-structured sentences: purpose, method, and usage context with output details. No redundancy or wasted words. Information is front-loaded.

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

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

For a tool with 4 parameters, 1 required, and no output schema, the description fully explains inputs (entities, models, context), process (probe, rank), and output (ranked list with score, confidence, signal density). No missing critical details.

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

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

Schema description coverage is 100%. The description adds value by explaining that the first entity is treated as the 'subject', that context disambiguates common names, and that models require an optional API key for Anthropic. This goes beyond the schema's technical descriptions.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb-resource combination. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general compare) by specifying it probes each entity and ranks 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 context: 'Useful for competitive AI-marketing audits' and gives an explicit example question. It does not specify when not to use, but the multi-entity comparison purpose is well-articulated.

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

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

Annotations already mark as read-only, idempotent, non-destructive. Description adds beyond: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

Description is front-loaded with purpose, then explains composition and outputs. Every sentence adds value, including edge cases like failing sources and scoped packages. Efficient use of 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?

No output schema exists, but description thoroughly lists return fields (summary block, per-advisory detail, links, alternative versions). Covers partial failures and timeouts. Complete for a two-parameter 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% and schema already describes parameters. Description adds that version defaults to latest, but provides no new meaning beyond schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size via deps.dev and bundlephobia. It uses specific verbs and resources (fans out, returns summary block) and is distinct from siblings which serve different domains.

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: when an agent asks about package safety, popularity, size, or cost. Also specifies NPM-only in v1 and directs users to deps.dev:version for other ecosystems. Provides clear context for 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 and idempotentHint, but the description adds valuable behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation and flagging. 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 yet comprehensive, using only a few sentences to convey purpose, usage, pairing, technical details, and constraints. No unnecessary words, and information is front-loaded with the main action.

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

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

Given no output schema, the description adequately explains return values (passages with offsets and scores) and includes model details, chunking, truncation, and pairing with sibling tools. It covers all essential aspects for an agent 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?

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for the 'query' parameter and clarifying the 'text' parameter context (e.g., SEC 10-K body). It also reiterates the default limit (5) and range (1-20), though these are in 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: semantic search inside a fetched record, returning top passages with offsets and scores. It specifies the verb 'search' and resource 'inside a fetched record', and distinguishes from siblings like 'ask_pipeworx_grounded' by emphasizing its role for records already obtained.

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

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

Explicit guidance on when to use: 'Use when the record is too big to cram into the prompt'. Also explains pairing with 'ask_pipeworx_grounded' for grounding, and provides technical context about chunking and character limits, including truncation behavior.

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 mutability (creates a subscription), return value, account requirements, delivery channel constraints, and rate limits (10/day for SMS). The annotations indicate idempotentHint=true, but the description doesn't address idempotency, creating a minor gap but no contradiction.

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

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

The description is detailed but well-structured, starting with the core purpose and then expanding on types and delivery. Every sentence adds information, though it could be slightly more concise without losing clarity.

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

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

Despite no output schema, the description covers the return value ('Returns the new subscription id'), all parameter types, prerequisites, and constraints. It is comprehensive for a tool with nested objects and multiple supported types.

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

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

The description adds significant value beyond the input schema by explaining the meaning of each type and parameter, providing examples (e.g., 'items:["5.02"] = officer change'), and detailing delivery channel options with constraints. Schema coverage is 100% but the description enriches 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's function: 'Create a proactive monitoring subscription to a live-data event stream.' It mentions the return value 'Returns the new subscription id.' and distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' 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 gives explicit context for when to use the tool, such as requiring a Pipeworx OAuth account and prerequisites like phone verification for SMS. It does not explicitly say when not to use it, but the detailed constraints provide sufficient guidance.

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

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

Annotations already indicate readOnly and idempotent. Description adds context: it is the onboarding entry point, draws from a live catalog, and returns categorized examples. No contradictions; adds value 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 detailed but front-loaded with key phrases and examples. Every sentence adds value, though it could be slightly more concise. Still appropriately sized for a complex onboarding tool.

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

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

Given 1 optional param, no output schema, and few siblings, the description covers all needed context: when to use, what it returns, parameter behavior. No gaps.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning by listing specific focus areas (finance, pharma, etc.) and explaining that omitting gives a spread. This goes beyond schema descriptions.

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

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

The description clearly states it is the onboarding entry point, lists example questions, and specifies that it returns category-bucketed example questions with tool+argument shapes. This distinguishes it from siblings like 'discover_tools' and 'ask_pipeworx'.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains when to pass 'topic' vs. omit. It implies when not to use and references alternatives (meta-tools).

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

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

Adds significant value beyond annotations: ownership enforcement, deactivation vs deletion, and link to recent_alerts for historical events. 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 concise sentences, front-loaded with action, 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?

Complete for a cancellation tool with one parameter: covers ownership, deactivation, historical availability. No output schema 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%, so baseline is 3. Description does not add new meaning to the 'id' parameter beyond what's in the schema ('Subscription id (uuid) returned by subscribe').

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?

Describes specific verb 'Cancel' and resource 'subscription by id'. Clearly distinguishes from siblings like subscribe and list_subscriptions by mentioning 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?

States ownership enforcement ('only cancel your own subscriptions') which guides when to use. Does not explicitly mention when not to use, but context is clear given siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, consistent with a read-only tool. The description adds valuable behavioral details: it returns a verdict with five specific outcomes, an extracted structured form, actual value with citation, and percent delta. It also explains the underlying data source (SEC EDGAR + XBRL). No contradiction.

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

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

The description is fairly concise, with front-loaded purpose and usage. It includes multiple example phrasings and a brief note on replaced workflow. Every sentence contributes value, though it could be slightly more streamlined without losing clarity.

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

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

Given the tool's simplicity (one parameter, no output schema) and rich annotations, the description is complete. It explains the return types, the domain of supported claims, and the version scope. No additional context seems necessary for correct use.

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

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

Schema description coverage is 100% for the single 'claim' parameter. The description adds further semantic clarity with natural-language examples and domain scope (company-financial claims), which helps the agent form appropriate queries beyond the schema's generic 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: verifying natural-language claims against authoritative sources. It lists specific phrasings ('Is it true that…', 'fact check') and distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls, making its unique value explicit.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also defines the supported scope (company-financial claims). While it doesn't list when not to use or alternative tools, the context is clear and sufficient for appropriate selection.

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