Ssb No

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds key behavioral details: returns per-model {score, confidence, signals, raw_response} + combined view, default model, and that Anthropic requires a BYO key with direct billing. No contradictions.

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

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

Three sentences, front-loaded with purpose and scoring. Every sentence is informative: purpose, model options, return format, use cases. No waste.

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

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

Given 4 parameters (all described), no output schema but return structure explained, and annotations covering safety, the description is sufficiently complete. Could mention rate limits or error scenarios, but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: clarifies default model for 'models', explains '_apiKey' usage and billing, gives example values for 'entity' and 'context'. 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 the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It uses specific verbs (probe, score) and resource (LLMs for visibility), distinguishing it from sibling tools like ask_pipeworx or entity_profile.

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

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

Explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Explains default model and when to provide an API key for Anthropic. Lacks explicit when-not-to-use comparisons to siblings but provides clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing safety profile. The description adds valuable behavioral context: returns structured answers with citation URIs, routes to multiple sub-tools, and fills arguments. No contradictions with annotations.

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

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

The description is well-structured, starting with the key guidance to prefer over web search, followed by topic list, routing explanation, and examples. It is informative without being overly verbose; each sentence adds value.

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

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

Given the tool's complexity (massive tool routing) and rich annotations, the description adequately covers usage, expected output (structured answers with citations), and provides examples. It could mention failure modes or query limitations, but is largely complete.

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

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

Schema coverage is 100% with description for 'question' and aliases. The description adds examples (Apple revenue, etc.) and clarifies that multiple field names are accepted as aliases, enhancing the schema's meaning.

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

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

The description clearly specifies the tool's purpose: it is preferred over web search for authoritative structured data on a wide range of topics. It explicitly lists examples (SEC filings, FDA data, etc.) and states it routes to 3,774 tools, making the verb+resource 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 clear context on when to use the tool ('PREFER OVER WEB SEARCH') and provides examples of suitable queries. It implies when-not-to-use (not for unstructured or opinion-based queries) but does not explicitly exclude alternatives or name sibling tools.

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

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

Adds behavioral context beyond annotations: describes hallucination resistance, structured response with refusal reasons, extra LLM call cost, and reliance only on fetched data. No contradiction with annotations.

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

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

Description is front-loaded and informative, with each sentence contributing value. Slightly lengthy but justified by the need to explain complex behavior and 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?

Given complexity (routes to many tools) and schema (simple question parameter), the description covers mechanism, return format, use cases, and limitations. No output schema needed as return format is fully described.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific details beyond what the schema already provides (question and aliases), but no omission.

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 'Hallucination-resistant answer mode for high-stakes reads' and explains the routing and extraction process. Distinguishes from sibling 'ask_pipeworx' by emphasizing exclusive use of tool result and refusal reasons.

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 answer will be quoted, cited, or acted on' and for facts like financial/legal/medical) and when to prefer alternative ('prefer ask_pipeworx for casual lookups'), including cost trade-off.

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

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

The description goes far beyond the annotations (which are all read/idempotent hints). It fully discloses the fan-out behavior to multiple data sources, classification logic, resolution matching, safety short-circuits, closed-market handling, cancellation rule risk, and tradeability warnings. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the core purpose in the first sentence. It is structured into logical sections (classifiers, fan-out examples, response shapes, safety, etc.). However, the fan-out examples and detailed explanations, while valuable, could be slightly trimmed without losing clarity.

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

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

Given the tool's complexity (3 parameters, no output schema, deep integration with external data sources), the description is exceptionally complete. It covers input processing, classification, fan-out logic, response structure, edge cases (low confidence, closed markets, wide spreads), safety, and resolution risk. The agent has enough context to use and interpret results correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds extensive semantic value. It explains the depth parameter's values (quick='2-3 sources', thorough='full fan-out'), the include_raw parameter's effect on response size and content, and the market parameter's input formats with examples. This far exceeds basic schema descriptions.

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

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

The description clearly states the tool's verb ('Research a Polymarket bet') and resource ('pulling the relevant Pipeworx data for it in one call'). It lists multiple input formats (slug, URL, question text) and provides specific use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicit guidance on when to use: 'Use for...' three specific scenarios. The description explains when NOT to rely on results (low-confidence matches, closed markets, wide spreads) and instructs the agent to inspect resolver contract fields before trusting analysis. It also details the depth parameter (quick vs thorough) and include_raw flag, giving clear context for appropriate usage.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: pulls latest 10-K data for companies (with handling of off-calendar fiscal years), FAERS data for drugs, sorted results by primary metric, and returns paired data 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 dense but well-structured, starting with example queries and then explaining functionality. Each sentence adds value, though it could be slightly more concise by grouping related details.

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

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

Given the tool's complexity (two entity types with different data sources), the description covers key aspects: usage context, data sources for each type, result sorting, and return format (with citations). No output schema exists, but the description mentions URIs. It is fairly complete for an agent's 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% with two parameters. The description adds meaning by explaining what data each entity type pulls (company: financials; drug: adverse events, approvals, trials) and specifying that values should be tickers/CIKs for companies or names for drugs, along with range constraints.

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

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

The description clearly states that this tool performs side-by-side comparisons of 2-5 companies or drugs. It uses specific verbs like 'compare' and lists example queries that distinguish it from sequential lookups. The sibling tools include 'entity_profile' and 'validate_claim', and this description makes the unique purpose 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?

The description explicitly advises to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities. It provides clear context for when to use, though it does not explicitly list exclusion criteria or alternative tools beyond the sibling list.

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

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

Beyond annotations (read-only, idempotent, non-destructive), the description explains decomposition, parallel routing, pre-verified facts with evidence and gaps[], time expectation, and that it never invents data. 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 adds value; the description is concise for its complexity, front-loads purpose, and includes critical details without redundancy.

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

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

Given no output schema, the description fully explains the returned findings packet structure (evidence, confidence, source, gaps). Also covers authentication and expected duration.

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

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

With 100% schema coverage, the description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8) and clarifying that question can be broad/multi-part. This exceeds baseline.

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

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

The description clearly states the tool performs grounded multi-source research by decomposing questions into sub-questions and routing to many tools in parallel. It distinguishes from sibling tool ask_pipeworx for single lookups.

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

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

Explicitly advises use for broad or multi-part questions, and points to ask_pipeworx for single lookups. Also mentions account requirements and paid plan for thorough depth.

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. The description adds that results include full schemas with curated examples and are ready to call directly, which is useful beyond the annotations.

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

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

Description is front-loaded with purpose and usage. The list of domains is extensive but helpful; could be slightly trimmed but is acceptable. Efficient overall.

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

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

Given no output schema, the description fully explains what is returned (top-N tools with names, descriptions, schemas, examples). Adequate for a discovery tool with clear usage context.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add significant meaning beyond the schema, but clarifies the purpose of the query parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data/task. It lists specific domains and explicitly distinguishes itself from other tools by advising to call it first when many tools are available, differentiating it from siblings like search_within or query_table.

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 ('Call this FIRST when you have many tools available and want to see the option set') and implies when not to (if you already know the tool). Provides clear context for selection.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds value by detailing the multi-source fan-out, USPTO API sunset with soft-fail behavior, and return fields (cik, filings, fundamentals, patents, news, LEI). No contradictions.

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

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

The description is a single paragraph but well-organized, starting with examples, then purpose, then details. It is slightly verbose but not wasteful; every sentence adds value. Could be more concise, but front-loaded with key info.

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

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

Despite no output schema, the description explains the structure of the return data thoroughly, including specific fields, limits (up to 5 filings), and fallback behavior (patents soft-fail). For a complex tool with multiple data sources, this is complete.

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

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

Schema coverage is 100% with descriptions. Description adds clarification: value can be ticker or zero-padded CIK, names are not supported. The enum for type is explained. This goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides example queries and lists specific data sources, distinguishing it from siblings like 'resolve_entity' and 'compare_entities'.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises when not to use: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, which cover the core behavioral traits. The description adds 'clear sensitive data' as a behavioral context, but this is a minor addition given the annotations already disclose the destructive nature.

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 sentences with no wasted words. The first sentence states the core functionality, and the second provides usage guidance and related tools. It is optimally 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 parameter and no output schema, the description covers the purpose, usage context, and related tools. The annotations cover behavioral aspects. It could mention the lack of a return value or confirmation, but that is not critical.

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 parameter 'key' has a clear description: 'Memory key to delete'. The tool description does not add any additional semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying a verb and resource. It mentions pairing with 'remember' and 'recall', which distinguishes it from related tools. However, it doesn't fully clarify what constitutes a 'memory'.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests pairing with 'remember' and 'recall', implying alternatives. But it doesn't explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds process details (fetches, extracts, emits) which are helpful but not critical behavioral traits beyond annotations.

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

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

Two sentences plus a bulleted use-case list. Front-loaded with main action, no wasted words, and well-structured for quick understanding.

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 two-parameter tool with rich annotations and no output schema, the description explains the output format (single text blob, standard format) and sufficient context for usage. Minor gap: no mention of error handling for invalid URLs.

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

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

Input schema covers both parameters with descriptions. Description does not add additional meaning beyond what schema provides, but schema coverage is 100%, 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?

Clearly states the tool generates a llms.txt file for a URL, with specific verb and resource. Distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on the llms.txt format.

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

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

Explicitly lists use cases (getting client site indexed, drafting for own project, auditing competitor). Provides clear context but does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by specifying that it returns the caller's subscriptions and lists the fields, providing useful scope information beyond what annotations offer.

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

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

The description is two sentences long, front-loads the main action, and includes all essential information without any filler. Every sentence adds value, making it efficient for an agent to parse.

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

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

Given the tool's simplicity (one optional parameter, no output schema, but return fields described), the description is complete. It covers what the tool does, what it returns, and when to use it, leaving no critical gaps for 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?

The schema has 100% coverage with a clear description for the include_inactive parameter. The tool description does not add any additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' which is a specific verb and resource. It also lists the return fields and provides context on when to use it (before adding more or to get an id for cancellation), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly mentions use cases: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear guidance on when to invoke the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Annotations are all false, but description reveals key behaviors: free, rate-limited, does not count against tool-call quota, team reads digests daily, signal affects roadmap. 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?

Concise yet comprehensive: 6 sentences covering purpose, usage guidance, team process, and rate limit. Front-loaded with key action and structured logically.

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

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

Given no output schema, the description covers all necessary context: purpose, when/why to use, parameter meanings, behavioral constraints, and expected impact. Sufficient for an agent to decide and invoke correctly.

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

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

Schema has 100% coverage with descriptions for each parameter. The description adds further context: explains enum values with examples, suggests format for message (be specific, 1-2 sentences), and provides optional context fields with examples (e.g., 'fred' for pack).

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, data gaps, or praise. It defines each feedback type with specific examples, and distinguishes from sibling tools (which are for queries, comparisons, etc.) by focusing on feedback.

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 provides when to use (bug, feature/data_gap, praise) and when not to (don't paste end-user prompt). Also mentions rate limit (5 per identifier per day) and that it's free, guiding appropriate 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 declare readOnly, idempotent, not destructive. Description adds valuable behavioral traits: self-aggregating from CF analytics engine, no PII, caching duration (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?

Three sentences, each earning its place. Front-loaded with core purpose, then use cases, then technical details. 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 simplicity (1 param, no required, no output schema), description fully covers what output contains (top tools, packs, volume), behavioral traits, and use cases. 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?

Only one parameter (window) with enum. Description adds meaning beyond schema by explaining trade-offs between shorter and longer windows. Schema coverage is 100%, so baseline 3, but description enriches it.

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

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

Clearly states it returns top tools, top packs, and call volume over a window. Distinguishes from siblings by focusing on trending data rather than generic discovery or Q&A. Provides three specific use cases.

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 (discovering hot sources, confirming canonical choice, aligning use case). Discusses window trade-offs. Lacks explicit when-not-to-use or alternatives, 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive detail: requirement for exactly one parameter, walking child markets, monotonicity checks, partition-sum computation, Jaccard similarity threshold, placeholder filtering, and fill check against live CLOB depth. It discloses conditions under which signals are suppressed (e.g., realizable_edge_pp ≤ 0). No contradictions with annotations.

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

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

The description is well-structured, starting with the requirement, then general purpose, followed by detailed explanations of each mode, semantic anchor, partition filter, response format, and fill check. It is front-loaded with key information. However, it is lengthy and densely packed with technical details (e.g., Jaccard threshold, placeholder fraction), which could be restructured or summarized for 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 lacking an output schema, the description fully explains the response structure (opportunities[], partition_check, fill check results) and covers input constraints, internal logic, and edge cases (e.g., skipped_low_similarity, placeholder filtering). It also references a sibling tool (polymarket_fill_risk) for advanced sizing, making the documentation self-contained 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%, but the description significantly enriches both parameters: it explains the single-event vs cross-event distinction, provides real-world examples of slugs and URLs, and details how each parameter is used internally (e.g., `topic` triggers semantic anchor and cross-event scanning). This goes well beyond the schema definitions.

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

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

The description clearly states the verb 'Find' and resource 'arbitrage opportunities on Polymarket'. It distinguishes between `event` and `topic` modes, and the sibling list includes related but distinct tools like polymarket_edges and polymarket_fill_risk, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use `event` vs `topic`, recommends `event` for specific markets, and explains that cross-event mode captures patterns missed by single-event. It mentions that calling with no args fails, and references a sibling tool for custom sizing. However, it does not compare to other siblings like polymarket_edges or polymarket_kalshi_spread, which slightly limits full alternative differentiation.

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

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

Despite annotations already declaring readOnly and idempotent, the description adds significant behavioral context: the three model families, edge computation details (e.g., slippage adjustment, Kelly fractions), the 24h-move warning, caching behavior (1h KV level), and diagnostics structure. This far exceeds what annotations provide.

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

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

The description is verbose (~400 words) but well-structured with sections. It front-loads the purpose and then dives into details. Some sentences could be tightened without losing clarity.

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

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

Given the tool's complexity (9 parameters, 3 model families, no output schema), the description is exceptionally thorough. It explains each segment, all opportunity fields, the response top-level including diagnostics, and even caching logic. No gaps are apparent.

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

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

Schema description coverage is 100%, so baseline is 3. The overall description adds value by explaining how parameters function as 'knobs' (e.g., tradeable-edge filters, min_partition_leg_kelly usage context). It does not repeat schema but enriches meaning.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb+resource and distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx-based edge detection.

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

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

The description provides clear context for when to use the tool ('Built for "what should I bet on today"') but does not explicitly exclude alternatives or mention when not to use it. It explains the Fed bets exclusion briefly.

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

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

Annotations indicate readOnly, openWorld, idempotent. The description complements these with limits: 60-day TTL, snapshot availability since enabling, decay from daily closes not intraday, and gaps meaning no scan. It explains the response structure and its implications (e.g., median lifespan as competition clock), providing deep behavioral insight.

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

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

The description is well-organized: purpose, key question, arguments, response fields explained, and limits. Every sentence adds value. It is front-loaded with the core idea, then details, and ends with constraints. Appropriate length for the tool's complexity.

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

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

No output schema exists, so the description fully explains the return value: tracked[], expired[], snapshot_dates[], with details on each field and how they are computed (e.g., trend, decay_pp_per_day). It also covers edge cases (gaps) and practical interpretation (lifespan clock). Comprehensive given the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions. The description adds context by calling 'window' a 'snapshot family' and specifying defaults/maxes. While redundant, it reinforces parameter meaning. Slight deviation: description says max 30, schema says clamp 2-30, but this is minor and does not detract.

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 purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (current snapshot) by focusing on time-series persistence.

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

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

The description provides a clear use case: to differentiate between fresh wide edges and old wide edges, implying usage when evaluating trade timing. It explains the meaning of response fields but does not explicitly mention when not to use it. However, the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral details: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced directional risk. No contradiction with annotations.

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

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

The description is long but well-structured with uppercase labels (SINGLE-MARKET, BASKET) and front-loaded purpose. Every part adds value, though slight tightening could improve readability. Still highly effective.

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

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

Given the tool's complexity (two modes, multiple return values, warnings), the description is thorough. It covers all necessary aspects: required parameters, default values, return fields, and risk warnings. No output schema exists, so description adequately fills that gap.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining which parameter to use for each mode, default behavior for side in basket mode, and interpretation of size_usd for buys vs sells. It complements the schema effectively.

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

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

The description clearly states the tool's function: 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes two modes (single-market and basket) and provides specific verbs and resources. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

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'. Explains why—theoretical overround not capturable on thin books, partial fills convert arb to directional risk. 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 already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: conditions for compatibility_warning (non-equivalent bet shapes, semantically unrelated events), temporal alignment check, and skipped counters. This exceeds what annotations provide.

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

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

The description is well-structured with uppercase labels for modes, response, and safety fields. It is slightly verbose but every sentence adds value and it front-loads the main 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 no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) sufficiently for an agent to understand what to expect. It covers edge cases like compatibility warnings and temporal alignment, making it complete enough for a tool of this complexity.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema by explaining the topic set, providing examples, and clarifying that explicit parameters override topic mapping. This helps the agent select and invoke correctly.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit pairing), distinguishing it from sibling tools like polymarket_arbitrage which likely operate within a single venue.

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

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

The description explains when to use each mode and provides guidance on interpreting safety fields, including a caveat that most pre-mapped topics currently return compatibility warnings. It could be more explicit about when not to use the tool, but the guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows the tool is safe. The description adds behavioral context about how omitted dimensions are handled (collapsing) and how to select values, which is beyond the annotations. This enriches understanding of the query 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 extremely concise at two sentences. The first sentence states the core purpose ('Pull data from a table'), achieving good front-loading. Every sentence serves a purpose with no wasted words.

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

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

The tool has 2 parameters with full schema coverage and annotations covering safety, but the description lacks details about the return format or structure. Although the schema mentions 'json-stat2' in the body description, the tool description itself omits this. For a data query tool, specifying the output format would improve completeness. Overall, the description is adequate but not fully comprehensive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the schema information ('id is the numeric SSB table id; body is a PxWeb query object') but adds little new meaning. It does not provide additional semantic value beyond what the schema already offers.

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

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

The description clearly states the tool's purpose: 'Pull data from a table.' It specifies the resource (table) and action (pull data), and distinguishes from the sibling tool 'table_meta' (which likely returns metadata). The details on the id and body parameters further clarify the tool's scope.

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

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

The description provides some usage guidance: 'Omitted dimensions with elimination collapse; otherwise select values per dimension.' This tells the agent how to structure the body query object. However, it does not explicitly state when to use this tool versus alternatives like table_meta, nor when not to use it. The guidance is implicit but not comprehensive.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds value by explaining the listing mode when key is omitted, scoping by identifier, and the pairing with remember/forget, which are behavioral details beyond the annotations.

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

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

The description is concise, with three sentences that each add value. It front-loads the main action and then provides usage context, examples, and sibling relationships without redundancy.

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

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

For a simple 1-parameter tool without output schema, the description covers the two modes, examples, scoping, and relationship to siblings. It lacks explicit detail on return format or error handling, but remains largely complete.

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

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

Schema coverage is 100% and the schema already describes the key parameter well. The description reinforces that omitting key lists all keys, adding slight context, but does not significantly extend beyond the schema explanation.

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 'retrieve' as a specific verb and identifies the resource as values saved via remember. It clearly distinguishes from sibling tools by naming remember and forget, and explains the two modes (retrieve by key or list all keys).

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 concrete examples (ticker, address, research notes) and states the use case: looking up stored context without re-deriving. It implies when to use (when something was saved) and mentions scoping, but does not explicitly state 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it returns the most recent alerts, explains the structure of each alert, and clarifies that mark_read modifies read state for subsequent calls. 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 concise at four sentences, front-loads the core purpose, and every sentence adds essential information. No filler or redundancy.

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

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

The tool has no output schema, but the description explains what each alert contains (source, citation_uri, payload). All five parameters are covered, and the description mentions polling suitability and an alternative access method. For a read-only retrieval tool, this is complete.

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

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

Schema coverage is 100% and each parameter has a description. The description goes further by providing an example filter ('sec_8k') and explaining the semantics of mark_read ('flag returned events read so the next call only shows newer ones'), which adds useful 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 a clear verb+resource: 'Pull fired events from your subscription feed.' It specifies exactly what is returned (source, citation_uri, raw event payload) and distinguishes the tool from the alternative GET endpoint mentioned. No ambiguity about the tool's function.

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

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

The description states 'Polls work fine' and explains the effect of mark_read, providing context for repeated usage. It does not explicitly list when not to use this tool versus sibling tools, but the sibling list includes subscription management tools, so the usage context is clear enough.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds behavioral details: multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, and return structure.

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

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

One focused paragraph with examples front-loaded. Slightly dense but every sentence adds value. Could be slightly tighter 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?

No output schema, but description fully explains return structure (changes[], total_changes, citation URIs). Covers source behavior and fallbacks. Complete for a 3-param tool.

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

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

Schema has 100% description coverage, but description adds examples for 'since' (relative shorthand, recommended default), clarifies value format, and notes type restriction.

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

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

The description clearly states the tool provides a change feed for a company over a date window, with example queries. It distinguishes from sibling entity_profile, which returns static profile.

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

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

Explicitly tells when not to use ('Use entity_profile instead...'), and provides context for typical queries. Does not compare to all siblings but covers key 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?

Disclosure beyond annotations: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. Annotations already indicate idempotentHint true and not destructive.

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

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

Four sentences, none wasted. First sentence captures core purpose, subsequent sentences add important context efficiently.

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

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

For a simple two-parameter tool with no output schema, the description covers all necessary context: storage mechanism, scope, persistence, and pairing with sibling tools.

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

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

Schema description coverage is 100%, but description adds practical examples for key format and value content, enhancing meaning 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 verb 'save data' for later reuse, with specific examples like ticker, address, preference. Distinguishes from siblings recall and forget.

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

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

Explicitly says when to use (discover worth carrying forward) and mentions pairing with recall and forget for retrieval and deletion, providing clear guidance.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint all true. The description adds context that each call cascades through several internal lookup endpoints, replacing 2-3 manual lookups. This explains efficiency and internal complexity without contradicting 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 but every sentence adds value: user-facing examples, explicit guidance, detailed output descriptions, and internal behavior note. It is well-structured and front-loaded with the most critical info (purpose and when to use).

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

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

Given no output schema, the description fully explains return values for both entity types. It covers input acceptance (ticker, CIK, name for company; brand or generic for drug) and even mentions disambiguation. The tool's complexity (2+ internal lookups) is addressed, making it 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% with 2 parameters. The description adds significant meaning beyond the schema by detailing what each type returns (e.g., ticker+CIK+company for company, RxCUI+ingredient+brand for drug) and the auto-disambiguation for company names.

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 concrete user queries like 'What's the ticker for...' and explicitly states the tool resolves names to canonical identifiers. It clearly lists supported entity types (company, drug) and distinguishes itself from siblings like entity_profile and compare_entities by focusing on identifier resolution.

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

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

The description provides explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It details what each type returns and accepts as input, but does not explicitly state when not to use it or mention alternatives beyond inferring from the sibling list.

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

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

The description goes beyond annotations by explaining the internal process (probing each entity with ai_visibility_check, ranking by score) and the output structure (ranked list with score, confidence, signal density). Annotations already indicate idempotence and read-only, which align with the description.

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

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

The description is three sentences with no wasted words. It front-loads the purpose, then provides detail and a usage example. Every sentence earns its place.

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

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

Despite having 4 parameters and no output schema, the description sufficiently explains input parameters, behavior, and output format. It addresses the tool's purpose, how it works, and what the user gets back. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in 'entities' is treated as the subject for narrative, and that 'context' disambiguates common names. This provides useful semantic context beyond parameter names.

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 a specific verb ('Compare' and 'Probes') and resource ('AI visibility across entities'). It distinguishes itself from the sibling 'ai_visibility_check' by focusing on multiple entities and ranking.

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

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

The description provides clear context for when to use the tool ('competitive AI-marketing audits'), and implies it is for multi-entity comparison. It does not explicitly state when not to use it or mention alternatives, but the context signals and sibling list make it reasonable.

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

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

Annotations already cover read-only, idempotent, non-destructive. Description adds valuable behavioral details: fans out across two sources, partial failure handling, bundlephobia slowness (5-30s), and sources_failed list. 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 information-dense but well-structured: purpose, usage, return details, limitations. Every sentence adds value, though a slight reduction in length could improve conciseness.

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

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

Given no output schema, the description fully explains the return format (summary block fields, advisory details, links, alternative versions) and partial failure behavior. No gaps for a two-parameter read-only 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 covers both parameters with 100% coverage. Description adds context for package (scoped packages accepted) and version (defaults to latest), which enhances understanding 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 defines the tool as a composite check for npm packages, using specific verbs like 'fans out' and lists concrete sources (deps.dev, bundlephobia). It distinguishes from sibling tools (none directly similar) and provides clear scope.

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

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

Explicitly states when to use the tool: when agent asks about safety, popularity, size, or cost of adding a package. Also provides negative guidance for other ecosystems, directing to deps.dev:version directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds significant value: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradiction with annotations.

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

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

Description is dense but well-structured and front-loaded with key purpose. Every sentence earns its place, though slightly longer than minimal. Efficient use of space.

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

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

Despite no output schema, the description explains return format: top-N passages with character offsets and similarity scores. Covers cap, truncation, and pairing with another tool. Complete for a search 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%. The description adds meaning beyond schema: for 'text' provides examples (SEC 10-K, article), for 'query' gives example queries, for 'limit' notes default and range. Adds practical 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 explicitly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded, noting they pair together, making the purpose very clear.

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

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

Provides clear guidance on when to use: when the record is too big for the prompt to save context. Mentions pairing with ask_pipeworx_grounded. Does not explicitly state when not to use but effectively communicates context through examples 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, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context about return value structure (child nodes with type and text) and the meaning of types 'l' and 't', which is beyond what annotations provide.

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

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

Single, dense paragraph with no wasted words. Every sentence adds value: purpose, parameter explanation, return structure, examples, and relation to siblings.

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

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

Given no output schema, the description fully documents the return format (child nodes with fields id, type, text) and the significance of types. Parameter is fully covered. 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 parameter 'path'. Description adds default behavior and examples, but does not add new semantic meaning beyond the schema's description.

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

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

The description clearly states the tool navigates the subject tree, with specific examples of paths and return structure. It distinguishes itself from siblings like table_meta and query_table by explaining that leaf table IDs are used by those tools.

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

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

Provides explicit usage context: default path is root, path examples given, and explains how to use returned IDs with other tools. No explicit when-not, but clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it creates a new subscription, returns the ID, requires authentication, details delivery channel behaviors (e.g., webhook auto-disable after 10 failures, signing secret one-time exposure), and lists type-specific filter structures. 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 approximately 100 words in two well-organized paragraphs. It front-loads the core purpose and return value, then covers prerequisites, types with examples, and delivery details. Every sentence adds meaningful information without redundancy.

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

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

The tool has 3 parameters (2 required) and no output schema. The description covers all parameters with examples and constraints, mentions the return value (subscription ID), and addresses auth prerequisites. It lacks explicit idempotency behavior and error scenarios, but given the complexity of types and delivery options, it is sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topics) and explaining delivery channel parameters with constraints (e.g., phone verification, rate limits). This goes beyond the schema's minimal 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 'Create a proactive monitoring subscription to a live-data event stream' using a specific verb and resource. It distinguishes from sibling tools like 'list_subscriptions' (list) and 'unsubscribe' (delete), making the purpose unambiguous.

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

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

The description explicitly requires a Pipeworx OAuth account, excluding anonymous users. It provides detailed usage guidance for each subscription type and delivery channel, including constraints like phone verification and SMS cap. However, it does not explicitly compare to alternative tools like 'recent_alerts' for pulling alerts.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns example questions with exact tool+argument shapes from a live catalog, and that calling without arguments yields a full spread. 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 moderately sized and well-structured, starting with example queries, then purpose, output, and usage guidance. Every sentence is valuable, though slightly verbose in listing all categories.

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 explains input, output, and usage context. The agent can correctly invoke and interpret the tool's response.

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 describes the topic parameter, and the description enriches it by listing specific values and clarifying that omitting it gives a cross-category spread. Adds meaningful context beyond the schema.

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

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

The description clearly states the tool's role as an onboarding entry point, returns category-bucketed example questions, and distinguishes it from siblings like ask_pipeworx by specifying that it suggests questions rather than answering them.

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

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

Explicitly advises to use this FIRST when the agent doesn't know what Pipeworx can do, and provides guidance on calling with or without the topic argument. Could improve by stating when not to use it, but current guidance 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 indicate a safe, idempotent read operation. The description adds context about what the tool returns (variables/dimensions, valid values), beyond the annotations. No contradictions.

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

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

The description is extremely concise with one sentence and an example, no wasted words. Front-loaded with the main 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 simple single-parameter tool and thorough annotations, the description provides sufficient context about the return content. No output schema exists, but the description covers what is returned.

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 'id' parameter, with a clear description. The tool description does not add extra semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves table definition including variables/dimensions and valid values, with a specific example for the id parameter. It effectively distinguishes from siblings like 'query_table' which would query actual 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 does not explicitly provide when to use this tool vs alternatives. It implies use when needing table metadata, but no direct comparison with siblings like 'query_table' or 'entity_profile'.

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?

Goes beyond annotations by explaining that rows are deactivated, not deleted, and that historical events remain via 'recent_alerts'. This adds valuable behavioral context not captured 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, each adding critical information with no redundancy. First sentence states action, second adds ownership and behavioral detail. Front-loaded and efficient.

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

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

Given the tool's simplicity (one param, no output schema), the description fully covers purpose, ownership constraint, and behavioral nuance. Nothing is missing for selection and invocation.

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

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

Schema coverage is 100%, and the description does not add additional meaning to the 'id' parameter beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description starts with a clear verb-resource pair ('Cancel a subscription by id'), precisely stating what the tool does. 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), giving clear context for when the tool is applicable. No mention of alternatives or when not to use, but the constraint 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 already provide readOnlyHint, idempotentHint, etc. Description adds behavioral details: returns a verdict (confirmed, refuted, etc.), extracted structured form, actual value with pipeworx:// citation, and percent delta. Also explains it replaces multiple calls. No contradiction with annotations.

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

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

Description is moderately sized, front-loaded with query examples and clear purpose. Each sentence adds information without excessive verbosity. Could be slightly more compact but overall efficient.

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

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

For a tool with one parameter and high schema coverage, the description fully explains purpose, domain, usage context, and return format. Despite no output schema, the description details what the tool returns. Complete and sufficient.

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

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

Only one parameter 'claim' with schema description. Schema coverage is 100%. Description adds value by explaining the claim is natural-language and supports specific types (revenue, net income, etc.), with examples. Thus goes 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 starts with natural-language query examples, explicitly states 'claim verification against authoritative sources', and specifies domain: company-financial claims for public US companies via SEC EDGAR + XBRL. Clearly distinguishes from siblings by noting it 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?

States 'Use whenever the agent needs to check whether something a user said is factually correct' and gives domain scope and limitations (v1 supports company-financial claims). While not explicit about when not to use, the domain limitation implies exclusion for non-financial claims. No explicit alternatives, but siblings provide other research options.

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