Magic 8 Ball

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds key behavioral details: it probes LLMs, scores per model, requires a BYO API key for Anthropic (with direct payment), and returns per-model results. 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?

Every sentence earns its place: front-loaded with core purpose, then model details, cost note, return format, and use cases. 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 no output schema, the description fully specifies return structure (per-model score, confidence, signals, raw_response + combined view). It covers all parameters, their conditions, and the tool's utility. 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 coverage is 100%, and the description supplements parameter meanings well: it explains that 'models' defaults to workers-ai, '_apiKey' is only needed for anthropic, and 'context' aids disambiguation. 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?

The description uses specific verbs ('probe', 'score') and clearly states the resource (LLMs' knowledge of a business/brand/product/topic) and output (visibility 0-100). It distinguishes from sibling tools like 'ask_pipeworx' or 'deep_research' by focusing on AI visibility measurement across multiple models.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and states default model vs. optional Anthropic probe. However, it does not explicitly mention when not to use this tool or contrast it with siblings that might seem similar (e.g., 'scan_competitor_ai_presence').

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

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

Annotations already declare read-only, idempotent, and open-world hints. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns pipeworx:// citation URIs, and is described as one fast call on every tier. This goes beyond the annotations, though it stops short of detailing failure modes or latency variance.

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 substantially longer than typical, but it earns its length by covering a broad tool with many use cases, examples, and escalation guidance. It is front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and well-structured, though slightly verbose in the middle.

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

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

For a broad question-answering tool with no output schema, this description is remarkably complete. It covers the tool's scope, how it works (routing, citations), typical use cases, examples, limitations, and when to use alternatives. An agent would be well-equipped to decide when and how to invoke it.

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

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

The schema fully documents the 'question' parameter and its aliases, so the parameter semantics baseline is high. The description supplements this with concrete example questions and the kind of natural-language input expected, aiding the agent in formulating queries. It does not restate schema details but adds contextual richness.

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

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

The description clearly identifies the tool as a question-answering system that routes to thousands of sources and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as higher-fidelity alternatives for specific needs.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', lists trigger phrases like 'what is' and 'look up', and gives a clear escalation path ('Step up only when needed') for grounded and deep research. It also clarifies how it handles news queries, leaving little ambiguity.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond those: it's a full working router (not a fallback), currently identical to ask_pipeworx, and part of an experiment with candidate routing improvements. It also discloses that results are used for comparison, which is important behavioral information. No contradiction found.

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 paragraph of three sentences, each adding distinct information: beta identity, current status, and usage guidance. It is front-loaded with the key point. Slightly wordy in places (e.g., listing all tool count) but still efficient 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 tool's complexity (a router with over 5,000 tools), the description gives sufficient context: it is identical to ask_pipeworx, currently matches the stable version, and is safe to use. There is no output schema, but the tool's output is likely the same as ask_pipeworx, which is implied. It could benefit from a brief explanation of what 'routing' means, but overall it is complete enough for an agent to use it correctly.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for the 'question' field. The description does not add extra parameter semantics beyond stating 'same arguments' as ask_pipeworx, but since the schema already fully covers meaning, a baseline of 3 is appropriate.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly distinguishes it from the stable ask_pipeworx and the grounded sibling, and the purpose is actionable: use it to get the newest routing. This is a specific verb+resource+scope description.

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 guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared to the stable router to decide merges, and notes that no candidate is currently active, so behavior matches ask_pipeworx. This clearly indicates when to choose this tool over the stable version.

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 the exact return structure, refusal reasons, extra LLM call cost, and the strict 'ONLY what the tool result contains' policy. This is rich behavioral disclosure.

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

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

The description is dense but every sentence earns its place: it front-loads the core purpose, then explains the routing and extraction, return formats, refusal cases, usage scenarios, and cost tradeoff. No fluff.

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

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

Includes success and failure return schemas, refusal reason enums, cost comparison, and explicit use-case guidance. With no output schema, the description fully compensates by documenting the response contract.

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 being aliases for 'question' and already documented in the schema. The description adds no parameter-specific detail beyond stating it 'fills arguments' in routing, which applies broadly.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers solely from tool results. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing the grounded extraction and the refusal behavior.

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

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

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' This clearly tells the agent when to select this tool over the alternative.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds extensive behavioral details: low-confidence resolution short-circuit, closed market handling, wide spread warnings, resolution-rule risk, news fallback fields, and more. 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 very long and dense with information. While well-structured with sections and examples, it could be more concise. However, 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?

Very complete given complexity: covers classifiers, fan-out examples, response shapes, resolver contract, parent extractor, news fields, safety, error handling, resolution rules, and more. No output schema, so description carries full burden and does so thoroughly.

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 market can be slug, URL, or question; depth enum values 'quick' vs 'thorough'; include_raw default false and use cases. Adds value beyond schema.

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

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

The description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', specifies input types (slug, URL, question), and details the resolution, classification, fan-out, and output. It distinguishes from sibling tools like polymarket_edges or 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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. Provides classifier and fan-out examples. Lacks explicit 'when not to use' but context is strong.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and output format with citation URIs. This provides critical behavioral context.

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

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

The description is appropriately detailed for the complexity of the tool. It front-loads common queries and then explains key details. Every sentence is informative, though it could be slightly more structured (e.g., separate sections for company vs drug).

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

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

Given the simple schema (2 params with 100% coverage), rich annotations, and no output schema, the description fully covers input examples, data sources, edge cases (fiscal year handling), sorting behavior, and output format. It leaves no obvious gaps 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% with descriptions for both parameters, but the description adds significant value: explains what type='company' and type='drug' retrieve, gives examples for values, and clarifies constraints (tickers/CIKs vs drug names, max 5 items).

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

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

The description starts with multiple natural language query examples and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. The context also implies when not to use (for single entities) without needing to state it.

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

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

The description adds rich behavioral context beyond the annotations: it guarantees gaps[] are 'never invented', explains that citations are only present when fetchable, describes semantic excerpting of large records, mentions contradictions[] for standard/thorough, and discloses latency (15-60s, up to ~90s for thorough). It also covers account limitations and the paid tier for thorough, all consistent with the readOnly/openWorld/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 long (~250 words) but front-loads critical info (account requirement, fallback tool) and structures the rest logically. Every sentence adds functional information, and the length is justified by the tool's complexity (multiple depth modes, output guarantees, timing). Slight redundancy with the schema's depth enum text keeps it from a 5.

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

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

Given the tool's complexity and the absence of an output schema, the description is impressively complete: it covers preconditions, operation mode, return format (findings packet, gaps[], contradictions[], citation_uri), edge cases (breaking news returning empty gaps), and performance expectations. This gives the agent a reliable mental model for invoking and interpreting 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?

The input schema already provides 100% coverage with detailed depth enum descriptions, so the baseline is met. The description adds value by flagging that depth:'thorough' requires a paid plan, giving example question phrasings, and clarifying that broad/multi-part questions are acceptable for `question`. This goes beyond the schema's raw definitions, though not by a wide margin.

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

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

The description clearly states the tool's purpose ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...') with a specific verb and resource, and explicitly distinguishes it from open-web search and sibling tools like ask_pipeworx. It also provides concrete example use cases, making its scope 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 gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also notes the account prerequisite and names ask_pipeworx as the alternative for unsigned-in users, covering both context 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, destructiveHint. Description adds that results include full schemas with examples and are ready to call, no second lookup needed. No contradictions.

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

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

Description is fairly concise with front-loaded purpose and usage. All sentences add value. Could be slightly shorter but still efficient.

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

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

Despite no output schema, description fully explains return format (tools with names, descriptions, full schemas, examples). Also provides context for when to call it. Complete for its purpose.

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

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

Schema coverage is 100%. Description adds value by listing aliases (task, q, description, search) and clarifying that 'query' accepts natural language. Slightly more than baseline 3.

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

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

The description clearly states it finds tools by describing data or task, returns top-N relevant tools with ready-to-call schemas. It distinguishes from sibling tools like 'deep_research' or 'search_within' by focusing on tool discovery.

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).' Provides examples of when to use. Does not explicitly state when not to use, but gives strong guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. Description adds valuable behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specifies return fields, and notes USPTO PatentsView API sunset May 2025 with soft-fail 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?

Description is information-dense but well-organized: starts with examples, then a clear purpose statement, followed by details on sources and output. Could be slightly more structured (e.g., bullet points for outputs) but remains concise and scans well.

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

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

Given the tool's complexity (multi-source aggregation) and lack of output schema, the description adequately explains what is returned (CIK, filings, fundamentals, patents, news, LEI) and covers limitations (USPTO sunset, name handling). Missing details on pagination or error handling but sufficient for selection.

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: explains type enum (only 'company'), value format (ticker or zero-padded CIK), explicitly excludes names, and references resolve_entity for name resolution. Provides examples like 'AAPL' and '0000320193'.

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

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

Description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' Examples like 'Tell me about X' / 'research Acme' illustrate the purpose. It explicitly distinguishes from sibling tools by advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.'

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

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

Explicitly says when to use: 'when the user asks for a holistic view.' Also states when not to use: 'names not supported (use resolve_entity first if you only have a name).' Provides clear alternatives and 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?

Description adds context beyond annotations (destructiveHint) by explaining appropriate usage scenarios. No contradictions.

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

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

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

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

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

Given single parameter, no output schema, and annotations, description adequately covers purpose and usage. Slight gap: could mention destructive nature explicitly if annotations were absent.

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

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

Schema coverage is 100%, and parameter description matches schema. Description adds no new meaning to the key parameter beyond what schema provides.

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

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

The description clearly states the tool deletes a memory by key, with specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly specifies when to use: when context is stale, task done, or clearing sensitive data. Names alternative tools for pairing.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral details: fetches the page, extracts title/description/key links, and outputs standard markdown. 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?

Extremely concise: two sentences plus a list of use cases. Front-loaded with the main action, 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 2 parameters with full schema coverage and annotations provided, the description is mostly complete. It explains the process and output clearly. Could be slightly more detailed on output format but sufficient.

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

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

Schema description coverage is 100% with both parameters documented. The description adds minimal new info about parameters beyond what the schema provides, only implying the URL usage and noting the max_links limit is already in 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 it generates an llms.txt file for a URL. The verb and resource are specific. However, it does not explicitly differentiate from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence', though the distinct purpose is evident.

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

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

Explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitors. Provides clear context for when to use, but does not mention when not to use or 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 already indicate read-only, idempotent, non-destructive behavior. The description adds the specific return fields, which is useful behavioral context beyond annotations.

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

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

Two sentences: first states the main action and return fields, second provides usage guidance. No wasted words, 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?

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, return values, and usage advice. It is complete for the 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?

The only parameter, include_inactive, is fully described in the input schema (100% coverage). The description does not add new semantic meaning beyond what the schema provides, so baseline score is appropriate.

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

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

The description clearly states the tool lists active subscriptions and specifies the returned fields (id, type, etc.), making the purpose distinct from siblings like subscribe or unsubscribe.

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

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

The description advises using this to review existing subscriptions before adding more or to find an id for cancellation, providing clear context but not explicitly excluding 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 already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the response type ('Returns response text') and the two optional modes (cynical, corporate), which are not covered by annotations.

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

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

Two sentences with no filler. The first sentence states the core purpose, and the second adds usage guidance and mode features. Every word serves a purpose.

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

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

Given the low complexity (3 simple parameters, output schema present), the description covers purpose, usage, and modes. It could mention that answers are random or that there is no factual basis, but it is adequate for an agent to understand the tool's role.

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%. The description complements the schema by explaining the effect of 'cynical' (negative-weighted) and 'corporate' (business jargon) beyond the schema definitions. While most meaning is already in schema, the description adds helpful context.

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

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

The description clearly states the verb ('Ask'), the resource ('yes-or-no question'), and the outcome ('get a mystical answer'). It also mentions support for cynical and corporate modes, distinguishing it from any potential 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?

The description explicitly says 'Use when you need a random decision, tie-breaker, or humorous perspective,' providing clear context for when to invoke the tool. It does not include negative guidance but is sufficient.

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

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

Annotations only indicate readOnlyHint=false. The description adds substantial behavioral context: rate-limited to 5 per identifier per day, free and does not count against tool-call quota, team reads digests daily, returns a claim_token when filed without an account, and warns not to paste end-user prompts. 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 longer than average but front-loaded with the purpose and each sentence contributes necessary guidance (boundaries, claim_token, rate limit, feedback content rules). While dense, it is well-organized and avoids fluff; the only minor redundancy is repeating the claim_token usage already in the schema.

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 covers the return behavior (claim_token and later status check), operational limits (rate limit, free), scoping (only this Pipeworx connection), and content expectations. It is fully self-contained for an agent to decide when and how to use it correctly.

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

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

The schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds extra meaning beyond the schema by explaining how to construct the message (in terms of Pipeworx tools/packs, not prompts) and clarifying the claim_token usage pattern (pass with no other arguments). This goes beyond pure schema repetition.

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

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

The description clearly states this tool reports feedback to the Pipeworx team (broken, missing, or praise) and explicitly scopes it to tools served by this connection, distinguishing it from sibling tools like ask_pipeworx or research tools. It names specific categories (bug, feature, data_gap, praise) with concrete examples, so the agent knows exactly what it is for.

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

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

Provides explicit when-to-use guidance (wrong/stale data, missing tool, praise) and when-not-to-use guidance (tools from other MCP servers, with the alternative action of filing with that server). It also explains the claim_token workflow and rate limiting, making the tool's usage context fully clear.

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

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

Annotations already indicate read-only, idempotent, and nondestructive. The description adds value by explaining data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). 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, front-loads the main purpose, and uses bullet points for use cases. Every sentence adds value with no redundancy.

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

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

While the description covers purpose, usage, and behavior, it lacks details on the exact output format or structure. Since no output schema exists, providing examples or field names would improve completeness.

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

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

Schema coverage is 100%. The description adds semantic meaning to the 'window' parameter by explaining the effect of different values: shorter windows surface hot trends, longer windows show steady-state demand.

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 verb 'returns' and the specific resources: top tools, top packs, and total call volume. It distinguishes itself from sibling tools by focusing on trending data aggregated across agents.

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 three specific use cases in bullet points, but does not explicitly exclude scenarios or name alternative tools. It gives clear context for when to use the tool.

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

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

Annotations indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral details: monotonicity checks, partition-sum logic, semantic anchor, partition filter, fill check with live CLOB depth, and condition for not trading. No contradiction. Completely discloses behavior 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 thorough but verbose, containing detailed procedural information that could be streamlined. However, it is well-structured with clear sections and front-loaded with the main purpose. Every sentence provides value, but length impacts conciseness.

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

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

Despite no output schema, the description clearly explains the structure of the response (opportunities[], partition_check) and covers all critical aspects: invocation modes, algorithmic details, fill check, and cross-event pairing rules. It also references a sibling tool for custom sizing, making it complete for a complex tool.

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

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

Schema description coverage is 100%. The description adds significant context: event mode recommended for specific market, topic for cross-event scanning, examples of slugs, and detailed explanation of each mode's behavior. It enriches 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and distinguishes among three invocation modes (no args, event, topic) with specific use cases. It differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly advises when to use each mode: no args for trending scan, event for a specific market (recommended), topic for cross-event scanning. Also warns when not to trade (realizable_edge_pp <= 0). Provides clear context 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 indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral details: model segments, caching (1h KV-level), diagnostics, and a 24h-move warning. No contradiction with annotations; significant added value.

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

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

The description is detailed but verbose, packing much information into a single paragraph. While well-structured with segments and technical details, it could be more concise for agent readability.

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

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

Despite no output schema, the description fully explains return structure (by_segment, diagnostics), tradeable-edge knobs, and caching. All essential information for correct tool invocation is provided.

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 detailed descriptions for all 9 parameters. The tool description adds context on parameter interactions but does not significantly enhance individual parameter meaning beyond the schema, justifying the baseline score.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifying the resource, action, and unique value. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker through its focus on data disagreement and model families.

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 the tool is for 'what should I bet on today' and provides guidance on knobs like min_liquidity and max_spread_pp. However, it does not explicitly compare with siblings or state when not to use it, missing some usage 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read-only behavior. The description adds value by detailing the response structure (tracked[], expired[], snapshot_dates[]), explaining the meaning of fields like trend and decay_pp_per_day, and noting limitations (TTL, snapshot gaps). No contradictions with annotations.

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

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

The description is dense but well-organized: it starts with a high-level purpose, then details the response format, and ends with limitations. While it packs a lot of information into a few sentences, it remains clear and avoids redundancy. Some extra punctuation and capitalization could be improved, but overall efficient.

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

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

Despite lacking an output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) with detailed semantics, including sub-fields like edge_pp_net time-series, trend, decay_pp_per_day, first_seen, and lifespan_days. It also covers behavior (snapshot gaps, TTL) and parameter effects. This is complete for a read-only tool with two parameters.

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%. The description adds context beyond the schema by explaining default values (days default 14, max 30; window default '1wk'), providing a purpose for each parameter (days as lookback, window as snapshot family), and clarifying constraints (days clamped 2-30). This fully compensates for any missing schema detail.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about how long an edge has existed and whether it's shrinking. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical tracking rather than just current edges.

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

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

The description explains when to use the tool (to understand edge persistence and decay) and provides a concrete example contrasting a fresh wide edge vs. a 3-week-old one. It also includes a LIMITS section indicating constraints like history depth and snapshot gaps. While it doesn't explicitly state when not to use it, the context and sibling references imply alternatives like 'polymarket_edges' for current data.

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, etc. The description adds substantial behavioral context: it walks the ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict, and explains basket fill risks like 'forced_directional_risk'. No contradictions.

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

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

The description is well-structured with bold headings and sections for single-market and basket modes. It is slightly verbose but every sentence adds value. Could be trimmed slightly but still effective.

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

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

Given no output schema and complex dual-mode behavior, the description covers return fields comprehensively (e.g., top_of_book, vwap_fill_price, slippage_pp, profit_usd, thin_legs). Explains basket risks and single-market details fully. No gaps for agent decision-making.

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 3. The description adds meaning beyond schema by explaining how size_usd interpretation differs between single-market and basket modes, and default side logic for baskets. Provides enough context to compensate for lack of enum 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 this is an edge check against live order-book depth, distinguishing single-market and basket modes. It uses specific verbs like 'Realizable-vs-theoretical edge check' and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why (thin books, partial fills, directional risk), providing clear context for alternatives.

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

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

The description extensively covers behavioral traits beyond annotations: it details the two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning with two cases, temporal_alignment, skipped counters), and explains that spreads are mathematically meaningless when temporal alignment is false. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 a clear lead sentence, followed by sections for modes, response, and safety fields. It is slightly verbose but well-organized and front-loaded with the core purpose. The information density is high, and 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?

For a tool with no output schema, the description fully explains the response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It covers all necessary operational context for a complex cross-venue spread tool, including failure modes and edge cases.

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

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

With 100% schema description coverage, the description adds significant value beyond the schema. It lists the exact 10 topic shortcuts, explains that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides, and describes how they interact. The schema examples are also reinforced.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers), and the purpose is immediately understandable and distinguishable 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 provides explicit guidance on when to use each mode, warns that most pre-mapped topics return compatibility warnings, explains the meaning of safety fields (compatibility_warning, temporal_alignment, skipped counters), and cautions that real spreads are rarer than the shortcut list suggests. This gives clear when-to-use and when-not-to-use 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 already mark readOnly, idempotent, not destructive. Description adds scoping and pairing context, adding value 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 concise sentences with no fluff. Front-loaded with core action, then usage context.

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

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

Complete for a simple read-only tool with good annotations and schema. Implicitly describes return value, no output schema needed.

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

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

Schema has 100% coverage; description adds that omitting key lists all keys, providing 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?

Description clearly states the tool retrieves a value saved via remember or lists all keys when omitted. Distinguishes from sibling tools remember and forget.

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

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

Explicitly describes when to use: look up context stored earlier. Mentions pairing with remember and forget, and scoping by identifier.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds the side-effect of mark_read:true (flags events read, so subsequent calls skip them), which is beyond what annotations convey. 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?

Reasonably concise, with the core purpose front-loaded. Each sentence adds value, though one could argue slight redundancy between 'watch' description and parameter details. Not overly verbose.

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

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

No output schema, so description compensates by detailing return fields (source, citation_uri, payload). Covers filtering, mark_read side-effect, and alternative access method. Adequate for a read-only list tool with good annotations.

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 brief descriptions. The tool description adds practical context: filter examples ('sec_8k'), ISO timestamp requirement, and the effect of mark_read on next call. This enhances understanding beyond schema alone.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing it from sibling tools like recent_changes or search_within. It enumerates key fields returned (source, citation_uri, payload), making the tool's role unambiguous.

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

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

States that polling works fine and points to an alternative HTTP endpoint for scripts/dashboards, offering context on when to choose this tool. Missing explicit when-not or comparisons to sibling tools, but the alternative mention is 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?

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds significant behavioral context: parallel calls to multiple sources, failover logic, soft-fail for USPTO, and structured return format with citation URIs. No contradictions with annotations.

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

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

The description is a single dense paragraph that efficiently conveys purpose, usage, and behavior. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for easier scanning. Still, it's concise and front-loaded with examples.

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

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

For a complex multi-source tool without output schema, the description provides return format details (changes grouped by source, total count, URIs). It covers edge cases like GDELT rate limiting and USPTO sunset. Missing details on pagination or limits, but overall complete enough for effective use.

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

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

Although schema coverage is 100%, the description enriches parameter meaning: it explains the since parameter with examples of ISO dates and relative shorthand, suggests typical monitoring usage, and clarifies value accepts ticker or CIK. This adds value beyond the schema's basic 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 specifies the tool's purpose: a change feed for a company within a time window, fanning out to multiple sources. It uses concrete examples ('What's new with X') and explicitly distinguishes from the sibling tool entity_profile, which provides static profiles instead of changes.

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

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

The description gives explicit when-to-use guidance (queries like 'what's new') and when-not-to-use (use entity_profile for static profiles). It also explains the source fan-out behavior with failover (GDELT preferred, GNews fallback) and the soft-fail for USPTO, helping the agent know what to expect.

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: scoped memory, persistence duration (24h for anonymous, persistent for authenticated), and companion tools. 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?

Three sentences, front-loaded with purpose. Every sentence adds value: purpose, usage guidance, behavioral details. No filler.

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

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

For a simple two-parameter tool with no output schema, description covers purpose, usage, persistence, scoping, and companion tools completely.

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

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

Schema coverage is 100%, so description does not need to add much. Provides example keys but no additional syntax or constraints beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb and resource. It differentiates from siblings recall and forget by naming them explicitly.

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

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

Provides explicit when-to-use guidance ('when you discover something worth carrying forward') with examples. Lacks explicit when-not-to-use instructions but context is clear.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial context: identifiers are labeled with source, unresolved identifiers are explicitly listed, and LEI/FIGI enrichment degrades gracefully without losing EDGAR data. It also mentions internal cascading through multiple endpoints, giving the agent a clear expectation of 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 dense and information-rich, but it is a single long paragraph with several redundant example phrasings at the start. It could be tightened while preserving the key details. It is not as concise as it could be.

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

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

With no output schema, the description carries the burden of explaining return behavior. It covers identifier sources, unresolved field, graceful degradation, and internal cascading. For company entities, it lists the identifiers returned but not the exact output structure; for drugs, it does specify output. This is reasonably complete but not fully exhaustive.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the schema by specifying accepted formats (ticker, CIK, name for company; brand/generic for drug) but does not introduce new parameter-related details beyond what the schema already provides.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with concrete examples and supported types. It distinguishes itself from siblings by noting it provides the IDs other tools require as input and explicitly says 'Use FIRST whenever you have a name but need an ID.'

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

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

It gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces manual lookups, implying it's the efficient choice. However, it does not explicitly mention alternatives or when not to use it, which prevents a 5.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific fields. No contradictions with annotations.

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

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

Two tightly written sentences: first states core purpose and method, second gives use case and return details. No extraneous words, front-loaded with key information.

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

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

Despite no output schema, the description clearly explains return format (ranked list with score, confidence, signal density). Mentions entity count range (2-8) and treatment of first entity, making it fully self-contained.

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

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

Schema coverage is 100%, but description adds meaning: first entity treated as subject for narrative, rest as competitors. Reinforces model options and API key requirement, adding nuance beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different method).

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 a concrete use case: competitive AI-marketing audits. Implicitly suggests not for single entity checks, but lacks explicit when-not guidance. Overall usage context is well explained.

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 it as read-only, idempotent, and non-destructive. The description adds specific details: fans out to external sources, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. 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 thorough but somewhat long. Every sentence is informative, but could be trimmed slightly for brevity while retaining all key points.

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 (composite tool with external sources, no output schema), the description fully explains the return value structure, failure behavior, and ecosystem limitations. It covers everything an agent needs.

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 are accepted and version defaults to latest. This pushes to 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 that the tool performs a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It is specific to npm and distinguishes from sibling tools like deep_research.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes NPM-only in v1 and directs other ecosystems to deps.dev versions.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. This goes beyond annotations to inform agent behavior.

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

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

The description is concise (two main sentences plus one technical detail sentence). It is front-loaded with the core purpose and then adds usage guidelines and technical specifics. No unnecessary words.

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

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

The tool has no output schema, but the description explains the return format: top-N passages with character offsets and similarity scores. It also covers limits (200K chars), embedding model, and pairing with another tool, making the description self-contained.

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

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

Schema coverage is 100%, so the description's examples for 'query' and 'limit' are supportive but not essential. The description adds context like 'natural-language query' with examples, which slightly enhances understanding beyond the schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and details like returning top-N passages with offsets. It distinguishes itself from sibling tools by focusing on searching inside existing data, not fetching new 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?

The description explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. It gives clear context but does not list when not to use or alternative tools explicitly.

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 discloses OAuth requirement, supported types with examples, delivery channel details (always-on feed, optional email/sms with caps, webhook with signing secret), and sms 10/day cap. Annotations already indicate mutation and idempotency; description adds context without contradiction.

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

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

Description is verbose but well-structured: purpose first, then requirements, types, delivery channels. Every sentence adds value, though could be slightly tighter.

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 3 params, 2 required, nested objects, and no output schema, the description covers input semantics well and mentions output (returns id). It also notes the always-on feed behavior. Sufficient for typical use.

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

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

Schema coverage is 100%, but description adds substantial meaning: explains each type's parameters, delivery options, constraints (e.g., phone must be verified, webhook secret returned once). This goes far beyond schema.

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

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

Description states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb (create) and resource (subscription), and distinguishes from siblings like unsubscribe and list_subscriptions.

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

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

Description mentions prerequisite: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It does not explicitly state when to use vs alternatives, but the prerequisite and type details guide usage.

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

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

Annotations already mark as read-only, open-world, idempotent, non-destructive. Description adds behavioral context: it returns example questions with exact tool+argument shapes, drawn from a live catalog. No contradiction with annotations; enriches them.

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

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

Description is fairly long but well-structured: starts with example queries, then explains return and usage. Every sentence adds information, but a minor reduction could improve conciseness without loss.

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

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

For a tool with no output schema, the description fully explains the return (category-bucketed example questions with tool/argument shapes) and usage modes. Annotations cover safety, so 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 coverage is 100% for the single optional 'topic' parameter. The description adds value by listing possible values (finance, pharma, etc.) and explaining that omitting it gives a cross-category spread. Above baseline 3.

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

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

The description clearly states it's an onboarding entry point for agents new to Pipeworx, returning category-bucketed example questions. It uses specific verbs ('returns', 'draws from') and distinguishes from sibling meta-tools like ask_pipeworx by instructing 'Use this FIRST'.

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

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

Explicitly says to use when 'you do not yet know what Pipeworx can do' or to learn meta-tool calling. Provides two modes: no arguments for full spread, or topic parameter for focus. No when-not needed given the clear entry-point role.

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

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

The description adds behavioral detail beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Annotations already indicate non-destructive and idempotent, but this clarifies the deactivation 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 two sentences, front-loaded with the verb, and contains no unnecessary words. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description fully explains the behavior (deactivation), ownership enforcement, and side effects (historical events available). 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 a description for 'id' as 'Subscription id (uuid) returned by subscribe.' The description mentions 'by id' and ownership enforcement, adding context but not significantly new meaning beyond the schema.

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

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

The description starts with 'Cancel a subscription by id' which is a clear verb+resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation.

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 states 'Ownership is enforced — you can only cancel your own subscriptions,' providing a clear usage condition. It implies when to use (if you own the subscription) but doesn't explicitly state alternatives or when not 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 indicate read-only, open-world, idempotent, non-destructive. The description adds crucial behavior: how claims are routed, the exact verdict list, and the critical distinction between 'could_not_verify' (check failed, not evidence) and 'unsupported' (no source covered). It also discloses the 'verification_error{stage,detail}' payload, exceeding annotation coverage.

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

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

The description is detailed but not bloated; every sentence adds necessary information. It is front-loaded with query examples and quickly moves to usage. It is longer than the ideal but the length is justified by the tool's complexity and the need to clarify ambiguous verdicts.

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

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

Given the tool's complexity (routing, multiple verdicts, error semantics) and no output schema, the description covers the return value (verdict, actual value, citation, reasoning), explains edge cases, and clarifies the two failure modes. It is complete enough for safe invocation by an 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% and both parameters are well-described, but the description adds further semantics: explains that tolerance_pct overrides the claim's implied tolerance, gives the default (implied by wording, capped at 5), and provides concrete example claims. This is valuable 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 verifies natural-language factual claims, with specific verbs like 'fact check', 'verify', 'confirm or refute'. It distinguishes from sibling tools by explaining its scope (any factual claim) and its integrated pipeline that replaces multiple 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', and distinguishes between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). However, it does not name specific alternative tools for when NOT to use it, so it stops short of a full 5.

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