Stocktwits

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: that probing Anthropic requires a user-provided API key and that users pay Anthropic directly. It also details the return structure (per-model score, confidence, signals, raw_response) and a combined view, going well 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 four sentences, each serving a distinct purpose: stating the core function and scoring, explaining default and optional API key, detailing return format, and listing applications. No superfluous information, well 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?

With 4 parameters fully described in schema and additional context in description, the tool is fully specified. The description includes return structure (per-model fields and combined view), which compensates for the lack of output schema. The use cases provided give adequate context for an agent to decide when to 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 coverage is 100%, and the description enriches each parameter with practical context: entity is 'the thing to ask about', models defaults to workers-ai, _apiKey is needed only if Anthropic is used, and context helps disambiguate. This adds significant meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It uses specific verbs (probe, score) and identifies the resource (LLMs), making the intent unambiguous. The tool's unique function is evident among 40+ siblings.

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

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

The description explicitly outlines default model usage (Workers AI Llama-3.3-70b) and the optional activation of Anthropic with an API key. It also suggests use cases like AI-marketing audits and brand checks. However, it does not explicitly state when to avoid this tool or mention alternatives (e.g., scan_competitor_ai_presence), which would improve 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 readOnly/openWorld/idempotent hints, and the description adds valuable context: routing across 5,529 tools, argument filling, structured answers with pipeworx:// citation URIs, one fast call, and tier compatibility. This goes beyond the annotation hints without contradicting them. It doesn't discuss rate limits or failure modes, but the added behavioral detail is significant.

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

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

The description is long but every sentence earns its place: it front-loads the critical 'prefer over web search' directive, then provides scope, behavior, examples, and escalation path. The structure is logical and skimmable, with no filler. Despite length, it remains tightly organized around decision-making.

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

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

For a router tool with no output schema, the description fully explains the return type (structured answer with citation URIs) and the internal process (routing, argument filling). It also covers the decision tree for related tools, making it self-contained for an agent to invoke appropriately. No critical missing context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete examples of valid queries ('current US unemployment rate', 'Apple's latest 10-K') and says it accepts natural language questions, which enhances understanding but doesn't provide new formatting constraints or semantics not already in the schema. No additional param-specific guidance is given beyond the schema's alias list.

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: answering factual questions about current/historical data from authoritative structured sources, routing to 5,529 tools with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives. The verb 'ask' and resource 'Pipeworx' are specific, and the scope is unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing clear when-to-use guidance. It names alternatives: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part queries. It even covers news/breaking-news routing, making the decision framework complete.

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

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

The description goes well beyond annotations by revealing the tool's beta nature, that candidate routing improvements may be active, and that currently it exactly matches ask_pipeworx. It also clarifies it's a full working router, not a fallback, and that results are compared against the stable router for merge decisions.

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

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

The description is three sentences with useful specifics like 'same 5,529 tools' and the retirement date '2026-07-26'. It's slightly verbose but each sentence contributes meaningful context; it could be tightened without losing essential information.

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

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

Given the simple schema and rich annotations, the description fully covers the beta status, current inactive candidate state, and relationship to the stable router. It also specifies the response shape is identical to ask_pipeworx, so no output schema is needed for clarity.

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 thoroughly documents all six parameters as aliases for 'question' (100% coverage). The description only mentions 'same arguments' as ask_pipeworx, adding no new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes itself from the stable sibling by focusing on experimental routing improvements, making its purpose unambiguous.

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

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

It explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (ask_pipeworx) and explains the comparison process. However, it doesn't explicitly state when not to use it, so it stops short of a full 5.

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

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

The description goes well beyond annotations by detailing the exact return structure on success and failure, including refusal_reason values. It discloses the mechanism (uses ONLY the tool result) and the cost tradeoff (one extra LLM call). This enriches the readOnlyHint and openWorldHint annotations without contradiction.

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

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

The description is dense but every sentence adds value: purpose, mechanism, return format, refusal reasons, use cases, and cost comparison. It is structured with a front-loaded key phrase and lists details efficiently, making it easy to parse.

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

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

Given no output schema, the description fully explains both success and refusal return shapes, including refusal_reason values. It covers use cases, limitations, and cost, providing complete context for an agent to decide when to invoke this tool and what to expect.

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

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

The input schema has 100% coverage: all six parameters are aliases for 'question', with the primary 'question' parameter described in detail. The description adds no parameter-specific guidance, but the schema already fully documents them, so baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that routes through the same tool selection as ask_pipeworx, fetches data, and extracts answers strictly from tool results. It is distinguished from the sibling ask_pipeworx by emphasizing grounded, evidence-based answers with explicit refusal behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts and legal claims. It also provides a clear alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description goes beyond by detailing internal processes: fan-out examples, safety mechanisms (low-confidence match, closed markets, wide spread), resolution-rule risk, and response shape. There is no contradiction with annotations.

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

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

The description is well-structured with clear section headers (FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and is front-loaded with the main purpose. However, it is quite lengthy; some sentences could be streamlined without losing essential information.

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

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

Despite no output schema, the description thoroughly explains return values (result.market, result.analysis, result.evidence) and all edge cases (low-confidence, closed markets, wide spread, cancellation rules). It covers everything an agent needs to use the tool effectively.

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 coverage is 100%, with each parameter described. The tool description does not add significant parameter-specific meaning beyond the schema; it provides usage context but no extra syntax or format details. 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies a concrete verb ('Research') and resource ('Polymarket bet'), and the detailed explanation of functionality (fan-out, classification) distinguishes it from sibling tools like polymarket_arbitrage or 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 provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also explains when to use the quick vs thorough depth parameter and notes resolution-match confidence. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the tool's safety profile is clear. The description adds context about data source (StockTwits) and intended use (thumbnail charts), which is useful but not critical beyond annotations.

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

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

Two sentences with high information density: purpose, data source, use case, alternatives. Front-loaded with calling conventions. No wasted words.

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

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

For a simple two-parameter tool with rich annotations, the description covers purpose, usage context, and alternatives. However, it lacks any description of return value format or data granularity, 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 0%, so description should compensate. It implicitly documents the 'symbol' parameter via examples ('[ticker]'), but does not explain the 'period' parameter at all. Meaning added is minimal for the optional parameter.

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

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

The description clearly states it provides 'price sparkline data for a ticker from StockTwits' and gives example usage patterns. It explicitly differentiates from sibling tools by naming alternatives (yahoo-finance, alphavantage) for serious price 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?

Explicitly states when to use ('embedded thumbnail charts') and when not to ('prefer dedicated finance packs...'). Names specific alternatives, giving clear context for agent 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 indicate safe read-only operation, and the description adds valuable behavioral context: handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and replaces many sequential lookups. 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 somewhat dense but well-structured with example queries up front, followed by function details. Every sentence adds value, though minor trimming 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?

Given the tool's complexity (two entity types, multiple data sources, sorting, citation URIs), the description covers all necessary aspects: entity type behavior, data metrics, sorting, and return format. No output schema exists, but the description sufficiently explains returns.

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

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

The schema covers 100% of parameters. The description adds meaning by explaining what data each type pulls (revenue, net income, etc. for companies; adverse-event counts for drugs) and the required format for values (tickers/CIKs for companies, names for drugs), exceeding schema detail.

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

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

The description clearly states the tool's purpose with specific verbs ('compare', 'side-by-side comparison') and the exact resources (companies or drugs). It includes example queries and distinguishes itself from sequential lookups, providing strong clarity.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides clear contexts like 'X vs Y', 'which is bigger', etc. It lacks explicit when-not-to-use or alternative tool names, but the guidance is still 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?

The description adds substantial behavioral detail beyond the annotations: account/auth requirements, latency expectations (15-60s, ~90s for thorough), gap handling (never invented, gaps[]), citation fetchability (pipeworx:// URIs always resolvable), contradiction detection, and semantic excerpting. This greatly enriches the readOnly/idempotent hints already in annotations without contradicting them.

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

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

The description is dense but long, organized in clear thematic blocks (account, capabilities, alternatives, depth behavior, citations, latency). It is front-loaded with the critical account requirement. Though every sentence carries useful information, some points (e.g., the second-hop iteration details) slightly overlap with the schema's depth description, making it less crisp than a shorter, zero-waste description would be.

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 the absence of an output schema, the description compensates fully by detailing the return packet (verbatim evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop field), prerequisites, alternative paths, and performance expectations. This gives an agent complete context for invocation and result interpretation.

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 includes descriptions for both 'question' and 'depth'. The description adds extra meaning by explaining the depth levels functionally (quick=3 facets, standard=5 with gap recovery, thorough=8 paid with iterative hop) and giving concrete examples of suitable questions. While it partially repeats the schema's depth enum, the contextual framing and examples elevate it above the baseline.

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

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

The description explicitly states the tool's purpose with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It also distinguishes itself from siblings by clarifying 'this is NOT open-web search' and naming ask_pipeworx as the alternative for single lookups and current news, making the scope unmistakable.

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

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

Usage guidance is explicit and thorough: it states when to use this tool ('Best for broad/multi-part questions over structured data'), when not to ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even gives a clear fallback for unsigned users ('If you are not signed in, use ask_pipeworx instead'). This goes beyond simple context by providing concrete exclusions and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: it returns the top-N most relevant tools with full input schemas and curated examples, ready to call directly. This goes beyond the annotations and provides safety and efficiency context.

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

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

The description is front-loaded with the core purpose and usage guidance. It is fairly concise given the amount of information packed in, though it could be slightly tighter. Every sentence serves a purpose, and the structure is logical.

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 comprehensively explains what the tool returns (tools with names, descriptions, and schemas). It covers the main use case, lists example domains, and clarifies that results are ready to call directly. The description is complete for an agent to understand and use the tool effectively.

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 does not add significant meaning beyond the schema's parameter descriptions; it mentions 'query' and 'limit' implicitly but does not explain each parameter in detail. The included examples are helpful but not enough to raise the score.

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: to find/discover tools by describing the data or task. It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and explicitly distinguishes itself by instructing to 'Call this FIRST' when many tools are available, differentiating it from siblings that perform specific tasks.

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: 'Use when you need to browse, search, look up, or discover what tools exist for' and 'Call this FIRST when you have many tools available.' However, it does not explicitly state when NOT to use this tool or list alternatives, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds value by detailing multi-source fan-out behavior, returned fields, and soft-fail for patents. 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?

Well-structured with examples first, then purpose, then guidance, then detailed returns. Slightly verbose but every sentence earns its place.

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

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

No output schema, but description fully explains return fields (cik, filings, fundamentals, patents, news, LEI) and limitations. Agent can assess when to invoke and what to expect.

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

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

Input schema coverage is 100% with clear descriptions. Description reinforces with examples (AAPL, 0000320193) and reiterates name restriction, adding marginal value beyond schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and lists example queries. It distinguishes from siblings by emphasizing preference over chaining single-pack lookups and directing name-based queries to resolve_entity.

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 (holistic view), when not to (names not supported, use resolve_entity first), and provides alternative guidance. Also mentions limitations like patents API sunset.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful beyond the annotations. No contradiction.

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

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

Two sentences: first states purpose, second gives usage guidance. Front-loaded, no extraneous words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and pairing with related tools, making it complete.

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

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

Schema coverage is 100% with the parameter 'key' described as 'Memory key to delete'. The description adds no extra parameter meaning, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It also mentions pairing with remember and recall, distinguishing it from sibling tools.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also implies alternatives by suggesting pairing with remember and recall.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts title/description/key links, and emits standard markdown format, confirming the non-mutating behavior and providing specific steps.

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 long, front-loaded with the main action and purpose. It is succinct without missing essential details, though the bulleted use cases could be integrated more compactly.

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

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

For a simple tool with 2 parameters and no output schema, the description adequately explains the process and output format. Minor gaps like error handling or rate limits are not critical given the low complexity and annotation coverage.

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

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

Schema description coverage is 100%, with both 'url' and 'max_links' clearly described. The description does not add new meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the target users (AI crawlers) and the output format, distinguishing it from sibling tools like 'ai_visibility_check' and 'scan_competitor_ai_presence', which serve different functions.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting llms.txt for a project, or auditing competitor AI indexing. While it doesn't provide explicit when-not-to-use or alternatives, the use cases are clear and no sibling tool directly overlaps.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds return field details but no additional behavioral traits 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 clear, front-loaded sentences with no extraneous information.

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

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

Given simple schema and annotations, covers purpose, return fields, and usage context adequately. No output schema required.

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, so description does not need to add detail. No extra meaning provided.

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 lists the caller's active subscriptions and specifies return fields. However, it does not explicitly distinguish from sibling list tools like `watchlists` or `subscribe`.

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 when to use: before adding more subscriptions or to find an id for cancellation. Could be improved by mentioning when not to use, but 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 provide false hints, so the description carries the full burden. It adds rich behavioral context: claim_token mechanism for follow-ups, rate limit of 5 per day, no tool-call quota impact, daily digest reading, and roadmap influence. This goes well beyond what annotations convey and gives the agent a clear picture of consequences.

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 each sentence earns its place: purpose, use cases, exclusions, claim_token flow, rate limit, and cost. It could be slightly more scannable with bullet points, but it's appropriately sized for the tool's complexity and avoids 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 tool with 4 parameters (one enum, one nested object) and no output schema, the description fully covers usage context, return behavior via claim_token, constraints, and exclusions. It leaves no significant ambiguity about when or how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra nuance beyond schema, such as the claim_token round-trip usage pattern, the instruction to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts, and clarifies that the type enum maps to specific conditions. It doesn't fully detail every parameter, but meaningfully supplements 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 states a specific verb ('Tell the Pipeworx team') and an explicit resource (feedback about Pipeworx tools). It clearly distinguishes itself from sibling tools by scoping to 'tools served by this Pipeworx connection' and enumerating feedback types (bug, feature, data_gap, praise).

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 (bug, feature, data_gap, praise) and when not to use (feedback about other MCP servers), with a direct alternative ('file it with that server instead'). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but description adds valuable operational context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). 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?

Description is well-structured: front-loaded main purpose, then bullet use cases, then notes on data source and caching. Every sentence adds value; 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 simple tool with one parameter and no output schema, description covers purpose, when to use, parameter semantics, data source, privacy, and caching. Agent has enough context to decide and invoke correctly.

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

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

Only one parameter 'window' with 100% schema coverage. Description adds meaning beyond enum values by explaining trade-offs: shorter windows for hot trends, longer for steady-state demand. This helps agent choose appropriately.

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 returns trending data from AI agents: top tools, top packs, and call volume over a window. Distinguishes from sibling tools like 'discover_tools' and 'trending_symbols' by specifying it's agent-driven call data, not user-driven trends.

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 three explicit use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent demand. This gives clear when-to-use context and helps differentiate from other discovery tools in the sibling list.

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, non-destructive. Description adds rich behavioral context: semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs), fill check against live CLOB depth, and structure of responses. 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 bold headings and clear sections. While verbose, each sentence adds essential information. The front-loaded purpose and mode overview make it easy to parse.

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

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

Despite no output schema, the description thoroughly describes response fields (opportunities[], gap_pp, suggested_trade, etc.), partition_check details, and fill check behavior. It covers all aspects needed for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for event and topic. The description adds value by providing concrete examples of slugs and seed questions, explaining that full URLs are accepted, and detailing the behavior for each parameter mode. This exceeds 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 tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from siblings like polymarket_edges and 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?

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'pass topic for a themed cross-event scan'. Also advises when not to trade based on fill check results and references polymarket_fill_risk for custom sizing.

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, destructiveHint) are consistent and description adds extensive behavioral details: caching at KV level keyed on knobs, response structure with diagnostics, Fed bets exclusion, and explanation of edge calculation. 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 lengthy but efficiently packed with essential information. Front-loaded with purpose, then systematically covers model families, response structure, knobs, and caching. Each sentence adds value, though some minor restructuring could improve 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?

No output schema, so description fully covers return values: by_segment with three segments, fed_candidates/fed_note, and _diagnostics for empty segments. Explains edge fields and caching behavior. Complete 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 descriptions for all 9 parameters. The tool description adds value by explaining the rationale behind certain knobs (e.g., min_partition_leg_kelly vs min_kelly) and providing context like slippage guidance and typical spread. Complements schema 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?

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using specific model families. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by detailing its unique segmentation and 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 built for 'what should I bet on today' and guides on when to use the tool. Provides details on tradeable-edge knobs (min_liquidity, max_spread_pp) to adjust for realizability. Could be more explicit about when not to use alternatives, but context is clear.

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

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

The description goes beyond annotations by detailing limitations (60-day TTL, dependency on snapshot runs), explainations of data gaps, and how decay numbers are computed (daily closes, not intraday). This adds significant behavioral transparency that annotations alone (readOnlyHint, idempotentHint) do not cover.

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 separate sections for arguments, response, and limits, making it easy to parse. However, it is somewhat verbose; it could be slightly more concise without losing essential details.

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

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

Given the lack of an output schema, the description comprehensively explains the response structure (tracked, expired, snapshot_dates) with clear definitions of each field. It covers all necessary context for a tool with two optional parameters and no nested objects.

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 meaning to the parameters by specifying defaults (days=14, window='1wk'), valid ranges (days max 30), and the role of window as a snapshot family. This complements the 100% schema coverage effectively.

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 provides 'edge persistence and decay telemetry' from daily snapshots, addressing the question of how long an edge has existed and if it's shrinking. It clearly differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical edge 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 provides context on when to use the tool by explaining that a fresh wide edge differs from an old one, implying it should be used for assessing edge longevity. However, it does not explicitly state when not to use it or compare directly with siblings, though 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?

Annotations declare readOnlyHint, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: walking the order book ladder, returning specific metrics (top_of_book, vwap_fill_price, slippage, etc.), and disclosing the risk of forced directional risk in basket mode. 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 detailed and well-structured with bold headers for single-market and basket modes. It is slightly verbose but every sentence adds critical information. It could be shortened slightly without loss, but it remains effective.

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

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

Despite lacking an output schema, the description fully enumerates return fields for both modes (e.g., top_of_book, profit_usd, thin_legs, forced_directional_risk). It covers the tool's complexity, including edge cases like partial fills and unhedged positions, 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?

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the dual modes (market vs event), default behaviors (like auto side detection for baskets), and interpretation of size_usd (settlement notional for baskets). This goes beyond the schema definitions.

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

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

The description explicitly states it is a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between two modes (single-market and basket). It differentiates from siblings like polymarket_arbitrage and polymarket_edges by advising use before acting on their signals, clearly specifying the tool's purpose and scope.

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 guidance on when to use the tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns of risks like partial basket fills causing unhedged directional positions. While it does not exhaustively list when not to use, the context is sufficient for an agent to decide.

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

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

Annotations (readOnlyHint, idempotentHint) are complemented by detailed safety fields: compatibility_warning explains two causes, temporal_alignment clarifies when spreads are meaningless, and skipped_cross_type/subtype counters expose dropped comparisons. No contradiction with annotations.

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

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

Description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with core function. Every sentence adds value, though slightly verbose.

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

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

Given no output schema, the description explains response structure (leg-by-leg prices, top_spreads_pp, safety fields) and covers edge cases via compatibility_warning. Parameter count is low and all are documented. Completely covers an agent's needs to understand behavior and limits.

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

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

Schema coverage is 100% with descriptions for each parameter. Description adds value by explaining how topic auto-maps to events on each venue and how explicit tickers override, plus enumerates all topic shortcuts. A small bonus for explaining behavior beyond schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb 'compute spread' and resource 'cross-venue bet pricing'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by focusing on two-venue comparison and outputting spread percentages.

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 documents two modes (topic shortcuts vs explicit tickers), provides a list of valid topic shortcuts, and warns that most pre-mapped topics return compatibility warnings and are not tradeable. This tells the agent when not to rely on the output.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)'. No contradictions.

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

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

Three sentences, front-loaded with main behavior, no redundant 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?

Complete for a simple retrieval tool with 1 optional parameter and annotations covering safety. No output schema needed for clarity.

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 100% for single optional parameter. Description adds semantic value: 'omit the key argument' to list all keys, which is not in schema description.

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

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

Specific verb 'retrieve' and resource 'value' with clear distinction: 'Retrieve a value previously saved via remember, or list all saved keys'. Differentiates from sibling tools 'remember' and 'forget'.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier ... without re-deriving it from scratch'. Mentions pairing with remember and forget, but lacks explicit when-not 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 as true/true/true/false. The description adds that mark_read:true flags events as read so next call shows only newer ones, a behavioral side-effect. It doesn't contradict annotations or introduce negative traits.

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

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

The description is four sentences, front-loaded with purpose and key details. Every sentence adds value: purpose, return fields, filtering, mark_read behavior, and alternative endpoint. 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 is read-only with no output schema, the description sufficiently explains return values and mark_read effect. It also addresses polling suitability and provides an alternative REST endpoint, covering practical usage concerns.

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

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

Schema covers all 5 parameters (100% coverage). The description adds examples (type 'sec_8k', ISO timestamp for since) and explains mark_read effect, enhancing understanding beyond the raw schema descriptions.

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

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

The description clearly states the tool pulls fired events from subscription feed, specifying return fields (source, citation_uri, payload). It is specific about resource and action, but does not explicitly distinguish from siblings like `list_subscriptions` or `subscribe`, leaving some ambiguity.

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

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

The description explains how to use the tool: filter by type and/or since, set mark_read. It mentions an alternative REST endpoint for scripts/dashboards and states polls work fine, providing context. However, it does not explicitly state when not to use this tool versus 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?

Description adds behavioral details beyond annotations: parallel fan-out to SEC, GDELT/GNews, USPTO with fallback logic, soft-fail for USPTO, and return structure (changes[] grouped by source + total_changes + citation URIs). No contradiction with annotations.

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

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

Single paragraph with front-loaded examples and clear technical details. Every sentence adds value; 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 no output schema, description succinctly explains return format. Covers multiple sources, fallback, relative date handling, and alternative tool. Complete for a complex multi-source 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 covers 100% of parameters. Description adds valuable context: examples for 'since' (ISO date and relative shorthand), and clarifies 'value' can be ticker or CIK, and 'type' is currently limited to 'company'.

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 explicitly states it's a 'change feed for a company' with specific examples ('What's new with X', 'latest on Y'). Clearly distinguishes from sibling tool entity_profile ('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?

Provides explicit usage scenarios (e.g., 'updates on Acme') and explicitly tells when to use entity_profile instead. Also explains fallback behavior for news sources.

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: scoped by identifier, 24-hour retention for anonymous sessions. Annotations indicate idempotent and non-destructive, which description aligns with.

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 main purpose, then usage guidance, then technical detail. 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?

Covers purpose, usage, parameter semantics, and pairing with recall/forget. Minor gap: no mention of return value or confirmation behavior, but schema and annotations suffice.

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

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

Schema has 100% coverage with descriptions for key and value. Description enhances by suggesting naming conventions and content types (findings, addresses, preferences).

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 uses specific verb 'save' and resource 'data' with clear scope 'to reuse later'. It distinguishes from sibling tools by explicitly naming recall and forget.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides examples and notes persistence differences for authenticated vs anonymous users.

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, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds valuable behaviors beyond those: it explains the cross-source identity spine, labels identifiers with their source, explicitly lists unresolved identifiers, states graceful degradation when GLEIF/OpenFIGI are unavailable, and mentions internal cascading lookups. This context helps set expectations 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 longer than typical, but it is well-structured: opening examples, then a clear usage directive, then detailed supported types and fallback behavior. Every sentence contributes meaningful information, and the length is justified by the tool's complexity. It is not repetitive, though tighter phrasing could make it 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?

Given the tool's complexity, the description covers all essential aspects: what it does, when to use it, input types for each entity, the output format (canonical identifiers with sources, unresolved list), and failure behavior (graceful degradation). It fills the gap left by the absent output schema by describing return values in sufficient detail.

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

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

Schema coverage is 100%: both 'type' and 'value' have detailed descriptions. The description largely repeats the schema's parameter semantics, adding examples but no new parameter-level meaning. For instance, the schema already says company value can be ticker, CIK, or name; the description restates it. Thus, it meets the baseline of 3 but does not elevate beyond it.

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

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

The description opens with concrete user queries and states the tool's core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the resources (CIK, LEI, FIGI, RxCUI) and distinguishes itself from siblings by instructing to 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly tells when to use the tool ('Use FIRST whenever you have a name but need an ID') and further clarifies the input types per entity category. It does not explicitly mention alternatives or when-not-to-use, but the context makes the primary use case 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?

The description fully discloses behavior beyond annotations: it probes each entity with ai_visibility_check, ranks by score, identifies most/least recognized, and returns a ranked list with score, confidence, signal density. It also mentions the optional Anthropic API key for certain models. Annotations already note read-only and idempotent, and the description adds valuable workflow details without contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, then process, then use case. Every sentence adds value, no wasted words. Structure is logical and easy to parse.

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

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

Given the tool's complexity (orchestrating multiple probes, optional models/API key, entity constraints) and the lack of output schema, the description covers everything needed: purpose, process, input constraints (2-8 entities), authentication, and return fields (score, confidence, signal density). 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 is 3. The description adds meaningful context: the first entity is treated as the 'subject' for narrative, and the tool accepts 2-8 entities. This goes beyond the schema descriptions, which are more generic. Additional details like the default model and API key dependency are already in the schema, so not redundant.

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: to compare AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking results. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (other dimensions) by specifying the side-by-side comparison with ranking.

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 a clear use case (competitive AI-marketing audits) with an example question. It implies when to use it (for multiple entities) but does not explicitly mention when not to use it or name alternatives. The sibling list and context make the guidance clear, but explicit exclusions would elevate it further.

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

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

Annotations already declare readOnly=true, idempotent, openWorld, and not destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed lists timeouts, and rest still returns. 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 dense but well-structured: purpose first, then usage context, then behavior (including edge cases), then output summary, then limitations. Every sentence provides value; no redundancy.

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

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

With complete schema (100% coverage), clear annotations, and a description that lists all output fields (is_latest, license, bundle sizes, etc.), the tool is fully specified for an agent to use without ambiguity. No missing information despite lacking 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% and already explains both parameters (package name with scoped acceptance, version defaulting to latest). Description adds no additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly defines a composite 'should-I-add-this-package' check combining deps.dev and bundlephobia. It uses specific verbs like 'scan' and 'check', and distinguishes from siblings by restricting to npm ecosystem and noting alternatives for other ecosystems.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies NPM-only in v1 and points to deps.dev:version for other ecosystems, 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This goes well beyond annotations and provides full 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 a single short paragraph with three sentences. It front-loads the purpose, provides usage guidance, and details behavior without any wasted 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?

Despite no output schema, the description explains the output: 'top-N passages with character offsets and similarity scores.' It also covers embedding model, windowing, and character limits. For a tool with three parameters, this is very 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 description coverage is 100% with good descriptions for each parameter. The description reinforces these by explaining output format (passages with offsets and similarity scores) and providing query examples. This adds substantial 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?

Clearly states 'Semantic search INSIDE a fetched record' and distinguishes from sibling ask_pipeworx_grounded by noting that search_within is for searching within a record, while the other grounds over passages. The verb 'search' and resource 'inside a fetched record' are specific and unambiguous.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a pairing strategy with ask_pipeworx_grounded: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear context and alternatives.

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

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

Beyond annotations, the description adds behavioral details such as the requirement for an OAuth account, delivery channel constraints (SMS 10/day cap), and webhook signing. 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 moderately long but well-structured, with the most important information front-loaded. Each sentence contributes value, 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?

Given the complexity of multiple subscription types, delivery options, and constraints, the description covers all necessary aspects, including prerequisites, type-specific params, and return value.

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

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

Schema coverage is 100%, but the description significantly adds meaning with detailed examples for each subscription type, param structure, and delivery channel behavior, going well beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This uses a specific verb (Create) and resource (subscription), and distinguishes it from sibling tools like list_subscriptions 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?

The description provides context on when to use the tool, including requirements (Pipeworx OAuth account) and supported types. It does not explicitly contrast with siblings, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read behavior. The description adds context about the editorial curation nature and the returned fields (tickers, names, watch counts), which goes beyond the annotations. No contradiction.

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

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

The description is concise, using three focused sentences to state the source, distinguish from sibling, specify output, and provide usage guidance. No redundant or vague language.

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

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

Given the simple single-parameter schema and rich annotations, the description covers the core purpose and output. However, it omits explanation of the 'limit' parameter, which slightly reduces completeness. Still, it provides sufficient context for typical 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 0%, so the description must compensate. However, the description does not mention the 'limit' parameter at all, nor its purpose or default behavior. This is a significant gap for a tool that expects a numeric input.

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

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

The description clearly identifies the tool as providing editorially curated trending equities, distinguishing it from the sibling tool 'trending_symbols' which uses raw-volume algorithmic ranking. It specifies the resource (StockTwits editorial picks) and actions (returns tickers, names, watch counts).

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: 'Use when you want editorial picks rather than algorithmic social-volume rank.' This provides clear guidance on choosing this tool over alternatives like trending_symbols.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds rich context: returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog. No contradictions.

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

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

The description is informative but somewhat lengthy (multiple clauses and lists). Front-loading is good, but could be more concise by trimming repetitive examples. Adequate 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?

With only one optional parameter and no output schema, the description covers purpose, usage, output structure, and context. It fully enables correct invocation and understanding.

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

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

Schema coverage is 100% with one optional parameter. The description adds meaning by listing example focus areas and explaining the behavior when omitted vs. specified, going 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?

The description specifies the verb ('suggest' / 'show examples') and the resource (example questions categorized by domain). It clearly states it is the onboarding entry point and distinguishes itself from siblings by being the first tool to use when unsure what to ask.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Provides guidance on passing a topic vs. omitting it. Lacks explicit when-not-to-use, but the use case is well-defined.

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 domain-specific context (StockTwits) and purpose but does not disclose additional behavioral traits such as rate limits, pagination, or 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?

The description is a single concise sentence with embedded examples, front-loading the key action. No extraneous information.

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

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

Given the simplicity (2 params, no output schema), the description covers the primary use case but lacks details on return values and does not distinguish it from similar sibling tools like suggest_symbols.

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

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

With 0% schema description coverage, the description must compensate. It implies 'q' is a company name or search term via examples and mentions variant tickers, but does not explain 'limit' or provide any parameter constraints or formatting 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's purpose: searching for StockTwits symbols to confirm existence or find variants. It uses specific verbs ('Look up', 'search') and resources ('StockTwits ticker', 'symbol on StockTwits'), making it unambiguous.

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

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

The description provides example queries but no explicit guidance on when to use this tool versus siblings like suggest_symbols or search_within. Users are left to infer context from the examples alone.

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 that it returns user posts with sentiment tags, timestamps, like counts, which is useful context. However, no mention of rate limits, auth needs, or edge cases 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?

Description is front-loaded with natural language queries, but has some repetition and could be more concise. Still, it communicates the tool's value efficiently.

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 5 parameters, no output schema, and annotations present, the description covers the return data but lacks parameter details. It is adequate but not comprehensive.

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 0%. Description implies 'symbol' (ticker) and 'filter' (bullish/bearish) through examples, but 'max', 'limit', 'since' are not explained. Only one of five parameters is clarified, leaving significant 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 returns StockTwits messages mentioning a ticker, with sentiment tags, timestamps, like counts. It is distinctive from siblings like 'trending_messages' or 'symbol_search', but does not explicitly differentiate.

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 natural language example queries and explicit guidance: 'Use for retail-investor sentiment, social-volume tracking, contrarian signal.' No when-not or alternatives mentioned, but usage context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and consistency. The description adds that it returns 'most engaged-with messages across all StockTwits streams', which provides additional context but does not disclose any 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?

The description is very concise, consisting of two quotes and one clear sentence. It is front-loaded with the core purpose. No extraneous content. The structure is slightly informal due to quotes, but every element serves a purpose.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides sufficient context: it explains the tool's return (trending messages) and its use case (market zeitgeist). The description does not need to detail output since it's a straightforward list. However, it could have briefly noted the lack of filtering options.

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 only parameter is 'limit' (optional number), with 0% schema description coverage. The tool description does not mention or explain the limit parameter at all, leaving the agent to infer its purpose from the name alone. Given the low coverage, the description should have clarified what limit controls (e.g., max number of results).

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 defines the tool as returning most popular/trending messages on StockTwits, using phrases like 'most popular posts' and 'most-engaged-with messages across all StockTwits streams'. It distinguishes from sibling tools like trending_symbols or symbol_stream by focusing on messages rather than symbols or streams.

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 says 'Use for general market-zeitgeist sense-making', which gives a clear usage context. However, it does not explicitly state when not to use this tool or mention alternatives among siblings (e.g., pipeworx_trending, trending_symbols). The guidance is implicit but lacks explicit comparisons.

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 convey readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable context: data source (StockTwits), metric (message volume), and temporal aspect (right now), enhancing transparency beyond the annotations.

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

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

The description is extremely concise, consisting of two lines with no superfluous information. Every phrase adds value, and the format is clear and 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?

The tool has one optional parameter with no output schema. The description explains the core functionality well but omits details on the return format (e.g., fields in the response) and the behavior of the 'limit' parameter. Adequate for a simple tool but not complete.

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

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

The input schema has 0% description coverage for the 'limit' parameter. The description does not mention the parameter at all, leaving its purpose and default behavior completely unspecified. This is a significant gap.

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

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

The description clearly states the tool returns 'top trending tickers on StockTwits by message volume right now', with explicit verb and resource. It includes alternative phrasings and use cases, distinguishing it from siblings like 'pipeworx_trending' which is from a different source.

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

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

The description provides explicit use cases: 'retail-attention scans, meme-stock detection, social-momentum trading'. While it doesn't state when not to use or name alternatives, the context is sufficient for an agent to determine applicability.

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 ownership enforcement and deactivation behavior, adding value beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). 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, 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 single-parameter tool with full schema coverage and clear behavioral description; 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% and parameter description is sufficient. Description does not add extra semantics 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?

Description clearly states 'Cancel a subscription by id,' with a specific verb and resource. Distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

States ownership enforcement and that cancellation deactivates rather than deletes, providing context. Does not explicitly contrast with alternatives but implies usage scope.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying that the tool returns messages with sentiment tags, timestamps, and ticker cashtags, and that it supports since/max cursor pagination and a limit cap, which goes beyond the annotation hints.

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

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

The description is two sentences long, front-loads the core purpose, and provides necessary details (pagination, return fields) without any fluff. 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 no output schema, the description adequately describes return content (sentiment tags, timestamps, cashtags) and pagination. It covers the single required parameter and optional pagination parameters. Could briefly mention that results are ordered but is otherwise 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 0%, so the description carries the burden. It explains that user_id identifies the user, and since/max/limit relate to pagination and capping. However, it does not explicitly define 'since' and 'max' as cursors or describe their exact semantics, leaving some ambiguity.

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 recent StockTwits posts from a specific user by user_id, distinguishing it from sibling tools like symbol_stream (which likely filters by symbol) and trending_messages (which likely retrieves trending posts).

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 says 'Use to follow a particular trader's commentary stream,' providing clear context for when to use this tool. However, it does not explicitly mention when not to use it or name alternatives, though the sibling list suggests related 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the two execution paths (SEC EDGAR fast path vs. grounded pipeline), the exact verdict vocabulary, and crucial caveats about could_not_verify vs unsupported, which prevents the agent from misinterpreting failure as evidence.

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 efficiently front-loaded with trigger phrases and organized into purpose, routing, return value, and caveats. Every sentence provides distinct information, though it could be slightly condensed without loss.

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 an output schema, the description fully specifies the return value (verdict list, actual value, citation, reasoning) and edge cases, making it complete for the agent to use.

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

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

Schema coverage is 100% for both parameters, and the description does not add significant new parameter semantics beyond what the schema already provides (e.g., tolerance_pct is fully documented in the schema). Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with trigger phrases and a specific use case ('fact check', 'verify the claim'). It distinguishes itself from generic Q&A tools by focusing on verifying factual claims and outlining two concrete pipelines.

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' and differentiates company-financial claims from other factual claims, including how the system routes them. It also explains the outcome semantics, helping the agent decide when to trust results.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature, so the agent knows it's safe. The description adds pagination support (since/max cursor) and a limit cap, which are useful but does not discuss edge cases like missing watchlist or rate limits.

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

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

The description is two efficient sentences, front-loaded with the core purpose and followed by key features. No redundant information; every sentence adds value.

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

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

Given no output schema, the description does not mention the return format (e.g., list of messages with fields). While annotations provide safety context, the lack of output details leaves the agent guessing about the data shape, which is a moderate gap.

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

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

Schema has 0% description coverage, but the description explains that 'since' and 'max' are for cursor pagination and 'limit' is a cap, providing meaning for these parameters. However, it does not detail each parameter's format or behavior, leaving some ambiguity.

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 fetches recent StockTwits messages for a specific watchlist, using a verb 'track' and specifying the resource 'messages for all tickers in a watchlist'. It distinguishes from sibling tools like 'symbol_stream' by emphasizing aggregation across multiple symbols in one call.

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 suggests using it to 'track social chatter across a curated list of symbols', providing a usage context. However, it does not explicitly mention when not to use it or compare with alternatives like 'symbol_stream' or 'trending_messages', leaving some guidance gaps.

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, destructiveHint, and idempotentHint. Description adds return fields but no additional behavioral context beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with purpose, no wasted words. 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?

Tool is simple with one parameter and no output schema; description explains return fields and use case, making it fully complete 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?

Only one parameter 'user_id' is mentioned in description without format details. Schema coverage is 0%, but description adds minimal value, only stating it is used as input.

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 lists public watchlists by user_id, specifying verb, resource, and parameter. Distinguishes from sibling 'watchlist' tool by mentioning subsequent use of watchlist_id.

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

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

Provides explicit use case: discover a trader's followed symbols, then use watchlist tool. Suggests alternative path but lacks explicit when-not usage.

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