Mastodon

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds valuable behavioral context: default model is Workers AI Llama (free), BYO key for Anthropic, and per-model return structure (score, confidence, signals, raw_response) plus combined view. No contradictions.

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

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

The description is concise and well-structured: one sentence for purpose, one for defaults and optional parameters, one for return format, and one for use cases. No redundant or 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 no output schema, the description adequately explains the return format (per-model and combined view). All 4 parameters are covered, and the use cases are clear. No additional context needed for a tool of this complexity.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds meaning beyond schema by explaining default model behavior (workers-ai used by default), when to provide `_apiKey` (if 'anthropic' in models), and the purpose of `context` (disambiguation).

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 a business/brand/product/topic and scoring visibility (0-100). It uses specific verbs ('probe', 'score') and distinguishes itself from sibling tools by focusing on multi-model AI visibility audits.

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

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

The description explains when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to use optional parameters like `_apiKey` for Anthropic probes. However, it does not explicitly state when not to use it or name alternatives among siblings, leaving some implicit guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it routes across 5,724 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and characterizes the call as "one fast call". 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 front-loaded with the most important guidance (prefer over web search, broad domain list) and then progressively covers routing, examples, and escalation. It is long, but nearly every sentence adds a distinct piece of guidance: domain coverage, mechanism, trigger phrases, examples, tier behavior, and sibling routing. A small amount of repetition (e.g., "START HERE"/"default entry point") keeps it from a perfect 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?

For a router tool with one required natural-language parameter, the description is complete: it specifies input format, domains, example queries, output shape (structured answer with citation URIs), performance characteristics, and precisely when to escalate to grounded/deep-research siblings. No output schema exists, so the description's return-format disclosure is essential and sufficient.

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

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

Schema coverage is 100% and the schema already documents all six aliases and the natural-language question format. The description adds useful examples of concrete question values ("current US unemployment rate", "Apple's latest 10-K") and a list of trigger phrases that help an agent populate the question parameter correctly. This goes beyond the schema 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 a specific verb and resource: it "Routes the question to the right one of 5,724 tools across 1497 verified sources" and returns a structured answer. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, and from web search by being explicitly preferred. This is a specific, differentiated purpose statement.

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

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

The description gives explicit when-to-use guidance: "PREFER OVER WEB SEARCH", "START HERE for most questions", and lists trigger phrases such as "what is", "look up", "find", "get the latest". It also gives explicit when-to-step-up instructions, naming ask_pipeworx_grounded for verbatim-evidence answers and deep_research for broad/multi-part questions. This fully routes an agent away from alternatives.

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

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

The description goes beyond the readOnly/idempotent annotations by disclosing the live experimental behavior: candidate routing improvements are active whenever one is under test, no candidate is active right now, and the tool is a full working router rather than a fallback or wrapper. This gives the agent an accurate model of how invocation may differ over time.

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 front-loaded, covering identity, current state, usage, and relationship to the stable tool in a compact space. The 'falls back to nothing' sentence is slightly emphatic but earns its place by preempting a common misreading of a beta router.

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?

It is complete for an experimental variant of a known sibling tool: it specifies the shared interface, current equivalence, experimental behavior, and evaluation purpose. It does not spell out the response shape, but saying it is identical to ask_pipeworx reasonably delegates that detail to the established 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 description coverage is 100% and the schema already explains the question parameter and its aliases. The description adds only that arguments are the same as ask_pipeworx, which does not materially enrich parameter semantics beyond the structured 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 identifies the tool as a beta version of ask_pipeworx and clarifies it is a universal router exposing the same 5,724 tools, arguments, and response shape. It distinguishes the tool from its stable sibling via the experimental routing layer, though an agent with no prior knowledge of ask_pipeworx still lacks a plain-language statement of what the router actually does.

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

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

It explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains current behavior versus the stable router ('currently matches ask_pipeworx exactly') and mentions that results are compared against the stable router, which is clear directional guidance.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it describes the internal routing and extraction process, the refusal mechanism with specific reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the cost implication. While it doesn't elaborate on every aspect of the safety profile, the annotations cover those, so the description supplements rather than repeats.

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 well-organized, front-loading the core purpose before detailing the response format, usage scenarios, and cost. Every sentence contributes to decision-making. It's slightly longer than minimal but justified by the complexity of the refusal logic and tradeoff with the sibling tool.

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

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

Given the absence of an output schema, the description fully explains the return structure including success and refusal payloads, enumerates all refusal reasons, and clarifies when to use this tool versus the alternative. It also mentions the cost tradeoff, ensuring an agent has all necessary information to call it correctly in high-stakes contexts.

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 question parameter and all five aliases fully documented. The description adds minimal value: it mentions the parameter is in natural language but doesn't provide syntax or formatting rules beyond what the schema already states. This is the baseline score for full schema coverage without additional semantic depth.

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

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

The description clearly identifies this as a hallucination-resistant answer mode, distinguishing it from ask_pipeworx by emphasizing that it extracts answers only from the tool result and returns evidence. It explicitly names the sibling it derives from (ask_pipeworx) and contrasts the two, leaving no ambiguity about its specific role.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives a when-not-to-use: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff, making the selection criteria crystal 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 extensively details behavior: market resolution, classification, fan-out, evidence packet, match confidence, parent event extraction, news fallback, safety short-circuits, and resolution rules. 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 long but well-structured with clear sections and front-loaded purpose. Each part adds necessary detail for a complex tool; minor verbosity is justified.

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

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

Given no output schema and three params, the description covers all behavioral aspects: fan-out, response shapes, edge cases (low confidence, closed markets, wide spreads), and resolution risk. Completely adequate.

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

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

Schema covers all 3 parameters with descriptions. The description adds value by illustrating input formats (slug, URL, question text), depth options (quick/thorough), and include_raw trade-offs. While schema is complete, description enriches understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, specifying inputs like slug, URL, or question text. It distinguishes itself from siblings by its specialized focus on Polymarket and Pipeworx.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides examples of fan-outs and classifiers, guiding when to invoke the 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals crucial behavioral details: it performs parallel data retrieval, pulls specific financial metrics from SEC EDGAR/XBRL for companies and FAERS data for drugs, sorts results by primary metric, and returns citation URIs. It also explains handling of different fiscal year ends, which is not obvious from annotations.

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

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

The description is dense and front-loaded with trigger phrases, making it easy to scan. However, it could be slightly more structured (e.g., bullet points for different entity types). At 5 sentences it is concise but packs substantial information; minor improvement possible without losing clarity.

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

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

Given no output schema, the description explains return format (paired data + citation URIs) and sorting behavior. It covers data sources, entity types, edge cases (off-calendar fiscal years), and even quantifies efficiency gains. This provides a complete picture for an agent to use the tool correctly.

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

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

The input schema covers both parameters with descriptions, but the description adds significant context: for 'type' it explains what data each enum value pulls (latest 10-K metrics for company, FAERS for drug), and for 'values' it clarifies expected formats (tickers/CIKs for company, drug names). It also notes min/max items, which schema already covers, but the real-world meaning is enriched.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It lists trigger phrases like 'compare X and Y', 'X vs Y', 'which is bigger', and explicitly differentiates from sequential single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups'. This distinguishes it from sibling tools like 'entity_profile'.

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

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

The description provides explicit when to use: for comparing multiple companies or drugs, with specific examples like 'rank these companies'. It advises preferring this tool over sequential single-entity lookups. It also details behavior for each type (company vs. drug), including handling of off-calendar fiscal years, giving the agent clear context for correct invocation.

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

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

Annotations already mark read-only, open-world, idempotent, non-destructive. The description adds substantial beyond-annotation context: account/paid-tier requirements, latency expectations, the findings-packet shape, gap/contradiction behavior, never-invents policy, excerpting behavior, and the guarantee that citations are fetchable. 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?

Long, but appropriately dense for a complex research tool. Critical constraints (account required, sibling fallback) are front-loaded, and use cases, output behavior, and depth semantics follow logically. A few clauses are packed tightly, so it reads as slightly dense rather than perfectly 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 no output schema, the description covers the return packet (evidence, confidence, source, fetched_at, citation, gaps, contradictions, hop field), latency, auth, depth trade-offs, and routing guidance. An agent has everything needed to choose and invoke the tool correctly, including what to expect on failure-adjacent topics.

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

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

Schema coverage is 100% and already explains depth and question well, so baseline is 3. The description adds extra selection-relevant meaning: quick vs standard vs thorough behavioral outcomes, the paid threshold for thorough, and expected latency by depth, which an agent can use to pick the right setting.

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

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

States a specific verb+resource: grounded multi-source research across Pipeworx's 1497 structured data sources in one call. It explicitly marks itself as NOT open-web search and gives concrete example queries, making its scope unmistakable and clearly distinct from sibling tools like ask_pipeworx.

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

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

Gives explicit when-to-use and when-not-to-use guidance: best for broad/multi-part structured-data questions, single lookups should use ask_pipeworx, breaking/current-news topics should prefer ask_pipeworx, and unsigned-in users should use ask_pipeworx. Sibling exclusions are named directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it returns top-N most relevant tools with full schemas and curated examples, ready to call directly. No contradiction.

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

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

Description is front-loaded with purpose and usage. The list of domains is somewhat lengthy but informative. Could be slightly more concise, but overall efficient.

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

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

For a discovery tool, it fully explains what it returns (tool names, descriptions, schemas) and how to use it. No output schema but description compensates. Siblings are numerous, and description sets clear expectations.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. Description adds examples and clarifies the main parameter's purpose, but doesn't provide significant additional meaning beyond the schema.

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

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

The description clearly states it finds tools by describing the data or task, listing many domains. It distinguishes itself from sibling tools by being the initial discovery tool, which is explicit in 'Call this FIRST'.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set'. Provides context on when to use (browse, search, discover) and implies it's for exploration before other tools.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds rich behavioral context: it fans out across six sources, details return structure (cik, filings, fundamentals, patents with sunset warning, news, LEI), and notes parallel execution. This goes well beyond 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 detailed but efficient—front-loaded with examples and key usage rules. While it contains a dense block of return fields, the information is well-organized and each sentence serves a purpose. A minor reduction in length could improve conciseness, but it remains clear and structured.

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

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

Given the tool's complexity and lack of output schema, the description fully explains return values (cik, filings with URIs, fundamentals, patents with sunset info, news, LEI) and edge cases (patents soft-fail). No additional context is needed for proper 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%. The description adds significant meaning: it clarifies that 'type' only supports 'company' for now, explains why only ticker/CIK are valid for 'value' (names not supported), and recommends using resolve_entity as a preprocessing step. This provides essential guidance missing from the schema alone.

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

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

The description starts with explicit query examples (e.g., 'Tell me about X', 'research Acme') and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling tools by recommending preference over chaining single-source lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' when a holistic view is needed. It also specifies input requirements (ticker or CIK, not names) and directs users to use resolve_entity if they only have a name, providing clear usage boundaries and alternatives.

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

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

Annotations already indicate destructiveHint=true, so the description's 'Delete' aligns with that. It adds context about clearing sensitive data but doesn't go beyond the annotation significantly.

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 no wasted words. The action and resource are front-loaded, and usage guidelines follow immediately. Every sentence is necessary.

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 annotations present, the description covers purpose, usage, and relationship to siblings fully. 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% and the description of the 'key' parameter ('Memory key to delete') does not add meaning beyond the schema definition. Baseline score of 3 applies.

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

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

The description uses a specific verb+resource ('Delete a previously stored memory by key') and distinguishes itself from sibling tools 'remember' and 'recall', clearly establishing its unique 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 states when to use the tool ('context is stale, the task is done, or you want to clear sensitive data') and references sibling tools for pairing, providing clear guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context on what the tool does internally (fetches page, extracts title/description/key links) and the output format, which is valuable 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 concise: two main sentences plus a list of use cases. It is front-loaded with the core functionality and wastes no 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 good annotations and schema coverage, the description covers the key aspects: purpose, output format, and use cases. It is sufficiently complete, though the exact output format could be slightly more detailed.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add significant new semantics 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?

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It also lists specific use cases, distinguishing it from related sibling tools like 'scan_competitor_ai_presence' or 'ai_visibility_check'.

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

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

The description explicitly mentions three use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly state when not to use the tool or mention alternative tools. However, the context is clear enough 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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds what the output contains (bio, counts, etc.) but does not disclose additional 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?

A single sentence that efficiently captures the action, resource, input example, and output summary. 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?

The description is complete for a simple tool with one parameter and an existing output schema. It mentions key return fields, making it sufficient for an agent to understand the tool's purpose.

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

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

Schema coverage is 100%; the schema already includes a clear description and example for the id parameter. The description's mention of 'by ID' adds no new semantic value beyond the schema.

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

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

The description uses a specific verb 'Get' and resource 'Mastodon account profile', clearly indicating the input (ID) and output (bio, counts, post history, verification status). It distinguishes from all sibling tools, none of which are for account retrieval.

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 implicitly states when to use (need account by ID) but does not explicitly mention when not to use or alternatives. However, given the tool's simplicity and lack of similar siblings, the guidance is still clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the return format but does not disclose potential rate limits, pagination, or other behavioral traits beyond what annotations provide.

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

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

Single sentence, no wasted words. All information is front-loaded and necessary.

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 a clear output schema (implied), the description covers the essential purpose and return content. No gaps identified.

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

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

Schema coverage is 100% for the single limit parameter. The description does not add details beyond the schema, 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 specifies the action ('Get recent posts'), the resource ('public Mastodon timeline'), and the returned fields ('statuses with authors, timestamps, engagement counts, and content'). This clearly distinguishes it from sibling tools like get_trending.

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?

No guidance on when to use this tool versus alternatives (e.g., get_trending). No mention of prerequisites or when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about return values (engagement counts, authors, tags) but no behavioral traits beyond annotations. 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?

Two concise sentences with front-loaded purpose. No redundant or irrelevant content. Every word adds value.

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

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

For a simple read-only tool with one parameter and good annotations, the description is complete enough. It specifies output content, though it omits potential pagination or rate limits. Still adequate given the tool's simplicity.

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

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

Schema description coverage is 100%, with the 'limit' parameter fully described (default, max). The description does not add additional semantics beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves trending posts from Mastodon and lists returned data (engagement counts, authors, tags). It is specific about the resource and action, but does not explicitly distinguish from siblings like 'get_timeline' or 'pipeworx_trending'.

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?

No guidance on when to use this tool versus alternatives. The description implies it is for trending content but does not discuss exclusions or context, leaving agents to infer usage.

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

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

Annotations already indicate readOnly, idempotent, non-destructive nature. Description adds value by listing the exact fields returned (id, type, params, etc.) and noting the optional include_inactive parameter, enhancing 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?

Two concise sentences, each serving a distinct purpose: stating the function and providing usage guidance. No redundant or extraneous content.

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

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

Given no output schema, the description adequately covers returned fields. Annotations cover safety. Some may want pagination info, but for a small list it's acceptable. Lacks only minor details like ordering.

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. Description adds minimal extra meaning beyond what the schema already provides (just implies default of active subscriptions). 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?

Description clearly states it lists the caller's active subscriptions with a specific verb and resource. While it doesn't explicitly distinguish from other list tools in the sibling list, the context of subscriptions makes it clear.

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

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

Provides explicit guidance on when to use the tool: before adding more subscriptions or to find an id to cancel. Does not name alternatives but implicitly differentiates from subscribe/unsubscribe.

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 are all false, leaving the description to carry the burden. It discloses rate limiting (5/day), that it's free and doesn't count against quota, the claim_token flow for checking resolution, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is a single, well-organized paragraph that front-loads the purpose, then covers usage, behavioral nuances, and constraints. Every sentence adds unique, non-redundant information. Appropriate length given the tool's complexity.

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

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

Despite no output schema, the description fully explains the return behavior via claim_token and the resolution-checking flow. It also covers rate limits, quota impact, scope limitations, and guidance for crafting feedback. No gaps for the agent to operate 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds valuable semantics beyond schema: instructs users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, and clarifies claim_token usage ('with no other arguments'). This extra context justifies a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes the feedback tool from all sibling tools, which are research/management tools, by focusing on reporting issues about Pipeworx itself.

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

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

Explicit when-to-use guidance is provided: use for bugs, feature requests, data gaps, or praise. It also gives a clear exclusion: do not report issues from other MCP servers, and explains how to identify Pipeworx tools. This is exemplary usage guidance.

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

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

Discloses caching duration, data source (CF analytics-engine), no PII, and self-aggregating signal. Adds value beyond annotations which already indicate read-only, idempotent, non-destructive.

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

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

Well-structured: main action first, then use cases, then 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?

Given the tool's simplicity (one optional param, no output schema) and full annotations, the description covers behavior, caching, use cases, and data origin completely.

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

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

Single parameter 'window' is fully described with enum values and added semantics: shorter windows surface current trends, longer windows show steady-state demand. Schema coverage is 100%, and description enriches it.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window. It distinguishes from siblings like get_trending by specifying its focus on Pipeworx agent activity.

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

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

Explicitly lists three specific use cases and differentiates between short and long windows. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations declare readOnlyHint and idempotentHint, which align with the read-only computation nature. The description adds rich behavioral details: monotonicity checks, partition sums, semantic anchoring, placeholder filtering, and CLOB depth fill checks. 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 thorough and well-structured, starting with the core purpose then detailing each mode and behavior. Every sentence provides useful information, though slightly verbose for some readers. Could be tightened without losing clarity.

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

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

For a complex tool with no output schema, the description fully explains return fields (opportunities array, partition_check object), covering all modes and edge cases (low similarity, placeholder fraction, fill check). Includes practical warnings and cross-reference to sibling tools, making it self-contained enough for correct invocation.

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

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

Schema already documents both parameters. The description adds significant value by explaining the behavior of each mode with examples (event slug type, topic seed question), how the tool processes them (walks child markets, searches related events), and the algorithm applied. High schema coverage does not diminish the added semantic value.

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

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

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Verb and resource are explicit, and it distinguishes from sibling tools like 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?

Explicitly describes three modes (no args for trending_scan, event for specific market, topic for cross-event scan) and provides recommendations. Includes when-not-to-use warnings such as the Jaccard similarity threshold and placeholder filters, plus the fill check condition for not trading when realizable_edge_pp ≤ 0. References sibling tool 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 already indicate readOnlyHint and idempotentHint, and the description adds extensive behavioral context: caching at KV level, model family details, tradeable-edge knobs, diagnostics, and Fed market caveats. 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 long and dense with technical details (e.g., specific alpha values, funnel counters). While well-structured with numbered segments, it could be more concise. Every sentence adds value, but overall verbosity reduces readability for quick scanning.

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

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

Given the tool's complexity (9 parameters, nested output, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, fed section, diagnostics), model logic, and filter effects, leaving little ambiguity.

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 value by explaining how parameters interact (e.g., slippage_pp advice, min_partition_leg_kelly vs min_kelly distinction), justifying an above-baseline 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the tool is built for 'what should I bet on today' agents and explains how to use filter knobs. However, it does not explicitly mention when not to use it or provide alternatives beyond the implicit differentiation from siblings.

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

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

The description goes beyond annotations by detailing the response structure (tracked[], expired[], snapshot_dates[]), how decay is computed, and limitations (60-day TTL, gaps, intraday vs. daily closes). It fully discloses behavioral traits without contradicting the readOnlyHint, openWorldHint, and other 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 with the purpose and uses a structured format to detail response fields, making it easy to parse. While it is somewhat verbose, every sentence contributes useful information, achieving a good balance between conciseness and completeness.

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

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

Despite the lack of an output schema, the description fully explains the return fields (tracked, expired, snapshot_dates), edge cases (snapshot gaps, TTL), and limitations. It provides sufficient context for the agent to use the tool effectively, making it complete for this complexity level.

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?

Parameter coverage is 100% in the schema, and the description repeats the parameter explanations with slight additions (e.g., 'snapshot family' for window). Since the schema already provides comprehensive descriptions, the description adds limited extra semantic value, meriting a baseline score 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's purpose: providing 'Edge persistence and decay telemetry' to determine how long an edge has existed and whether it is shrinking. It uses a specific verb-resource pair and distinctively contrasts fresh vs. old edges, differentiating it from sibling tools like 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 indirectly explains when to use the tool by contrasting 'a fresh wide edge and a 3-week-old wide edge' and implying its use for understanding edge longevity. However, it does not explicitly specify when not to use it or name alternative tools, leaving room for improvement.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, no destructive. The description adds significant behavioral detail: walks order ladder, returns specific fields like vwap_fill_price, slippage, shares_filled, and warns about partial fills converting arb to unhedged position. 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 long but necessary given the complexity. It starts with a clear summary, then breaks down modes. Some sections are dense (e.g., return field lists) but every sentence adds value. Could be slightly more structured (e.g., bullet points) but is efficient for the information density.

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 lists return fields thoroughly (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains both modes completely. It covers parameters, defaults, return values, usage context, and risk warnings. Nothing essential is missing.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: explains interaction between market/event (mutual exclusivity), default side in basket mode (auto from partition sum), size_usd meaning in basket (settlement notional, shares per leg), and single-market size interpretation (max spend vs target proceeds). These details are not in 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 computes 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and uses specific verbs and resource (edge check). It is not a tautology and clearly differentiates from sibling tools like polymarket_arbitrage.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical edge not capturable on thin books, partial baskets convert arb to directional risk). No ambiguity about when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, but the description adds substantial context beyond that: compatibility fields can be non-empty even when matched_pairs>0, the meaning of each compatibility code, that null temporal_alignment means 'could not be computed' rather than aligned, that Kalshi fees are not modeled (gross spread), and that matching is keyword-based rather than a shared resolution source. 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 long but well-structured with clear section signposts (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence contributes safety or semantic value. It is denser than necessary for the tool's parameter count, but the complexity of the response and safety warnings 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?

Given that there is no output schema, the description carries the full burden of explaining the response shape and interpretation. It covers input modes, top_spreads_pp structure, compatibility codes, fee caveats, skipped counters, and flag per entry. Nothing critical an agent needs to invoke or interpret the tool correctly appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantic nuance beyond the schema: it explains that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, enumerates the exact shortcut values, and clarifies that both modes run the identical token-overlap matcher. This elevates it above the baseline.

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

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

The description states a specific verb and resource: it computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from likely siblings like polymarket_arbitrage and polymarket_edges by focusing on the same-question cross-venue delta, and it is not a tautology.

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

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

The description explicitly documents two modes — topic shortcuts and explicit ticker/slug pairings — and cautions that pre-mapped topics frequently return compatibility_warning ('pre-mapped ≠ tradeable'). It gives context on when each mode is appropriate and warns about interpreting temporal_alignment_unknown. It does not explicitly name sibling alternatives or state 'use instead of X', so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about scoping to an identifier and the lifecycle pairing with remember/forget, which is valuable 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?

Three sentences, each essential: primary action, usage context, and lifecycle. No wasted words, front-loaded with the core functionality.

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

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

Given the simple schema and full annotations, the description covers key behaviors (retrieve vs. list, scope, pairing with siblings). No gaps remain for effective tool 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 coverage is 100% with a clear description for the key parameter. The description reinforces the optionality (omit to list all keys) and adds concrete examples of memory contents (ticker, address, research notes), enhancing understanding.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It distinguishes from siblings by mentioning pairing with remember and forget, making the purpose specific and well-differentiated.

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

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

The description explains when to use the tool (look up stored context without re-deriving) and references alternatives (saving with remember, deleting with forget). It lacks explicit when-not statements but provides sufficient contextual guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it explains that mark_read:true flags returned events as read so subsequent calls return newer ones, and describes the return format in detail. This goes beyond the annotations without contradiction.

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

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

The description is a single paragraph with front-loaded purpose, and each sentence adds meaningful information: purpose, return fields, filtering options, mark_read behavior, and polling/alternative endpoint. No superfluous 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?

Without an output schema, the description adequately covers return fields (source, citation_uri, payload), parameter usage, and behavioral nuances like mark_read. It does not mention error handling or edge cases, but for a simple read-only tool with robust annotations, it is sufficiently 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?

All 5 parameters are documented in the schema (100% coverage), so baseline is 3. The description adds context by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and explicitly mentions filtering by type and ISO timestamp, enhancing understanding 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 retrieves fired events from a subscription feed, specifies return fields (source, citation_uri, payload), and mentions filtering options. This distinguishes it from sibling tools as no other tool handles alerts.

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 notes that 'Polls work fine' and provides an alternative REST endpoint (GET registry.pipeworx.io/alerts.json), offering clear context for when to use this tool vs. direct HTTP access. However, it does not explicitly state when not to use the tool among sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing it as a safe, read-only tool. The description adds valuable behavioral context: parallel fan-out to multiple sources, fallback logic (GDELT preferred, GNews on rate limit/5xx), soft-failure for USPTO, and the return format (structured changes grouped by source, total_changes count, pipeworx:// 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?

The description is moderately long but well-structured. It front-loads with example queries and core purpose, then systematically covers sources, parameter details, return format, and alternative tools. Each sentence adds value without redundancy. A slight reduction could make it even tighter, but it remains efficient.

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

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

Given the tool's complexity (multiple data sources, fallback logic, special date formats) and the absence of an output schema, the description is remarkably complete. It explains what sources are consulted, how fallback works, the `since` parameter formats, the output structure, and directs to the sibling tool for static profiles. The annotations cover safety and idempotency. An AI agent has sufficient information to decide when and how 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%, so baseline is 3. The description goes beyond by explaining the 'since' parameter accepts both ISO dates and relative shorthand (with examples '7d', '30d', '1y'), specifying for 'value' it can be a ticker or zero-padded CIK, and clarifying 'type' is currently limited to 'company'. This adds practical usage guidance 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 starts with example queries ('What's new with X', 'latest on Y') and clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It identifies specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes itself from the sibling tool 'entity_profile', which serves the complementary use case of static profiles.

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

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

The description explicitly tells when to use this tool vs alternatives ('Use entity_profile instead when you want the static profile...'), and provides example natural language queries. It implies usage for recent changes but does not explicitly state when not to use it (e.g., for historical data beyond a few years).

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 idempotent and non-destructive. Description adds important details: persistence scoping, session duration for anonymous (24 hours), and key-value storage mechanism. 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?

Paragraph is concise, front-loaded with purpose, then usage, then technical details. Every sentence adds value. No wasted words.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage, behavior, and parameter guidance. Missing only what the return value or confirmation looks like, but 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 has 100% coverage with good descriptions for 'key' and 'value'. The description adds example values but does not provide significant additional meaning beyond the schema. Baseline 3.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'Save' and resource 'data'. Distinguishes from siblings 'recall' and 'forget' by mentioning pairing.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Provides context on scoping (by identifier) and persistence (authenticated vs anonymous). Clear guidance.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, but the description goes well beyond them: it discloses graceful degradation when GLEIF/OpenFIGI are unavailable, internal cascading through multiple lookup endpoints, the behavior of returning figi_candidates instead of asserting on ambiguous matches, and the explicit listing of unresolved identifiers under `unresolved`. These are behavioral traits an agent cannot infer from annotations alone.

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

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

The description is dense but front-loaded with concrete trigger examples and the "Use FIRST" directive, then organized under SUPPORTED TYPES. However, it is very long and contains long run-on parentheticals that reduce scannability; while nearly every detail is useful, tighter formatting or bulleted structure would improve readability without losing content.

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

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

Given there is no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly: it names the output fields (`figi_candidates`, `unresolved`, source labels), covers failure modes for non-equity instruments, and describes enrichment fallback. For a complex tool with two entity types and multiple upstream sources, the description is complete enough for an agent to call it correctly and understand what it will get back.

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

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

Although the schema covers both parameters at 100%, the description adds substantial semantic value. It explains that `value` for a bond must be the issuer exactly as printed, warns against including trailing security-class words, and details how the same string can be a ticker, CIK, ISIN, or name. For `type`, it enumerates what each entity type returns and how enrichment works, far exceeding the schema's one-line 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 action — resolve a user-spoken name to canonical/official identifiers — and names the concrete resources it handles (CIK, ticker, LEI, RxCUI, FIGI). It distinguishes itself from sibling tools by framing itself as the first stop when you have a name but need an ID, and by listing supported entity types in detail. This leaves an agent with no ambiguity about what the tool is for.

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 invocation rule: "Use FIRST whenever you have a name but need an ID." It also explains that one call replaces 2-3 manual lookups, which helps the agent choose it over multi-step alternatives. However, it does not explicitly name sibling tools like entity_profile or compare_entities as alternatives or say when those should be used instead, so the exclusion guidance is incomplete.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds that it internally calls 'ai_visibility_check' per entity, ranks results, and surfaces most/least recognized. No contradictions with annotations.

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

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

Two sentences: first states purpose and mechanism, second provides usage context. Front-loaded with key action and output. Every sentence adds value; no fluff.

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

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

Despite lacking output schema, description clearly states it returns 'ranked list with score, confidence, signal density per entity'. Covers all necessary aspects: input, process, output, use case.

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

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

Schema coverage is 100% but description adds valuable semantics: 'first entry treated as the subject for narrative; rest are competitors'. This helps interpret the 'entities' parameter beyond the schema.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities'. It clearly distinguishes from sibling 'ai_visibility_check' (single entity) by stating it probes multiple entities side-by-side and ranks them.

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

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

Provides explicit use case: 'competitive AI-marketing audits' and an example question. Does not explicitly state when not to use or mention alternatives like 'ai_visibility_check' for single entity, but context is clear enough.

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, non-destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed will list timeouts.

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

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

The description is somewhat lengthy but well-structured and information-dense. Every sentence adds 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?

No output schema exists, so the description fully compensates by detailing the return structure (summary block, per-advisory detail, links, alternative versions) and error handling (partial failures).

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 package and version described). Description adds context by explaining defaults and composite behavior, but the schema already provides adequate 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 composite check for npm packages, covering license, advisories, version history, and bundle size. It clearly distinguishes from sibling tools that are unrelated (e.g., AI visibility, betting, search).

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

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

The description provides explicit use cases ('is X safe / popular / small' or 'what does adding lodash cost me'), specifies NPM-only scope in v1, and directs to alternatives (deps.dev:version) for other ecosystems.

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 openWorldHint, so the description need not repeat those. It adds that results include follower counts and engagement metrics, which provides useful behavioral context beyond the schema. However, it doesn't disclose any additional behavioral traits like rate limits or authentication needs.

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

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

Description is a single efficient sentence with no wasted words. It front-loads the main purpose and adds output details concisely.

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 output schema exists, the description adequately covers return values by mentioning follower counts and engagement metrics. It could mention the default type (statuses) but the schema covers that. Overall complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already details all parameters. The description does not add new parameter-level semantics beyond what the schema provides. The examples in the input schema are helpful but not part of the description.

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

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

Description clearly states the tool searches Mastodon for accounts, statuses, or hashtags, specifying the resource and result types including profiles, posts, and tags with follower counts and engagement metrics. This distinguishes it from siblings like 'search_within' or 'deep_research'.

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

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

Description implies usage for searching Mastodon content but does not explicitly state when to use this tool versus siblings like 'search_within' or 'deep_research'. No when-not guidance is provided.

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

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

Adds concrete details beyond annotations: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation, returns character offsets and similarity scores. Annotations already declare readOnly, idempotent, and non-destructive; 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?

Dense paragraph front-loads key idea; every sentence adds value. Could be slightly more structured but is appropriately sized and informative.

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

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

No output schema, but description explains output format (passages with offsets and scores), embedding details, character cap, and pairing with another tool. Complete for a 3-param search tool with 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?

Schema coverage is 100%, but description enriches 'text' with example types and 200K char limit, 'query' with natural-language examples, and 'limit' with default value. Adds meaningful context beyond schema.

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

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

The description clearly states it performs semantic search inside a provided text, specifying the verb 'search', resource 'text content', and scope 'inside a fetched record'. It distinguishes from sibling tools by noting it's for large records and pairs with ask_pipeworx_grounded.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and describes the return format (passages with offsets). Mentions pairing with ask_pipeworx_grounded for grounded answers. Lacks explicit when-not-to-use, but positive guidance is strong.

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

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

Beyond annotations (readOnlyHint: false, openWorldHint: true, idempotentHint: true, destructiveHint: false), the description discloses requirement for OAuth account, return of subscription id, rate limits on SMS (10/day), webhook auto-disable after 10 failures, and delivery channel constraints. It adds substantial behavioral 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 concise but thorough, using clear sectioning for purpose, requirements, types, and delivery channels. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (3 parameters, nested objects, multiple types, no output schema), the description covers purpose, inputs, outputs, prerequisites, and behavioral traits. It provides enough detail for correct invocation.

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

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

With 100% schema description coverage, the description enriches each parameter with concrete examples and constraints (e.g., SEC 8-K items, polymarket topic, phone verification). It clarifies nested object structures and provides delivery channel specifics 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.' It identifies the resource (subscription) and action (create), and distinguishes from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description explains prerequisites (OAuth account) and gives context for each subscription type. While it doesn't explicitly state when not to use this tool, it implies that only authenticated users can persist subscriptions, effectively excluding anonymous users.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: returns category-bucketed example questions with tool arguments, 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?

Description is front-loaded with common queries, then structured with details. While lengthy, each sentence provides necessary context without redundancy. Could be slightly more concise but 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?

No output schema exists, so the description fully covers what is returned (category-bucketed example questions with exact tool and argument shape). Also explains the source (live catalog) and optional topic filtering. Complete for 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%, but the description adds meaning by specifying example topics (finance, pharma, etc.) and explaining that omitting topic yields a cross-category spread. This aids agent in parameter selection.

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

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

The description clearly states the tool's purpose as an onboarding entry point for new agents, providing example questions. It distinguishes itself by recommending use before exploring other tools and names sibling meta-tools like ask_pipeworx.

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

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

Explicitly states when to use: when the agent doesn't know Pipeworx's capabilities or to learn meta-tools. Also explains optional topic parameter for focus, and lists sibling tools as alternatives for specific queries.

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

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

Adds key behavioral context beyond annotations: row is deactivated (not deleted), history preserved via recent_alerts. This explains side effects and data lifecycle.

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 focused sentences, front-loaded with action, 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?

Covers action, ownership, and effect on data. Lacks mention of return value, but for a simple idempotent mutation this is minor. Well-rounded overall.

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

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

Schema covers the single parameter fully (id as uuid from subscribe). Description adds little beyond 'by id', but ownership enforcement indirectly relates. Baseline 3 due to 100% coverage.

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

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

Describes canceling a subscription by id, clearly distinguishing from sibling tools like subscribe and list_subscriptions. Verb 'Cancel' and resource 'subscription' 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?

States ownership enforcement (only your own subscriptions). Clear context for use, though lacks explicit when-not-to-use or comparison to alternatives. Still strong 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 read-only/idempotent annotations, the description adds critical nuance: it defines the verdicts, explains the special meaning of could_not_verify (not evidence) and unsupported, and discloses the internal pipeline routing. This is significant behavioral context that prevents misuse.

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 densely informative, starting with trigger phrases and a clear purpose, then covering usage, output, and caveats. While long, each sentence contributes value, though it could be slightly tightened in the middle.

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

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

With no output schema, the description fully explains return values: a verdict from the enumerated list, the actual value with citation, and reasoning. It also clarifies the two edge-case verdicts (could_not_verify vs unsupported), which is essential for correct interpretation.

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

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

Both parameters are already described in the schema with 100% coverage, so the description adds little beyond mentioning 'exact percent-delta math' for financial claims. The schema's tolerance_pct explanation is more detailed than the description's, so the description does not need to compensate.

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 'natural-language claim verification against authoritative sources' and provides a specific verb ('fact check'/'verify'). It distinguishes itself from sibling tools by focusing on returning a verdict with grounded evidence, making its purpose unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes two usage paths (structured SEC EDGAR vs grounded pipeline) but does not explicitly name alternative tools or exclusions, so it lacks full comparative guidance.

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