Reddit

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. Description adds key details: default model is free, using Anthropic requires a personal API key and incurs costs, and the return structure includes per-model {score, confidence, signals, raw_response} plus a combined view. No contradiction with annotations.

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

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

Description is two sentences that efficiently cover purpose, default behavior, optional parameters, return format, and use cases. No wasted words, key information is front-loaded.

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

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

Despite no output schema, the description explains the return format per model and combined view. It covers all essential aspects: purpose, parameters, behavior, use cases, and constraints. For the tool's complexity (4 params, no nested objects), this is fully 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?

With 100% schema coverage, the description goes beyond by providing examples for 'entity', default behavior for 'models', the role of '_apiKey' as a pass-through, and disambiguation help for 'context'. This adds meaning not fully captured in the schema.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score per model. It specifies the verb 'probe' and resource 'LLMs', and distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on generic brand/product checks rather than competitor-specific analysis.

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

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

Explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and how to enable Anthropic with a BYO key. It does not explicitly list when not to use or alternative tools, but the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about routing to 3,751 tools and returning citation URIs, which is beyond the annotations.

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

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

The description is front-loaded with the key instruction and uses a bullet-like list of domains. It is reasonably concise for the amount of guidance provided, though examples add 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 no output schema, the description only mentions 'structured answer with stable pipeworx:// citation URIs', which is vague. Missing details on error handling or response format. For a complex tool, more completeness would be beneficial.

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 only repeats that aliases are accepted, adding no new semantic information beyond what the schema provides.

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

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

The description clearly states the tool routes questions to many tools and returns structured answers with citations. It lists many use cases but does not distinguish from sibling tools like 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 says 'PREFER OVER WEB SEARCH' for specific topics and provides numerous examples of when to use, such as 'current US unemployment rate' or 'Apple's latest 10-K'. Gives clear guidelines even if alternatives are not mentioned.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: the internal routing, extraction process, return format with explicit refusal reasons, and the extra LLM call cost. No contradictions with annotations.

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

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

The description is well-organized: starts with purpose, then mechanism, return format, usage advice. It is slightly long but every sentence adds value. No filler.

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 (routing among 3751 tools) and the presence of annotations, the description covers return format, refusal reasons, and cost implication. No output schema exists, but the description provides adequate detail for an AI agent to use it safely.

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 all parameters are aliases for 'question'. The description only says 'Your question in natural language', adding no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and differentiates from sibling 'ask_pipeworx' by noting the extra extraction step for factual grounding. The verb 'ask' plus resource 'Pipeworx Grounded' is specific and the behavior is well-defined.

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

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

Explicitly advises use when 'an answer will be quoted, cited, or acted on' and instructs to 'prefer ask_pipeworx for casual lookups', providing clear context for when to use this tool versus its sibling.

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 extensive behavioral context: market resolution, classification, fan-out to data packs, response shapes, safety checks (low-confidence matches, closed markets, wide spreads), and resolution-rule risk. This goes far beyond annotation defaults.

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

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

The description is well-structured with section headers and front-loaded with the main purpose. However, it is quite verbose, containing very specific details and examples that could be trimmed without losing essential guidance. It earns its place but could be more concise.

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

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

Despite no output schema, the description thoroughly covers response shapes, resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. It addresses all aspects a complex tool like this needs, ensuring the agent can use it effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for the 'market' parameter (slug, URL, question text) and explains 'depth' and 'include_raw', but does not significantly enhance understanding beyond the schema's own 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 researches a Polymarket bet by pulling Pipeworx data in one call. It specifies the verb 'research', the resource 'Polymarket bet', and distinguishes from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on data gathering and analysis.

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

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

The description provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It does not explicitly state when not to use it or alternatives, but the context is clear enough for an AI agent.

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

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

Annotations already declare non-destructive, read-only, idempotent behavior. Description adds critical details: data sources (SEC EDGAR/XBRL for companies, FAERS etc. for drugs), handling of fiscal years, sorting by primary metric, and output includes citation URIs.

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

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

Description is front-loaded with natural language examples and instructions, every sentence adds value. However, slightly verbose; could be more concise without losing information.

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

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

No output schema, but description explains return data per type, sorting, and citation URIs. With annotations safety profile clear, the description is fairly complete for an agent to understand expected behavior.

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

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

Schema coverage is 100% with parameter descriptions, but description adds value with concrete examples (tickers, drug names), constraints (2-5 items), and explains what each type returns.

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 does side-by-side comparison of 2–5 companies or drugs, with specific examples of query phrasings. It distinguishes itself from siblings by noting it should be preferred over sequential lookups.

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

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

Explicitly advises to always prefer this tool over sequential lookups when comparing entities, and provides example queries. However, lacks explicit 'when not to use' or direct alternatives among 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?

Beyond annotations (readOnly, idempotent, etc.), the description details the decomposition, parallel routing, evidence extraction with verbatim evidence, confidence, sources, citations, and gaps[] array. It also mentions expected time (15-60s) and account requirements. 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 appropriately sized for a complex tool; every sentence adds value. It is front-loaded with the main purpose, followed by methodology, output format, usage guidance, and requirements. No wasteful repetition or irrelevant details.

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

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

Given the tool's complexity and absence of an output schema, the description is complete: it explains the return format (structured findings packet, gaps[]), behavior (pre-verified facts), and prerequisites (account, paid plan). It covers all aspects needed for an AI agent to understand and invoke the tool correctly.

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

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

The description adds meaning beyond the input schema: for 'depth', it specifies the number of facets (quick=3, standard=5 default, thorough=8) and that thorough requires a paid plan. For 'question', it clarifies that broad/multi-part questions are acceptable and that decomposition is the point. Schema coverage is 100%, but description enriches understanding.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research in ONE call.' It explains the process of decomposing questions, routing to sources, and extracting answers. It distinguishes from sibling ask_pipeworx by noting it is for broad/multi-part questions vs single lookups.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and provides alternative: 'use ask_pipeworx for single lookups.' Also mentions prerequisites: requires a Pipeworx account, and paid plan for 'thorough' depth. This guides the agent in tool selection.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the output format (top-N tools with names, descriptions, and schemas) and confirming the input parameter aliases, which goes beyond the structured 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 slightly lengthy but well-organized, front-loading the purpose and key usage advice. It includes multiple examples of queries (e.g., 'look up FDA drug approvals') and clearly explains the return value, earning its 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 the tool's role as a discovery tool, the description fully covers what it does, when to call it, and what it returns. It describes the output (tool list with schemas) and addresses input parameter aliases, making it complete for effective use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reaffirms the query parameter is natural language and lists aliases, but these are already covered in the schema descriptions. No additional semantic depth is provided beyond what the schema offers.

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: finding tools by describing a data or task. It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being a meta-discovery tool, not a data-retrieval tool.

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

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

The description explicitly advises to call this tool FIRST when many tools are available, providing clear guidance on when to use it. While it doesn't mention when not to use it, the context implies it's for browsing and not for direct data 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?

Discloses data sources, return fields, potential failure of patents API, and input requirements. Annotations already indicate safety, but description adds depth 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?

Front-loaded with examples, but the detailed list of return items makes it slightly lengthy. Still efficient given 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?

Comprehensively covers inputs, sources, outputs, and failure modes. Without output schema, the description fully explains return values.

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 value by explaining unsupported name input and CIK format (zero-padded). Goes beyond schema descriptions.

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

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

The description clearly identifies the tool as providing a 'full cross-source profile of a US public company' with specific examples. It distinguishes from sibling tools by stating it should be preferred over chaining individual lookups for holistic views.

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 (holistic view) and when not to use (if only a name, use resolve_entity first). Provides alternatives and notes patent API limitations.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds no additional behavioral context 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?

Two sentences, front-loaded with action and purpose, no wasted words.

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

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

For a simple delete operation with one param, strong annotations, and no output schema, the description is fully adequate.

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

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

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, and description adds no further meaning.

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 the tool deletes a memory by key, with specific verb 'Delete' and resource 'memory'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Provides explicit when-to-use scenarios: stale context, task completion, clearing sensitive data. Suggests pairing with remember and recall.

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

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

Discloses actions: fetches page, extracts title/description/key links, emits standard format. Annotations already indicate safety and idempotency; description adds process and output details without contradiction.

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

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

Three efficient sentences: purpose, method, use cases. No redundancy, front-loaded with essential information.

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

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

For a simple tool with 2 params and no output schema, the description fully explains purpose, output format, and use cases. No missing critical context.

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

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

Both parameters fully described in schema (100% coverage). Description mentions URL implicitly ('Fetches the page') and max_links not detailed beyond schema; adds no additional meaning.

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

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

Clear verb+resource: 'generate a production-ready llms.txt file'. Distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation, not checking or scanning.

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 use cases listed ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'), providing clear context. Lacks explicit when-not-to-use or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds return fields (text, score, author, etc.), which provides some behavioral context but annotations cover safety profile well.

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

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

Two sentences: first states purpose and method, second lists return contents. No wasted words, front-loaded with essential info.

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

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

Tool is simple (1 param, no nested objects) with output schema present. Description mentions return structure (text, score, author, comment threads) which complements schema. For a straightforward read tool, this is complete enough.

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

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

Only one parameter (post_id) with 100% schema description coverage. Schema already describes it as 'Reddit post ID (the alphanumeric ID, e.g., "abc123")'. Description adds no extra parameter semantics beyond schema.

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

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

Description clearly states 'Get a Reddit post's full content and top-level comments by post ID'. Specifies verb (Get), resource (Reddit post), and distinguishes from sibling tools like search_posts or get_subreddit.

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 to use when you have a post ID and want full content and comments, but no explicit when-not-to-use or alternatives. Sibling list includes search_posts, but no guidance on choosing between them.

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, so the description does not need to repeat that. The description adds value by specifying the returned fields (titles, scores, authors, URLs, comment counts), which is beyond what annotations provide. No hidden behaviors need disclosure, and no contradictions exist.

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 sentence of 21 words, front-loaded with the main action ('Get trending posts from a subreddit'), followed by specifics on returned data. Every word serves a purpose, with no redundancy. This is highly concise for a two-parameter tool with good schema and annotations.

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 covers the essential purpose and return fields. Although the tool is simple (2 params, 1 required, output schema present), the description does not mention aspects like subreddit accessibility (private/restricted) or error cases. However, given the low complexity and presence of an output schema, the description is sufficiently complete for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so both parameters are well-defined in the schema (subreddit: name without prefix, limit: number with default/max). The description adds the example values 'python' and 'news' for subreddit, but this is already present in the schema examples. Overall, the description adds minimal extra meaning beyond the schema, justifying the 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 gets trending posts from a specified subreddit, listing the data returned (titles, scores, authors, URLs, comment counts). This specifies a verb ('get') and a resource ('trending posts from a subreddit'), and distinguishes it from siblings like 'get_post' (single post) and 'search_posts' (likely cross-subreddit 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 implies usage: to retrieve trending posts from a subreddit. However, it does not explicitly state when to use this tool versus alternatives like 'get_post' or 'search_posts', nor does it provide conditions where this tool is not appropriate. The context signal of sibling tools is present but not leveraged in the description.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so description adds specific context about return fields and default behavior (active subscriptions). 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 no wasted words. Front-loads purpose and ends with usage guidance.

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?

Sufficient for a low-complexity tool with one optional parameter. Lists return fields despite no output schema. Complete for typical use.

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

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

Schema coverage is 100%, and description hints at default behavior for include_inactive parameter. Adds some context beyond schema but not extensive.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinct from sibling tools 'subscribe' and 'unsubscribe'.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear usage context. No explicit when-not-to, but implied.

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

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

The description discloses rate limits (5 per identifier per day), free usage (no quota impact), and how feedback is processed (digests read daily, affects roadmap). Annotations provide no contradictory information; all are false, and the description adds valuable behavioral context beyond annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then provides usage guidance, then behavioral notes. Every sentence adds value; there is no redundancy or filler.

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

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

Despite no output schema, the description covers all necessary aspects: input semantics, usage guidance, behavioral traits, and constraints. It is fully self-contained for an agent to correctly invoke this tool.

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

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

Schema coverage is 100%, so each parameter has a description. The tool description adds extra context: for 'type', it reinforces enum meanings; for 'message', it advises specificity and length; for 'context', it notes optionality. This goes beyond the schema, though the schema already does well.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, or praise. It specifies the resource (Pipeworx team/tools) and verb (send feedback). None of the sibling tools perform this function, so it distinguishes well.

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

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

The description explicitly lists when to use this tool (bug, feature/data_gap, praise) and what not to do (don't paste end-user's prompt). This provides clear guidance on appropriate vs. inappropriate usage, differentiating it from 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by disclosing: self-aggregating signal, derived from CF analytics-engine, no PII, output structure (pack, tool, count), and caching behavior (5min-1h depending on window). No contradiction.

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

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

Three efficient sentences, front-loaded with main purpose, no redundant words. Each sentence earns its place.

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

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

For a tool with 0 required params and no output schema, the description covers purpose, output structure, data source, privacy, and caching. Lacks exact output format details, but sufficient for selection and invocation.

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

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

Schema coverage is 100% (single parameter 'window' with enum and description). The description repeats the enum values and adds usage context but doesn't provide new syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, using specific verbs and resources. It distinguishes from sibling tools like 'discover_tools' or 'ask_pipeworx' by focusing on trending aggregates.

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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, aligning use case with demand). Different window durations are advised for different needs. No explicit when-not-to-use, but the context is strong.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint all true, and destructiveHint false. The description adds detailed behavioral context: the two modes, semantic anchor for similarity (≥0.30 Jaccard), partition filter (drops placeholder slugs, >20% placeholder fraction returns null), fill check against live CLOB depth, and response structure. No contradiction with annotations.

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

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

The description is lengthy but well-structured with logical sections: requirements, mode explanations, semantic anchor, partition filter, fill check, and response fields. Every sentence contributes essential information. A slight reduction in verbosity could improve conciseness, but the structure aids comprehension.

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

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

Despite no output schema, the description explains the response structure (opportunities array, partition_check object, fill check details). It covers all major behavioral aspects: required args, mode-specific behavior, similarity threshold, placeholder filtering, fill check logic, and mentions related tools. The tool is complex and the description provides comprehensive context.

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

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

Schema description coverage is 100% for both parameters. However, the description adds significant meaning: explains the mode each parameter triggers, acceptable formats (slugs, URLs), and provides concrete examples like 'fed-decision-may-2026' and 'Fed rate decision'. This goes well beyond the schema descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes: 'event' for a specific market and 'topic' for cross-event scanning, with examples. It also references sibling tools like polymarket_fill_risk for context.

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

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

The description explicitly says one of 'event' or 'topic' is required, and call with no args fails. It recommends 'event' for specific markets and 'topic' for cross-event scanning, explaining the advantage of each. It also mentions when not to trade (realizable_edge_pp ≤ 0) and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds extensive behavioral context: caching behavior (1h KV), response structure with diagnostics for empty segments, detailed edge calculation methodology, and tradeable-edge knobs. No contradiction with annotations.

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

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

The description is very long and dense with technical details, but it is well-structured: purpose first, then segments, then response fields, then caching. It is front-loaded with the core action. While every sentence adds value, the length might hinder 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?

Since there is no output schema, the description fully details the response structure: by_segment groups, fed_candidates, _diagnostics, and per-opportunity fields. It explains all knobs and caching. The description is thorough and leaves no ambiguity about inputs, outputs, or behavior.

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 9 parameters are documented in the schema (100% coverage). The description adds significant value beyond schema descriptions, such as explaining default values, the purpose of each filter (e.g., min_edge_pp is net of slippage), and interactions between parameters (e.g., min_partition_leg_kelly vs min_kelly for partition arbs).

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

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

The description clearly states the tool scans top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan', the resource 'top Polymarket markets', and the output. The purpose is distinct from siblings like polymarket_arbitrage, which likely focuses on cross-market arbitrage.

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

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

The description explicitly targets the 'what should I bet on today' use case and explains the three opportunity segments. It details when each segment appears and provides tradeable-edge knobs. However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_kalshi_spread, leaving the agent to infer distinctions.

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

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

The description adds extensive behavioral details beyond the readOnly, idempotent, non-destructive annotations. It explains the response structure (tracked, expired, snapshot_dates), field meanings (trend, decay_pp_per_day, lifespan_days), and limits (60-day TTL, snapshot start date, daily closes not intraday). No contradictions with annotations.

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

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

The description is well-structured with a clear opening question, detailed response fields, and a LIMITS section. It is slightly long but every sentence adds value. Could be marginally more concise, but overall 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?

Given no output schema, the description fully explains return values (tracked, expired, snapshot_dates) and their sub-fields. It covers edge cases (snapshot gaps, 60-day TTL, decay computation). The tool's complexity is well-documented.

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 parameters have descriptions including defaults and ranges). The description reiterates the parameter purposes (lookback, window family) but does not add new information beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('answers how long has this edge existed and is it shrinking?') and clearly defines the resource (edge persistence and decay telemetry from daily snapshots). It distinguishes from the sibling tool 'polymarket_edges' by focusing on historical tracking rather than a single current snapshot, and provides a concrete example contrasting a fresh edge with a 3-week-old one.

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 implies when to use the tool (when edge age and decay are relevant) and gives context that a fresh wide edge differs from an old one. However, it does not explicitly state when not to use it or name alternatives like 'polymarket_edges' for a single snapshot, though that is clear from the description.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read-only operation. The description adds rich behavioral context: it walks the ladder, returns specific fields like slippage_pp, shares_filled, and for basket mode details thin_legs, forced_directional_risk. It explains that partial fills convert arb to unhedged directional positions, which is a key behavioral trait. 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 fairly long but well-structured with sections and bold key terms. Each sentence adds value, though some parts could be condensed slightly. It is appropriately detailed for the tool's complexity.

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

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

Given the tool's complexity, no output schema, and two distinct modes, the description is comprehensive. It covers single-market and basket modes, return fields, and risks. However, it could explicitly state that the tool only simulates/checks and does not execute trades (though implied by annotations). It is nearly complete.

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

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

Schema description coverage is 100% (all 4 parameters have descriptions). The description goes beyond the schema by explaining the default behavior for the 'side' parameter in both modes and clarifying 'size_usd' for basket mode (settlement notional, shares per leg). It also explains that 'market' and 'event' are mutually exclusive modes. This adds significant value.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly details what each mode returns (top_of_book, vwap_fill_price, slippage_pp, etc.). This differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description gives explicit usage 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 overround on thin books not capturable, partial basket fills create unhedged positions). This clearly tells the agent when to use this tool vs 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 confirm read-only, idempotent, non-destructive behavior. The description adds extensive context beyond annotations, explaining safety fields like compatibility_warning and temporal_alignment, and warns about non-equivalent bet shapes and temporal misalignment, giving agents a thorough understanding of tool behavior.

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

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

The description is front-loaded with the main purpose in the first sentence and is well-structured. However, it is quite lengthy with dense technical details; a slightly more concise version would improve readability without losing essential information.

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

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

Despite lacking an output schema, the description comprehensively explains the response format (leg-by-leg prices, spread array, safety fields) and covers all aspects of tool behavior, including edge cases and warnings. Given the tool's complexity, this is a complete and actionable description.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the two modes (topic vs explicit) and how parameters interact (e.g., explicit overrides topic), but the schema already provides adequate individual parameter meanings.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, differentiating it from sibling tools like polymarket_arbitrage and polymarket_edges by its specific focus on cross-venue comparisons.

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?

Describes two modes (topic shortcuts and explicit pairings) and warns that real spreads are rare, with most pre-mapped topics returning compatibility warnings. Provides clear context for when the tool is appropriate, though it lacks explicit alternatives compared to sibling tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it can retrieve by key or list all keys, and it is scoped per identifier. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with the main action, and every sentence adds value. No wasted or redundant 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 hints at returning a value or list but does not explicitly state the return format. However, it is comprehensive enough for a retrieval tool with a single optional parameter.

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 beyond the schema by explaining that omitting the key lists all keys, and that it retrieves values previously saved. This provides helpful context.

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

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

The description clearly states the tool's purpose with specific verbs ('Retrieve a value' or 'list all saved keys') and resource ('saved via remember'). It distinguishes itself from sibling tools like 'remember' and 'forget' by describing its specific function.

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 ('to look up context the agent stored earlier'), its scoping ('Scoped to your identifier'), and pairs it with 'remember' and 'forget'. It does not explicitly state when not to use, but the 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?

The description goes beyond annotations by disclosing that setting mark_read:true triggers a side effect (flagging events as read), which contradicts the readOnlyHint:true annotation. This transparency adds value by accurately describing the tool's behavior.

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

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

The description is concise with 3 sentences, front-loading the core purpose and then providing filtering options and usage notes. Every sentence serves a purpose, including the mention of the alternative REST endpoint for 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?

Given the tool has no output schema, the description adequately explains the returned fields (source, citation_uri, raw payload), filtering options, side effects of mark_read, polling suitability, and an alternative access method. It covers all critical aspects for effective 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?

With 100% schema coverage, the description adds extra context for type (e.g., 'sec_8k') and explains the effect of mark_read, enhancing understanding beyond the schema. The limit and unread_only parameters are not elaborated, but the example and explanation for key parameters provide value.

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

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

The description starts with 'Pull fired events from your subscription feed,' which clearly specifies the verb (pull) and resource (fired events). It also details the content of each alert (source, citation_uri, raw payload), and implicitly distinguishes from sibling tools like list_subscriptions which manage subscriptions rather than retrieving events.

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 mentions 'Polls work fine' and provides an alternative REST endpoint for scripts and dashboards, offering clear context for when to use this tool. However, it does not explicitly exclude use cases or compare with sibling tools beyond the indirect differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: fans out to multiple sources, fallback logic, soft-fail for USPTO, acceptable input formats for `since`, and the structure of the return value (grouped changes, total count, citation URIs).

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

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

Single paragraph with good structure using quotes and line breaks. Dense but not overly verbose; could be slightly more concise but appropriate for the complexity of the 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 no output schema, the description explains the return format (changes[] grouped by source, total_changes count, citation URIs). It also covers multiple data sources, fallback logic, and alternative tool usage, making it complete for agent 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%, so the schema already documents parameters. The description adds usage advice for `since` (relative shorthand like '30d', '1m') and clarifies that `value` accepts ticker or CIK, and `type` is limited to 'company'.

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

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

The description uses specific verbs ('returns change feed for a company') and names multiple data sources (SEC EDGAR, GDELT→GNews, USPTO). It explicitly distinguishes from the sibling tool 'entity_profile' by contrasting dynamic vs static profile.

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

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

Provides clear examples of when to use (user queries like 'What's new with X') and explicitly states when not to use: 'Use entity_profile instead when you want the static profile...'. Also explains fallback behavior between GDELT and GNews.

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=false and destructiveHint=false. Description adds: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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?

Four sentences, front-loaded with purpose. Could be slightly more concise, but every sentence adds value—usage guidance, lifetime details, pairing with siblings.

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

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

Complete for a simple key-value store with 2 parameters, 100% schema coverage, and clear annotations. No output schema needed. Description covers purpose, usage, behavioral traits, and lifetime.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra context (key-value pair scoping) but does not deepen parameter understanding 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 specifies a clear verb ('save'), resource ('data'), and scope ('across conversations or sessions'). It lists real-world use cases like resolved ticker or user preference. Sibling tools 'recall' and 'forget' are mentioned, distinguishing this tool's role in the memory trio.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. Pairs with recall and forget. Lacks explicit when-not-to-use instructions, but context makes it 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: internal cascading calls, replacement of 2-3 manual lookups, and detailed output per entity type (including citation URIs). Missing info on failure handling or rate limits keeps it from a 5.

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-structured paragraph front-loaded with query examples. Every sentence adds distinct value without redundancy. It efficiently covers purpose, usage, supported types, and outputs.

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

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

For a tool with no output schema, the description effectively explains return values for both types and mentions cascading calls. It does not address failure scenarios (e.g., unresolvable names) or potential limits, which would make it fully complete.

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

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

With 100% schema coverage, the description still provides significant added value: examples for 'value' (ticker, CIK, name for company; brand/generic for drug), auto-disambiguation note for company, and explanation of return fields. The schema's enum for 'type' is enriched with type-specific details.

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

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

The description uses specific verbs ('resolve', 'returns') and clearly identifies the resource (names to identifiers). It provides concrete examples and distinguishes its role as the first step when an ID is needed, setting it apart 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 explicitly states 'Use FIRST whenever you have a name but need an ID' and gives example queries. However, it does not mention when not to use it or compare directly with siblings that might also require IDs, leaving room for ambiguity.

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. The description adds that it calls ai_visibility_check internally, ranks results, and returns specific fields. It also mentions the optional _apiKey requirement for certain models, which is not in 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, front-loaded with main action, then internal mechanics, then use case. No redundant or extraneous information.

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

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

The description covers the output (ranked list with score, confidence, signal density) despite lacking an output schema. It does not mention limits like entity count range (handled in schema) or error handling, but overall is sufficient for a comparison 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 value by explaining that the first entity is treated as the 'subject' and the rest as competitors. It also clarifies the optional nature of models and _apiKey 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 uses specific verbs: 'Compare', 'Probes', 'ranks', 'surfaces'. The resource is clearly 'AI visibility across multiple entities'. It distinguishes from sibling ai_visibility_check by emphasizing side-by-side comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and contrasts with single-entity probing. It does not explicitly state when not to use this tool vs alternatives like ai_visibility_check, but the context implies it.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds behavioral details: it fans out across multiple sources, can take 5-30s on first measurement, partial failures return sources_failed, and it returns specific fields. 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 dense single paragraph that efficiently conveys all necessary information. Each sentence adds value, though it could be structured with bullet points or separate paragraphs for readability. Still, it's concise and front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description explicitly lists all return fields, explains partial failure behavior, and covers ecosystem scope. This fully compensates for the missing output schema, making the tool comprehensible and predictable.

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

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

Schema coverage is 100%, with descriptions for both parameters covering name examples and version defaults. The description adds no new parameter 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's purpose as a composite check for adding npm packages, aggregating data from deps.dev and bundlephobia. It distinguishes itself from sibling tools by explicitly scoping to NPM ecosystem v1 and noting alternatives for other ecosystems.

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

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

The description explicitly says to use when an agent asks about package safety, popularity, or size. It also provides guidance on when not to use it (other ecosystems) and suggests alternatives (deps.dev:version directly). The graceful degradation and timeout note further guide 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 read-only and idempotent behavior; description adds value by specifying return fields. No additional behavioral traits mentioned, but annotations cover safety adequately.

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

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

Two sentences, front-loaded with action and scope, no redundant information. Every sentence adds value.

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

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

With 3 parameters fully described in schema, output fields listed in description, and robust annotations, the description is complete for this tool's complexity. Could mention pagination or default sort, but not essential.

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 description does not need to add parameter details; it only mentions 'keyword or phrase' which aligns with the query parameter, but no extra semantic guidance beyond the schema.

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

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

Description clearly states the action (search), resource (Reddit posts), and scope (across all subreddits), and lists returned fields (titles, scores, subreddits, authors, URLs), distinguishing it from siblings like 'get_post' which retrieves a single post.

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?

Implied usage for keyword search across all subreddits, but no explicit guidance on when to use alternatives (e.g., 'search_within' for subreddit-specific search) or when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral details beyond annotations: 'every passage carries an offset so the agent can verify a verbatim quote,' plus technical details about embeddings, window size, and the 200K char cap with truncation flagging.

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

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

Description is a single dense paragraph that front-loads the purpose, then usage rationale, then integration with sibling, then technical specifics. Every sentence serves a purpose with zero waste.

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

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

Given no output schema, the description explains return format (top-N passages with offsets and scores), covers edge cases (truncation), and provides enough context for an agent to understand behavior and integrate with sibling tools.

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 well-documented in the schema. The description provides example queries and reiterates the char limit but does not add significant new meaning beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb (search), resource (a record's text), and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded for grounding.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context.' It also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.'

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

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

The description goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by detailing authentication requirements, subscription persistence constraints, delivery channel limits, and failure behavior for webhooks. No contradictions with annotations.

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

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

The description is comprehensive and front-loaded with the core purpose. It uses dashes for structure, but could be more scannable with bullet points. However, every sentence adds value; no fluff. Slightly verbose but still 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 subscription types, delivery channels, authentication constraints, and no output schema), the description is remarkably complete. It covers return value, prerequisites, parameter formats, delivery options, and edge cases like webhook auto-disable. 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?

Although schema coverage is 100%, the description adds substantial meaning: it provides concrete examples for each type (e.g., sec_8k items codes), clarifies validation rules for delivery channels (e.g., phone must be verified, webhook HTTPS only), and explains the return value (subscription id). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation. It also specifies the types of subscriptions and delivery channels.

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

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

The description provides explicit usage context: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), lists supported subscription types with example parameters, and details delivery channel constraints (e.g., SMS 10/day cap, webhook auto-disable after 10 failures). It implicitly guides when not to use (e.g., for one-off queries use 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds context about returning category-bucketed example questions with tool+argument shapes, which is useful but not essential beyond annotations.

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

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

The description is relatively long but well-structured with front-loaded key phrases. It efficiently packs all necessary information without redundancy.

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

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

Despite no output schema, the description clearly explains return value: 'category-bucketed example questions' with exact tool+argument shapes. It's comprehensive for the tool's onboarding 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% with the topic parameter described. The description adds value by explaining that omitting the parameter gives a cross-category spread and lists example focus areas.

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's the onboarding entry point for understanding Pipeworx capabilities, returning categorized example questions. It distinguishes from siblings by being the 'first use' tool for newcomers.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also notes optional topic filtering and cross-category spread, providing clear when-to-use guidance.

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

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

Adds key details beyond annotations: ownership enforcement, deactivation vs deletion, historical event retention via recent_alerts. All consistent with annotations (not destructive, idempotent).

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

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

Two sentences, front-loaded with purpose, then behavioral details. No wasted words, efficient and clear.

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

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

Given the tool's simplicity (one param, no output schema), the description covers all essential aspects: action, ownership, side effects, and relation to other tools. No gaps for typical usage.

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

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

Schema coverage is 100% with description for 'id'. Description adds that the id is a uuid returned by 'subscribe', linking to the subscription process. Adds value beyond schema.

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

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

Clearly states 'cancel a subscription by id', which is specific and directly distinguishes from siblings like 'subscribe' and 'list_subscriptions'. References 'recent_alerts' for historical context, further differentiating.

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 when-to-use (cancel subscription) and context about ownership enforcement. Implicitly says not to use for permanent deletion, but does not explicitly name an alternative tool. Slightly lacks explicit exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds that the tool returns a verdict with a citation and percent delta, and specifies the domain. This supplements the annotations without contradiction, but does not extensively reveal behavior beyond what annotations already cover.

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

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

The description is reasonably concise, starting with a clear verb and resource. It lists example intents succinctly and explains the domain and output. A minor inefficiency is the enumeration of user intents, but overall it is front-loaded and structured well.

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

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

Given the tool has one parameter and no output schema, the description adequately explains the return format (verdict, structured form, actual value, citation, percent delta) and domain (company-financial claims). This provides sufficient context 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 schema description for the single parameter 'claim' already provides examples and states it is a natural-language factual claim. The description repeats this context but does not add new meaning beyond what the schema provides. With 100% schema description coverage, baseline is 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 is for natural-language claim verification using authoritative sources. It lists example user intents and specifies the domain (company-financial claims via SEC EDGAR + XBRL). It distinguishes from sibling tools by positioning itself as a consolidated replacement for multiple sequential calls, which is unique among the listed siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the v1 limitation to company-financial claims. While it doesn't list when not to use or alternatives, the context is clear enough for the agent to decide.

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