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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals orchestration behavior: route to thousands of tools, fill arguments, and return structured answers with stable citations. It sets expectations that this is a starting point for most factual questions. 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 front-loaded and every sentence adds useful guidance, from scope to examples to the live-news caveat. It is slightly longer than strictly necessary due to the enumerated knowledge domains and repeated trigger phrases, but remains well-structured and readable.

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 still specifies the return shape: a structured answer with stable pipeworx:// citation URIs. It covers when to use, scope, examples, and an exception, which is complete for a one-parameter meta-router. The agent has everything needed to select and call 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 descriptions already cover all six parameters (question plus five aliases) at 100% coverage, so the description adds little semantic detail. The examples illustrate valid question values but do not define parameter constraints beyond natural language. 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 names a concrete action: routes a question to one of 5,743 tools across 1,500 verified sources, fills arguments, and returns a structured answer with pipeworx:// citation URIs. It distinguishes the tool from generic web search with 'PREFER OVER WEB SEARCH' and gives a broad but concrete scope. The purpose is unmistakable even without opening the schema.

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

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

Explicitly tells when to prefer this tool ('PREFER OVER WEB SEARCH'), lists trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), and provides concrete examples. It also addresses the live-news exception by noting ask_pipeworx already routes to live news and news-feeds packs. This is actionable, not implied.

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

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

Even though annotations already indicate read-only, idempotent, open-world behavior, the description adds valuable context: candidate routing may be active or not, the last candidate was retired, there is no fallback, and this is a fully working router rather than a stubbed beta. This prevents incorrect assumptions about reliability or availability.

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 essential beta/identical relationship and every sentence contributes important context: current state, usage, comparison to stable, and no-fallback behavior. It is slightly verbose with the parenthetical enumeration, but not padded.

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

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

For a complex universal router with no output schema, the description compensates by pointing to ask_pipeworx's response shape and documenting the experimental state, current behavior, and fallback expectations. It could be more self-contained by describing the response format directly, but the sibling reference is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents the required question parameter and all aliases. The description only restates that arguments are identical to ask_pipeworx and adds no extra semantic detail, so the 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 explicitly frames the tool as a beta version of ask_pipeworx, identifies it as an identical universal router with the same 5,743 tools, same arguments, and same response shape, and distinguishes it from the stable ask_pipeworx by the experimental routing candidate behavior. This gives an agent a clear sense of what the tool is and how it differs from 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 gives an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the stable router as the comparison point and clarifies the current no-candidate state, so an agent knows the tool currently behaves identically to ask_pipeworx. This is strong practical guidance.

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

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

The description discloses the exact success response shape, the full refusal_reason enum, and the grounded-extraction behavior, all beyond what the annotations provide. It also notes the extra LLM call cost and that refusals occur when data doesn't directly answer. This does not contradict the readOnly, idempotent, or non-destructive 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 information-dense and front-loaded, leading with the core purpose and then the critical behavioral contract. Every sentence contributes: routing explanation, response shape, refusal conditions, use cases, and cost tradeoff. There is no filler or repetition.

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

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

With no output schema, the description supplies the full return contract including evidence, confidence, source, and refusal reasons. Annotations cover the safety profile, the schema covers the input parameter, and the description covers usage and behavior, leaving no material gap for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, with the question parameter fully documented and aliases enumerated. The description adds context about the question being routed and grounded, but no additional parameter-level semantics are necessary given the schema already covers them.

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 this is a hallucination-resistant answer mode for high-stakes reads and explains that it extracts answers only from what the tool result contains. It explicitly contrasts itself with ask_pipeworx, distinguishing this grounded mode from the standard routing variant despite similar names.

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

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

It gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples like financial, legal, medical, or public-statement contexts. It also names the alternative and preference rule: prefer ask_pipeworx for casual lookups because this mode costs one extra LLM call.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavior: it decomposes questions, routes to 5,743 tools in parallel, returns a findings packet with verbatim evidence/confidence/source/fetched_at/citations, uses explicit gaps[] and never invents answers, performs gap-recovery hops, detects contradictions, and semantically excerpts long records. Latency expectations (15-60s, up to ~90s) are also provided. This is far richer than what annotations alone convey.

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

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

The description is long but densely packed with essential operational facts: auth, pricing, alternatives, taxonomy of depths, output format, citation reliability, contradiction handling, and latency. It is front-loaded with the account requirement. Some repetition exists (paid plan for thorough appears both at the start and in the depth explanation), so it isn't maximally concise, but the complexity of the tool justifies most of the length.

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

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

There is no output schema, and the description fully compensates by explaining the return format: findings packet, per-finding fields, gaps[], contradictions[], hop field, and citation_uri conditions. It also covers authentication, plan tiers, sibling fallback routes, and timing expectations. For a complex research tool with only two parameters, the description leaves no critical gap in an agent's ability to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful value on top of the schema. It elaborates depth semantics (quick=3 facets, standard adds gap-recovery + contradictions, thorough adds iterative lead-chasing), notes the paid requirement for thorough, and gives examples of appropriate questions. This goes beyond simply restating the enum 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 identifies the tool as 'grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in 'ONE call', which is a specific verb, resource, and scope. It distinguishes itself from ask_pipeworx and open-web search, and includes concrete example questions. This makes the tool's purpose unmistakable even among many 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 gives explicit guidance on when to use this tool versus ask_pipeworx: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx'. It also specifically excludes breaking/current-news topics, noting that deep_research 'returns mostly empty gaps[]' in those cases while ask_pipeworx routes to live news APIs. Account and paid-tier requirements are stated up front, covering prerequisites as well.

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?

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations. It discloses important behavioral nuances: 'an empty section is a real "no data", not a bug', 'a private company ... returns resolved:false with an explicit notes line, not a bare failure', and 'sources_used / sources_failed say which of these actually returned data for THIS company'. It also reveals fallback behavior (GDELT→GNews), resolved_from/resolved_to mechanics, and expected empty results for small-molecule-only companies. This is rich behavioral transparency.

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

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

The description is long but every sentence carries substantive information, from usage examples to source enumeration to edge-case behavior. It is front-loaded with purpose and the key 'ALWAYS PREFER' directive. However, it is structured as one dense run-on paragraph with heavy semicolon use, which harms scannability. Given the tool's complexity, the length is justified, but clearer formatting would make it a 5.

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

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

With no output schema, the description has to explain return values, and it does so thoroughly: cik, company_name, recent_filings with URIs, fundamentals, patents, federal contracts, FDA products, hiring, news, LEI, and sources_used/sources_failed. It also covers important failure modes (private company, invalid ticker, empty sections) and input variations. For a complex tool with 2 parameters and many data sources, this description leaves no major gap an agent would need filled to call it correctly.

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

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

Schema description coverage is 100% — both `type` and `value` are already thoroughly described in the schema with examples and resolution rules. The description largely restates the same parameter semantics ('Pass a ticker, zero-padded CIK, or a company name', 'type accepts company or ticker interchangeably') without adding new input-level meaning beyond the schema. Baseline 3 is appropriate because the schema already carries the full parameter documentation burden.

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

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

The description opens with concrete example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') and then states the core purpose: 'full cross-source profile of a US public company in ONE parallel call'. This clearly identifies the verb, resource, and scope. It also distinguishes from sibling tools by explicitly contrasting with 'chaining single-pack SEC/XBRL/news lookups', so an agent knows this is the holistic profile tool.

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

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

The description gives a strong directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This provides clear context for when to use the tool and names the alternative pattern to avoid. However, it does not explicitly say when NOT to use this tool (e.g., for a simple fact lookup) or name other sibling tools like compare_entities or resolve_entity as alternatives, leaving some exclusion boundaries implied rather than explicit.

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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing safety. The description adds substantial behavioral detail beyond that: the token-overlap matching logic, the exact meaning of each compatibility code (e.g., temporal_alignment_unknown is NOT the same as confirmed-aligned), the policy that unclassified legs are never paired, the fee disclaimer (gross vs. net), and the handling of skipped comparisons. This significantly exceeds the annotation baseline.

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

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

The description is long but well-structured: it begins with the core purpose, then covers modes, response fields, safety fields, codes, and non-obvious caveats. It uses bold labels and code formatting effectively. While every sentence packs useful information, the length is near the edge of what is concise; some redundancy exists (e.g., restating that compatibility_codes is machine-readable). Still, it earns a high score for front-loading and organization.

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?

There is no output schema, so the description carries the full burden of explaining the response shape. It does this thoroughly: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning/codes, fees_note, skipped counters, temporal_alignment, and low_confidence_pairs. It also covers edge cases like null temporal_alignment and the meaning of 'unknown' legs. An agent has everything needed to call the tool and interpret results correctly.

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

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

Schema coverage is 100% and each parameter has a description, but the tool description enriches semantics further: it explains the topic list as pre-mapped shortcuts that auto-fetch the matching event on each venue, clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and specifies the exact behavior of BOTH modes using the same matcher. This adds context beyond the raw schema.

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

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

The description opens with a precise purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further distinguishes the two operating modes (topic shortcuts vs. explicit pairings) and describes the matcher and output. This separates it from siblings such as polymarket_arbitrage and polymarket_edges, which focus on different cross-venue calculations.

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

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

The description explains when to use each mode (pre-mapped topic vs. explicit ticker/slug) and provides crucial usage warnings: most pre-mapped topics currently return compatibility_warning, and 'pre-mapped ≠ tradeable.' It also instructs agents to read safety fields 'even when matched_pairs>0.' However, it does not explicitly contrast with sibling tools or state when NOT to use this tool in favor of a sibling, so a perfect score is not warranted.

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?

Beyond the annotations, it discloses multi-endpoint cascading, graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguity handling via figi_candidates, source labelling of identifiers, and explicit unresolved output. This adds substantial behavioral context and does not contradict the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The description is dense and mostly front-loaded, but it is also overlong and repetitive, re-listing input types already described in the schema. Long parenthetical chains and lack of structured headings make it harder to scan, even though most of the detail is valuable.

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

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

With no output schema, the description compensates by specifying return values for both types: CIK/ticker/company_name, LEI with parent/ultimate-parent/children, FIGI, and RxCUI/ingredient/brand/citation. It also covers unresolved and ambiguous cases, so an agent has enough to call and interpret 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 already high at 100%, but the description adds significant meaning: accepted ticker/CIK/ISIN/name formats, an example ISIN-to-LEI mapping, and the critical warning to pass only the entity name, not the full noun phrase for bonds. This goes well 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 states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It then enumerates the exact output identifiers for company and drug types, distinguishing it from sibling tools like symbol_search or entity_profile by making clear it is the name-to-ID resolver.

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

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

The description gives an explicit directive: 'Use FIRST whenever you have a name but need an ID,' and lists concrete trigger phrasings like "find the CIK for…" and "look up the ID for…". It provides clear context but does not explicitly name alternatives or state when not to use this tool versus a sibling lookup 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?

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.