Jargon Translator

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that returns include per-model {score, confidence, signals, raw_response} and a combined view, and notes that Anthropic calls require a BYO key with direct payment. No contradictions.

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

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

The description is concise (about 4 sentences), front-loaded with the main purpose, and contains no redundant information. Every sentence adds value.

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

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

Given the tool complexity (4 params, no output schema, but annotations present), the description adequately covers the return format (per-model and combined view) and cost implications. It does not detail the raw_response structure but provides sufficient context for an agent to decide to invoke the 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% with descriptions for all 4 parameters. The description adds context: explains that 'entity' is the thing to probe, 'models' lists which models, '_apiKey' is optional and passed through, and 'context' helps disambiguate. It also clarifies the default model.

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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It specifies the default model and how to include Anthropic, distinguishing it from sibling tools like 'scan_competitor_ai_presence' or 'bet_research'.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the _apiKey parameter. However, it does not explicitly state when not to use the tool or list 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?

The description discloses that the tool routes questions to many external tools, fills arguments, and returns citations, which complements the annotations by explaining behind-the-scenes behavior. It also mentions performance ('one fast call') and tier availability. No contradictions with annotations; the description aligns with the read-only and idempotent hints.

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

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

The description is dense but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). It covers purpose, usage, examples, and alternatives in a single paragraph without redundancy. While a bit verbose, all sentences contribute value.

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

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

Given the tool's complexity as a router to thousands of sources, the description provides sufficient context: what it does, when to use it, examples, and how it differs from ground and deep_research. It mentions the output includes citations, compensating for the lack of an output schema. The absence of caveats about failures is acceptable for this high-level 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?

The input schema already fully documents the single logical parameter 'question' with aliases, so the description does not need to add much. The description provides example questions that illustrate expected input format. Baseline 3 is appropriate because schema coverage is 100% and description adds no additional parameter-specific semantics beyond examples.

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 that the tool routes factual questions to the right one of 5,462 tools and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing when each is appropriate. The verb 'ask' and resource 'Pipeworx' are specific and unambiguous.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and provides extensive when-to-use criteria, listing trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', and 'current'. It also names explicit alternatives: ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, plus notes on news coverage. This is exemplary guidance.

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

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

The description goes beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by explaining the experimental nature: candidate routing improvements are enabled live when under test, and it currently matches ask_pipeworx exactly. It also states 'Falls back to nothing — this IS a full working router, just the experimental edge,' disclosing that it is fully functional despite being beta.

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

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

The description is a single paragraph of four sentences, front-loaded with the key identity ('Beta version of ask_pipeworx'). Every sentence provides relevant information about the beta status, current behavior, usage, and fallback. It is slightly longer than necessary but remains efficient and organized.

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 references 'same response shape' as ask_pipeworx, which may be sufficient for agents familiar with that sibling tool. It also explains the router's purpose and scope (5462 tools). Lacking explicit details on response format could be a gap, but the comparison to ask_pipeworx partially compensates.

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

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

Schema description coverage is 100%, so the parameters are already well-documented (question and its aliases). The description mentions 'same arguments' but adds no additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,462 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements and its experimental edge, making its purpose specific and unambiguous.

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

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

The description explicitly states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidate, currently matches ask_pipeworx exactly) and notes that results are compared against the stable router, providing clear usage context and expectations.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses return shapes, refusal reasons, the extra LLM call cost, and the grounded extraction behavior. This fully informs the agent of non-obvious behaviors.

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 a clear label and then delivers dense, non-redundant details. It is longer than strictly necessary, but each 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 no output schema, the description compensates by specifying the exact success/refusal response contract. Combined with annotations and schema, the tool is fully understood 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 covers all six parameters at 100% and aliases are self-explanatory; the description adds no parameter-specific detail, but none is needed since the schema already documents them.

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

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

Description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly states it routes like ask_pipeworx but extracts answers only from tool results. This gives a specific verb+resource and clearly distinguishes it from the sibling ask_pipeworx.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups,' providing direct when-to-use and when-not-to-use guidance with the alternative named.

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 extensive behavioral details beyond annotations: fan-out patterns per bet category, response structure (market, analysis, evidence), resolver contract with confidence levels and alternatives, parent event extraction, news fallback fields, safety short-circuits for low-confidence or closed markets, and cancellation rule parsing. All these details provide high transparency.

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

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

The description is comprehensive but quite verbose, spanning multiple paragraphs. It is well-structured with clear sections and front-loaded purpose, but could be more concise. Some details could be moved to output schema or condensed without losing meaning.

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 fan-outs, classifiers, edge cases) and lack of output schema, the description covers all necessary aspects: input types, depth, classifiers, detailed fan-out examples, response shapes, resolver contract, parent events, news fallback, safety mechanisms, and cancellation rules. It is complete enough for an agent to understand and use the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds value by providing examples for the `market` parameter (slug, URL, question text) and explaining the `depth` and `include_raw` options with recommended defaults and tradeoffs. This extra context enhances 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 clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the verb 'research' and the resource 'Polymarket bet', distinguishes from siblings by emphasizing comprehensive evidence gathering and market-vs-model comparison. Examples of usage like 'should I bet on X' clarify its purpose.

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

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

The description provides explicit usage scenarios ('Use for...') and examples of when to employ the tool. It explains the `depth` parameter for quick vs thorough research. However, it does not explicitly mention when to use alternative tools among siblings, which would be helpful.

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 extensive behavioral context beyond annotations: describes data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorted results, and return format (paired data + citation URIs). No contradiction with annotations (all readOnly, openWorld, idempotent, non-destructive).

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

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

Description is a bit long but front-loaded with examples and trigger phrases. Every sentence contributes value; minor redundancy in listing examples could be trimmed slightly.

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

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

Despite no output schema, the description explains return values (paired data + citation URIs) and covers all relevant aspects: entity types, data sources, sorting, and entity limits. Fully adequate for the tool's complexity.

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

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

Schema already has 100% coverage with descriptions. The description adds concrete examples for 'values' (tickers/CIKs vs drug names) and reinforces usage context, going beyond the schema's definition.

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 compares 2-5 companies or drugs side-by-side, using trigger phrases like 'compare X and Y'. It distinguishes from siblings by explicitly preferring over sequential lookups and mentioning it replaces 8-15 calls.

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 indicators such as trigger phrases and a strong directive to prefer this tool over sequential lookups. Lacks explicit when-not-to-use scenarios but positive guidance is robust.

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, openWorld, idempotent), the description discloses auth requirements, latency (15-60s, up to ~90s), gap handling with 'never invented' evidence, hop and contradiction scans, excerpting behavior, and citation_uri resolution guarantees. This significantly enriches the behavioral context and does not contradict 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?

Though long, the description is front-loaded with the account requirement and core purpose, then flows into alternatives, depth details, and output specifics. Every sentence contributes unique value; there is no filler or redundancy.

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

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

With no output schema, the description fully compensates by detailing the findings packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field) and edge cases like excerpting and citation fetchability. It leaves little ambiguity about what the tool returns and how it behaves.

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 substantial nuance to the `depth` parameter (quick/standard/thorough semantics, gap recovery, contradictions scan) and explains that `question` can be broad and multi-part. It builds on the schema rather than merely repeating it, though the schema already carries the baseline 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?

The description explicitly states the tool performs 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call, and distinguishes it from open-web search and the sibling ask_pipeworx. The verb and resource are specific, and it clearly names what the tool does and for whom.

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

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

It provides explicit conditional guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. This explicitly states when to use this tool versus alternatives, including exclusions.

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, which the description matches. The description adds behavioral details: returns top-N relevant tools with full schemas and curated examples, ready to call directly without a second lookup.

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

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

Two sentences with key information front-loaded. The first sentence states the purpose, the second provides usage context and expected output. The list of domains is slightly lengthy but adds clarity. Efficient overall.

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 the return format (tool names, descriptions, full input schemas with examples). Parameter count is high but all are covered in schema. The description provides sufficient context for an agent to use the tool effectively.

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

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

Schema coverage is 100% with all parameters described and aliases listed. The description mentions that query accepts natural language and aliases (task, q, search, description), but this information is already in the schema. The description adds little beyond the schema for parameter 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?

The description clearly states 'Find tools by describing the data or task' with specific verb and resource. It distinguishes from sibling tools by being the discovery/metadata tool among many domain-specific tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists example queries and domains, providing clear guidance on when to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), details returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents with soft-fail note, news, LEI), and notes the patents API sunset. 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 relatively long but each sentence adds value. It is well-structured with examples, source details, and return field enumeration. While slightly verbose, the density of information justifies the length. A minor trim could improve conciseness without losing clarity.

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

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

Given the tool's complexity (multiple data sources, conditional availability), the description is thorough. It explains the soft-fail for patents, the format of recent_filings URIs, and the fundamentals sorting. With no output schema, it effectively describes return values. For a 2-parameter tool with 100% schema coverage, this is 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%, but the description adds substantial meaning beyond the schema: it explains that value can be ticker or zero-padded CIK, gives examples ('AAPL', '0000320193'), and clarifies that type is limited to 'company'. This adds practical usage guidance not present in schema declarations.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call.' It gives specific example queries ('Tell me about X', 'research Acme') and distinguishes itself from chaining individual lookups. This is a specific verb+resource with clear differentiation from siblings.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies that names are not supported and advises using resolve_entity first. This provides clear when-to-use, when-not, and alternative tool guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and implies deletion is irreversible, enhancing understanding beyond annotations.

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

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

Three sentences: first states action, second gives usage context, third suggests pairings. No wasted words, front-loaded with purpose.

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

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

For a simple tool with one required parameter and annotations present, the description fully covers what the tool does, when to use it, and its relationship to siblings. No missing information.

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 'key' described as 'Memory key to delete'. The description's mention of 'by key' does not add new meaning beyond the schema, so baseline score of 3 applies.

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

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

The description explicitly states 'Delete a previously stored memory by key', clearly stating the verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall', indicating its complementary role.

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

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

Provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. However, no explicit when-not-to-use or alternative tools beyond the pairing mention.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context: it fetches the page, extracts title/description/key links, and outputs a single text blob. It also specifies the output destination (site-root/llms.txt). This goes beyond annotations without contradiction, fully disclosing 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 highly concise: two sentences plus a bullet list of use cases. Every sentence earns its place, with no fluff. Front-loaded with the main action and followed by details. Well-structured for quick 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?

For a tool with 2 parameters, full schema coverage, no output schema, and rich annotations, the description is complete. It explains input, process, output format, and use cases. No gaps remain for an agent to select 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?

Input schema coverage is 100% with both parameters (url, max_links) described. The description adds value by explaining that max_links defaults to 25 and max is 50, which is not in the schema but is helpful for agent usage. The url parameter is implicitly tied to 'fetches the page', reinforcing its purpose.

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 core function: generate a production-ready llms.txt file for any URL. It explains the process (fetch page, extract title/description/key links, emit standard markdown) and the purpose (AI crawler indexing). This is specific, distinguishes from siblings like 'scan_competitor_ai_presence', and includes concrete output details.

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

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

The description lists three explicit use cases (client site indexing, personal project drafting, competitor auditing) which guide appropriate usage. It does not explicitly state when not to use it or compare to alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the return value ('translation and interpretation tips') and the ability to specify direction and tone, which aligns with annotations. There is no contradiction.

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

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

The description is two sentences, front-loaded with the core purpose. Every sentence adds value without redundancy. It is concise and well-structured.

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

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

Given the simple nature of the tool, existing annotations (readOnly, idempotent, non-destructive), full schema coverage, and presence of an output schema, the description is complete. It specifies direction, tone, and return value, leaving no obvious gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description provides a natural-language explanation of the direction and ton parameters (e.g., 'jargon→plain' and list of tones), but it does not add substantial new information beyond what the schema already provides in the enum descriptions.

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

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

The description clearly states the tool's action: 'Translate between corporate jargon and plain English.' It specifies the resources (corporate jargon and plain English) and the verb (translate). Given that sibling tools are unrelated (no other translation tools), the tool is easily distinguishable.

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

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

The description explicitly mentions the key parameters for usage: direction and tone, and states what the tool returns. While it does not explicitly list when not to use it or compare to alternatives, the context is clear due to the unique nature of this tool 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by listing specific return fields and the include_inactive parameter 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?

Two sentences, no extraneous information. Purpose and usage are 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?

Tool is simple with one parameter. Description lists return fields and parameter behavior, and annotations cover safety. No gaps given complexity.

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

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

Schema coverage is 100% for the single parameter. Description does not add additional meaning beyond what the schema provides, so baseline 3 applies.

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

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

Description clearly states verb 'List', resource 'subscriptions', and scope 'caller's active subscriptions'. Distinguishes from sibling tools like subscribe/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 when to use: 'review what you're monitoring...or to find an id to cancel'. No explicit exclusion of alternatives, but clear context.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limits (5 per identifier per day), cost (free, doesn't count against quota), and processing cadence (team reads digests daily). It also tells the agent not to paste end-user prompts. These are meaningful behavioral details, though the response/confirmation behavior is not described.

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 paragraph of about 150 words, but every sentence adds distinct value: purpose, use cases, scope exclusion, formatting guidance, rate limit, and cost. It front-loads the core purpose and remains efficient for the nuance it conveys, though light formatting would improve scannability.

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 3 params, a nested context object, and no output schema, the description provides enough for an agent to decide and invoke correctly: when to use, what to include, what not to include, and operational constraints. It lacks return-value expectations, but for a feedback tool this is not a critical gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical framing guidance: describe issues in terms of Pipeworx tools/packs, don't paste the user's prompt, and maps each feedback category to concrete triggering situations. This supplements the schema's enum descriptions with actionable 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 opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the tool's purpose and distinguishes it from the sibling research/subscription tools by being the designated feedback channel.

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 when' guidance maps three scenarios (wrong/stale data, missing tool, praise) to feedback types. It also provides a clear exclusion — only for tools from this Pipeworx connection, not other MCP servers — and instructs the agent to file elsewhere, which is strong alternative guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral details: self-aggregating from CF analytics, no PII, caching 5min-1h. 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?

5 sentences, front-loaded with purpose, uses bullet-style list for use cases. Every sentence adds value. No redundancy or fluff.

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

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

Given single parameter and no output schema, description sufficiently explains inputs, outputs, caching, and use cases. Agent can confidently invoke without guessing.

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 optional parameter with enum. Description adds semantic guidance: 'shorter windows surface what's hot now; longer show steady-state demand.' This goes beyond the schema's enum list.

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

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

Clearly states the tool returns top tools, packs, and call volume over windows. Distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on trending/aggregate data.

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?

Lists three concrete use cases (discovering hot sources, confirming canonical tool, aligning use case). Implicitly tells when to use (trending) vs not. Does not explicitly mention siblings but context is clear.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details the partition check, fill check with live CLOB depth, similarity threshold, placeholder filtering, and response structure. No contradictions.

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

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

The description is structured with clear sections (modes, semantic anchor, partition filter, response, fill check), each sentence adds value, and the most critical information (purpose and argument usage) 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?

No output schema is provided, but the description fully specifies the response structure (opportunities[], partition_check fields, fill_check results). For a complex tool, this is complete and leaves no ambiguity about 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 the description adds significant meaning: event slug format, examples, and that full URLs work; topic seed question examples and cross-event behavior. This far exceeds the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and gives specific examples.

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 each argument: no args for trending scan, event for specific market, topic for cross-event. It also explains semantic anchor and partition filter constraints, and references polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnly, idempotent), the description details caching ('Cached 1h at KV level'), computation models (lognormal, GDELT, partition_overround, etc.), response structure (by_segment, diagnostics), and caveats (Fed exclusions). Fully discloses behavioral traits.

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

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

Well-structured with clear sections (purpose, model details, response, knobs) and front-loaded with key purpose. However, it is verbose with specific numerical details (e.g., 'tennis 1.02, soccer 1.10') that could be condensed without losing meaning.

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

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

Despite no output schema, the description thoroughly explains response structure (by_segment with diagnostics) and covers filtering logic, caching, and edge cases (Fed bets). Provides sufficient context for an agent to correctly interpret results and handle empty segments.

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 adds significant meaning: e.g., min_kelly 'Skips opportunities that are too small to bet sensibly', min_partition_leg_kelly explains why min_kelly doesn't apply to partitions. Each parameter gets contextual usage advice beyond schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and is 'Built for "what should I bet on today"'. It distinguishes itself from sibling tools by naming its three model families and specific use case.

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

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

Provides explicit guidance on when to use (e.g., 'discover opportunities without paging'), describes tradeable-edge knobs for filtering, and notes that Fed bets are excluded due to unreliable data. Does not explicitly contrast with sibling tools like polymarket_arbitrage but is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: history bounded by snapshot TTL, decay computed from daily closes (not intraday), and the meaning of edge_pp_net sign. No contradiction.

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

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

The description is front-loaded with purpose and structure (args, response format, limits). It is detailed but not overly verbose; every sentence adds value. Could be slightly shortened by omitting some repetition of response field names.

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 fully explains the response structure (tracked, expired, snapshot_dates fields), the meaning of decay metrics, edge sign convention, and limits. Given no output schema, this is thorough and leaves no obvious gaps for a user to understand the tool's 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 clear descriptions. The description adds value by specifying defaults (days=14, window='1wk') and clarifying clamping bounds (max 30, though schema says clamp 2-30). It also explains the window parameter as 'snapshot family'.

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

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

The description states a specific purpose: edge persistence and decay telemetry from daily snapshots, answering a precise question about edge freshness. It clearly distinguishes from sibling tools like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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

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

The description explains when to use the tool (to assess edge persistence and decay) and provides context on the significance of fresh vs. old wide edges. It also outlines limits (60-day TTL, snapshot start, daily closes only). However, it does not explicitly state when not to use it or directly contrast with alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: walks the order book ladder, returns metrics like top_of_book, vwap_fill_price, slippage_pp, verdict, and highlights risks like thin legs and forced directional risk. 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, front-loaded with purpose, and well-structured using headings like 'SINGLE-MARKET:' and 'BASKET:'. Every sentence provides necessary information without redundancy. It is concise yet comprehensive.

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 having no output schema, the description enumerates all return fields for both modes, explains the verdict system, and warns about thin legs and directional risk. It covers prerequisites, parameter modes, and use cases. For a tool of this complexity, the description is complete.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds further meaning: explains how size_usd interpretation differs between single-market (spend/proceeds) and basket (settlement notional), side default logic, and the distinction between market and event. This adds value beyond the schema, though the schema itself is already adequate.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the verb 'check' combined with 'fill risk' makes the function unambiguous. Siblings like polymarket_arbitrage and polymarket_edges are related but this tool's unique role 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?

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to rely on theoretical overround and warns about directional risk from partial fills, offering clear when-to and when-not-to instructions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds extensive behavioral context: compatibility_warning, temporal_alignment, skipped_cross_type/subtype counters, and explains spread meaningfulness conditions. 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: purpose first, then modes, response fields, safety fields, and a warning. Every sentence adds value. Could be slightly more concise but front-loading is 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 the tool's complexity (two venues, multiple modes, safety fields) and no output schema, the description is thorough. It explains return values (leg prices, spreads), compatibility checks, temporal alignment, and skipped comparisons. All likely agent questions are addressed.

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

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

Input schema has 100% description coverage and already describes parameters. The description adds meaning by explaining the effect of each parameter (topic shortcuts vs explicit tickers, overriding behavior) and the interaction between them. The schema's examples further clarify usage.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question. It distinguishes two modes ('topic' shortcuts vs explicit tickers) and explains the return value (spread in percentage points). This sharply differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (to find real spreads between venues) and includes explicit warnings: 'Real cross-venue spreads are rarer... most pre-mapped topics return compatibility_warning today.' It provides guidance on the two modes and when explicit tickers are needed, but does not explicitly list when not to use it or compare to alternatives.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds scoping detail (identifier-based) and clarifies behavior when omitting key (list all). No contradictions.

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

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

Three sentences covering main action, usage context, and pairing. Front-loaded with the core action. Could be slightly trimmed but generally 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 only one optional parameter, no output schema, and good annotations, the description adequately explains retrieval, listing, scoping, and tool relationships. Complete for a simple read tool.

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

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

Schema coverage is 100% and the schema already describes the parameter similarly ('omit to list all keys'). Description adds minimal extra meaning beyond the schema.

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

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

Clearly states the verb 'retrieve' and the resource 'value previously saved via remember', and distinguishes between retrieving a specific key and listing all keys. Implicitly differentiates from sibling tools remember and forget.

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

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

Provides context on when to use: to look up stored context without re-deriving. Mentions pairing with remember and forget, but does not explicitly state when not to use or compare to other siblings like search 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?

The description states that setting mark_read:true flags events as read, implying a state change. However, annotations declare readOnlyHint=true, indicating no side effects. This is a direct contradiction, suggesting the tool may modify data despite being labeled read-only. No other behavioral traits are disclosed 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 about five sentences, well-structured with the main purpose front-loaded. Each sentence adds relevant information (return fields, filtering, mark_read, polling). While concise, the phrase 'polls work fine' could be integrated elsewhere. Overall, no wasted words.

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

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

Given no output schema, the description adequately explains return values (source, citation_uri, payload). It covers key usage aspects: filtering, mark_read behavior, and alternative access. The tool is simple with 5 optional parameters, and the description provides enough context for complete understanding.

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

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

The input schema covers all 5 parameters with descriptions, achieving 100% schema description coverage. The description adds significant value beyond the schema: it provides an example type ('sec_8k'), explains the effect of mark_read (flagging events as read), and clarifies polling behavior. This extra context helps the agent use the tool correctly.

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: 'Pull fired events from your subscription feed.' It specifies what is returned (most recent alerts with source, citation_uri, payload) and distinguishes it from sibling tools by focusing on subscription feeds. The verb 'Pull' combined with 'fired events' is specific and actionable.

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

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

The description provides clear context for when to use the tool (to retrieve recent alerts) and includes filtering options (type, since). It also notes that polling works and gives an alternative access method for scripts/dashboards. However, it does not explicitly state when not to use this tool versus alternatives, such as list_subscriptions.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds details on data sources, fallback behavior (GDELT to GNews), and potential failures (USPTO sunset). Could clarify more about the exact return structure.

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

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

Dense but well-organized with front-loaded examples. Could be slightly shortened, but every sentence adds value.

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

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

Despite no output schema, the description explains the grouped return structure (changes by source, total count, citation URIs). Covers sources and potential issues. Complete for a query tool with 3 required params.

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

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

Schema coverage is 100%. Description adds meaning: explains 'since' accepts ISO or relative shorthand with examples, 'value' accepts ticker or CIK, and suggests typical monitoring window. This goes 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 aggregates recent changes (SEC filings, news, patents) for a company. It distinguishes itself from sibling 'entity_profile', which retrieves static profiles.

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

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

Provides explicit example queries and directs when to use 'entity_profile' instead. Also suggests typical use of 'since' parameter with '30d' or '1m'.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description adds key behavior: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

Three sentences, front-loaded with verb and resource, no wasted words. Every sentence adds unique value.

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

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

Given simple schema (2 string params, no output schema), description fully covers purpose, usage, persistence, and pairing. No gaps.

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

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

Schema coverage is 100% with descriptions. Description adds value by providing naming conventions (e.g., 'subject_property', 'target_ticker') and clarifying value as 'any text', but could include more format constraints.

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 saves data for later reuse across conversations/sessions, with concrete examples (ticker, address, preference). Distinguishes from siblings recall and forget.

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

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

Explicitly describes when to use (discover something worth carrying forward) and pairs with recall/forget for retrieval/deletion. Implicitly states when not to use by 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 mark this as read-only, open-world, idempotent, and non-destructive. The description adds meaningful behavioral context by disclosing that each call cascades through multiple lookup endpoints, returns specific fields per entity type, includes citation URIs, and auto-disambiguates inputs. There is no contradiction with annotations.

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

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

The description is front-loaded with query examples and a clear purpose statement, followed by structured type-specific details. It is somewhat verbose with repeated example phrasing, but every sentence conveys useful information; the length is justified by the need to explain two distinct entity types and their return values.

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

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

Given there is no output schema, the description fully specifies the return fields for each type (ticker, CIK, company_name; RxCUI, ingredient, brand) and mentions citation URIs. It also explains the internal cascade and that it replaces manual lookups, giving the agent a complete picture for invoking and interpreting the result.

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 enriches both parameters. It clarifies the 'type' enum with the two supported types, and for 'value' it gives concrete examples (AAPL, CIK, ozempic) and explains what input forms are accepted for each entity type, including auto-disambiguation behavior not in the schema.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with concrete examples ('ticker', 'CIK', 'RxCUI'). It clearly distinguishes from siblings by framing the output as identifiers that other tools require as input, not profiles or 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 instruction 'Use FIRST whenever you have a name but need an ID' is explicit and actionable. It also details supported entity types and input formats. However, it does not explicitly mention when not to use it or name alternative sibling tools like entity_profile, though the context signals suggest those alternatives.

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

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

Description adds significant behavioral context beyond annotations: explains internal call to ai_visibility_check, ranking logic, and output fields (score, confidence, signal density). No contradiction with annotations (idempotent, read-only, non-destructive).

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

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

Four sentences, no fluff. Front-loaded with main purpose, then details. Every sentence earns its place.

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

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

With no output schema, the description adequately explains return format (ranked list with metrics). It also describes internal process (probing each entity) and ordering convention, making the tool complete for its complexity.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining the 'subject' role of the first entity in narrative, which is not in schema. This complements the schema well.

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

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

Description uses specific verb 'compare' and resources 'AI visibility across multiple entities', clearly distinguishing from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (possibly generic comparison). It explicitly states the action of probing each entity with ai_visibility_check and ranking results.

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

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

Description provides clear usage context: 'Useful for competitive AI-marketing audits' and a motivating question. However, it does not explicitly state when not to use or name alternative tools beyond the sibling list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: partial failure handling, bundlephobia timeout (5-30s), and the sources_failed key. This goes well 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?

The description is a single, information-dense paragraph. While it packs a lot of value, it could be slightly more structured (e.g., separate lines for return fields). Nevertheless, it is front-loaded with the main purpose and every sentence adds necessary detail.

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

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

Despite no output schema, the description fully explains the return format (summary block with listed fields, per-advisory detail, links, alternative versions, sources_failed). It covers ecosystem limitation, timeout behavior, and partial failure. No gaps remain for an agent to misunderstand.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that scoped packages (e.g., '@types/node') are accepted, and that version defaults to latest. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, combining deps.dev and bundlephobia. It specifies the verb ('scan'), resource ('dependency'), and the context ('should I add this npm package to my project'). This distinctly differentiates it from sibling tools.

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

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

Provides explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This covers both when to use and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds valuable technical details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char limit 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?

Single paragraph of ~100 words, front-loaded with purpose, followed by use case and technical details. Every sentence provides useful information without redundancy or fluff.

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

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

Despite no output schema, the description explains the return format (passages with character offsets and similarity scores). It also covers truncation behavior and pairing with other tools. Minor gap: no mention of result count or pagination, but overall sufficient for a 3-param 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% with descriptions for each parameter. The description adds extra context: for 'text' it notes max ~200K chars, for 'limit' it specifies range 1-20 and default 5, and for 'query' gives concrete examples. This adds value beyond the schema.

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

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

Description clearly states the tool performs semantic search inside a fetched record, using a natural-language query to return top-N passages with offsets and scores. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining its role in retrieving smaller, relevant chunks.

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

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

Description gives explicit when-to-use advice: use when the record is too large for the prompt. It also mentions pairing with ask_pipeworx_grounded, indicating an alternative workflow. However, it does not explicitly state when not to use this tool.

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

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

Discloses behavioral traits such as the 10/day SMS cap, phone verification requirement, webhook auto-disable after 10 consecutive failures, and that the feed is always on. This adds context beyond annotations (idempotentHint=true, which is consistent). 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?

Well-structured with clear paragraphs for purpose, requirements, types, and delivery. Information is front-loaded. Slightly verbose but every sentence adds value.

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

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

Given the complexity of subscription types and delivery channels, the description covers most aspects. It mentions return value (subscription id) but lacks details on error handling or how to use the returned id. Still, it is thorough enough for an AI agent.

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 significant detail: it provides per-type params structure with examples (e.g., sec_8k with items codes), delivery constraints (phone verified, webhook signing secret, auto-disable). This goes well beyond the schema's basic definitions.

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

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

The description clearly states it 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id.' It lists supported types and delivery channels, distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Explicitly requires a Pipeworx OAuth account, stating 'anonymous + BYO cannot persist subscriptions.' It also provides scenarios for each subscription type with params examples, and delivery channel options. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Adds significant behavioral context beyond annotations: describes output format (category-bucketed questions with tool+argument shapes), live catalog source, and parameter behavior. 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?

Well-structured with typical user questions upfront, then purpose, output format, and usage instructions. No wasted sentences; every part adds value.

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

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

Complete description despite no output schema: explains output type and coverage. Covers purpose, parameter usage, and when to use. Suitable for an onboarding tool.

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

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

Schema already describes the optional topic parameter; description adds semantic value by explaining how it focuses results and listing example values. Schema coverage is 100%.

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

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

Description clearly states the tool returns category-bucketed example questions for onboarding. Uses specific verbs and resource, distinguishes from siblings by positioning as the first tool to use.

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' and explains how to call with or without a topic. Lacks explicit when-not-to-use but provides clear context.

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

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

Adds context beyond annotations: ownership enforcement, deactivation instead of deletion, and tie to 'recent_alerts'. Annotations already signal idempotent and non-destructive, but description enriches with exact 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?

Two sentences with no wasted words. Every sentence adds value: purpose, ownership constraint, and side-effect explanation.

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 purpose, ownership, mutation behavior, and cross-reference to related tools. No gaps remain.

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

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

Schema already provides full description for the single parameter 'id' (uuid from subscribe). Description does not add further parameter details beyond restating that the tool uses the id.

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 action ('Cancel a subscription by id') and resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and deactivation behavior.

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

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

Explicitly states ownership constraint and hints at when not to use (if you need historical events, use 'recent_alerts'). Could be improved by directly stating when to prefer alternative tools.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) are already present, and the description adds detailed behavioral context: the two-path routing, use of structured SEC EDGAR for financial claims, return values with verdict and citation, and fact that it replaces multiple calls. No contradictions.

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

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

The description is a single dense paragraph that front-loads examples and purpose. While informative, it could be more structured (e.g., bullet points) for easier scanning, but the length is justified by complexity.

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

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

Despite no output schema, the description fully explains the return value (verdict, actual value, citation, reasoning) and covers both processing paths. Parameter descriptions are complete and contextualized.

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%, yet the description adds substantial value: explains how tolerance_pct overrides implied tolerance and provides usage example for hallucination detection. Default tolerance mechanism is clarified.

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 verifying natural-language claims against authoritative sources, using example phrasings and distinguishing between company-financial and other claims. It differentiates from siblings by noting it replaces 4-6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct.' Describes two distinct paths, but does not explicitly list when not to use or compare to alternatives like 'ask_pipeworx_grounded'.

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