Sefaria

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

Annotations declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context: the default model is free, Anthropic probing requires a BYO key passed directly to Anthropic, and the return format includes per-model {score, confidence, signals, raw_response} plus a combined view. No contradiction with annotations.

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

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

Two sentences with zero waste. The first sentence states the core purpose and scoring, the second explains model options and return format, followed by a list of use cases. Front-loads key information.

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

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

The description covers usage with default and optional key, cost implications, return structure (per-model and combined view), and use cases. Given no output schema, it adds sufficient context for an agent to understand what the tool does and what it returns.

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 explaining that the default model is Workers AI Llama-3.3-70b (free) and that '_apiKey' is only needed for Anthropic, with key passed straight through. It clarifies the 'models' parameter's supported values and the 'context' parameter's purpose for disambiguation.

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

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

The description clearly states it probes LLMs for entity knowledge and returns a visibility score (0-100). It distinguishes from sibling tools like 'ask_pipeworx' (platform-specific) and 'scan_competitor_ai_presence' (competitor-focused) by being a general-purpose brand/product visibility check.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly mention when not to use or provide direct alternatives among siblings.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable context about routing to 3,745 tools and returning structured answers with stable citation URIs. It does not contradict annotations. However, it could further disclose error handling or limitations.

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 usage priority, then listing domains, explaining routing, and providing concrete examples. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

Given the tool's broad scope and rich annotations, the description covers the core function, input, and output (structured answer with citations). It lacks explicit mention of behavior for ambiguous queries or missing results, but remains largely complete for an agent to use effectively.

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

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

With 100% schema description coverage, the baseline is 3. The description provides examples and clarifies that the input is natural language, but does not add new semantic details beyond the schema's property descriptions. It is adequate but not exceptional.

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 answer factual questions requiring structured data from verified sources, with specific domains listed (SEC filings, FDA, etc.). It distinguishes itself from web search by emphasizing structured data and citations. The verb 'ask' and resource 'pipeworx' are well-defined.

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

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

The description explicitly instructs to prefer this tool over web search and provides specific trigger phrases ('what is', 'look up', etc.) along with examples. However, it does not explicitly mention when to use sibling tools like 'ask_pipeworx_grounded' or other alternatives, leaving a minor gap in exclusionary guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details that it extracts answers only from tool results, returns explicit refusal reasons (enumerated as 'not_in_source', 'no_tool_match', etc.), and costs one extra LLM call. These are critical behavioral traits not conveyed by annotations alone.

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

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

The description is tight and front-loaded with the core purpose and process. Every sentence serves a clear role: distinguishing from sibling, explaining workflow, return format, usage guidelines. No unnecessary words.

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

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

Given no output schema and relatively simple parameters, the description provides complete context: explains the routing process, success/failure outputs including refusal reasons, and specifically enumerates refusal scenarios. It also contrasts with the sibling tool, making it comprehensive for an agent to decide and use 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. The description notes that question can use aliases (query, q, prompt, text, input), which adds slight clarity but does not add significant meaning beyond the schema. The description does not elaborate on parameter constraints or usage nuances.

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: 'Hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from sibling 'ask_pipeworx' by emphasizing groundedness with refusal on lack of evidence. It also details the process and return format, making the distinction 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?

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off (one extra LLM call), giving clear criteria for tool selection.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint) by detailing the tool's behavior: fan-out logic per category, response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence and closed markets, liquidity warnings, and resolution-rule risk. It is highly transparent with 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 lengthy (several paragraphs) but necessary given the tool's complexity. It is front-loaded with the main purpose and input format, then organizes details into sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). Every sentence adds value, though it could be slightly trimmed. Overall well-structured.

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

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

Despite the lack of an output schema, the description thoroughly explains all return fields (market, analysis, evidence including nested structures), covers edge cases (low-confidence match, closed markets, wide spreads, resolution-rule risk), and describes the resolver and parent event extractor. It is complete for a complex tool with many moving parts.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds minimal extra meaning beyond the schema: it gives examples of market_input (slug, URL, question text) and mentions depth in passing but does not elaborate on depth or include_raw beyond the schema's own descriptions. The added value is marginal, so a 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input type (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). The verb 'research' and resource 'bet' are specific, and the tool distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on comprehensive data gathering and analysis.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clearly guides when to use the tool. However, it does not explicitly mention when not to use it or provide alternatives (e.g., polymarket_edges for edge tracking), though siblings exist. The guidance is solid but lacks 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 indicate safe read-only operation. Description adds significant behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, and return of 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?

Description is dense and informative, front-loaded with example queries. While a single paragraph, it efficiently conveys purpose, usage, and key behaviors. Could benefit from minor structuring (e.g., bullet points) but is concise.

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

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

Given no output schema, the description adequately describes return format (paired data + citation URIs) and sorting behavior. Covers both entity types and edge cases (off-calendar fiscal years). Complex tool with good completeness.

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

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

Input schema covers both parameters with 100% description coverage. Description provides examples of valid values (tickers/CIKs for company, drug names) and hints about behavior, but does not add substantial semantic nuance beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with specific example queries and resource types. It distinguishes itself from sequential single-pack 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 instructs to prefer this over sequential lookups when comparing entities. Provides context for when to use each type (company vs drug) and what data is retrieved. However, does not explicitly mention alternatives like entity_profile for single lookups.

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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds significant context: returns verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, explicit gaps[] for unanswered facets, never invents, and returns a structured findings packet. 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 relatively long but every sentence serves a purpose. Front-loads key functionality and usage guidelines. Minor redundancy (e.g., 'in parallel' mentioned twice) but overall clear and structured.

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

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

Given complexity (3,745 tools, 884 sources, parallelism), no output schema, and only 2 parameters, the description provides complete context: returns a findings packet with citations, gaps, and pre-verified facts. Includes time estimate and account requirements.

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

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

Schema covers 100% of parameters but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8) and associated plan requirements, and clarifies that question can be broad/multi-part because decomposition is the point.

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

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

The description uses a specific verb-resource pair (multi-source research) and clearly distinguishes from sibling 'ask_pipeworx' by stating the tool decomposes broad questions into sub-questions and routes to 3,745 tools, while ask_pipeworx is 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 states when to use (broad/multi-part questions) and provides alternative (ask_pipeworx for single lookups). Also includes prerequisites (Pipeworx account, paid plan for 'thorough' depth) and time estimate (15-60s).

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, non-destructive. Description adds: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradiction.

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

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

Description is concise, front-loaded with purpose, then usage, then details. Every sentence is necessary and informative. 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?

Though there is no output schema, the description fully explains what is returned (names, descriptions, schemas with examples) and how it works (top-N, direct callable). Complete for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining multiple aliases for query (q, task, search, description) and the default/max for limit, improving clarity 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: 'Find tools by describing the data or task.' It lists specific domains like SEC filings, FDA drugs, etc., and contrasts with sibling tools by being the discovery mechanism.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context and examples.

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 include readOnlyHint, openWorldHint, idempotentHint, destructiveHint, which align with the description. The description adds beyond annotations: explains the USPTO PatentsView API sunset (May 2025) and soft-failure behavior, details return fields (cik, company_name, filings with URIs, fundamentals sorted, news via GDELT→GNews fallback, LEI via GLEIF), and limits (up to 5 filings). This gives the agent a clear picture of behavior and limitations.

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

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

Description is a single dense paragraph. It front-loads example queries and key guidance. While highly informative, it could be more structured (e.g., bullet points) for easier scanning. However, it is still relatively concise given the amount of information conveyed.

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 parameter set (2 required params, no nested objects), no output schema, and sibling tools that include resolve_entity, the description is fully complete. It covers what the tool returns, limitations, fallbacks, and prerequisites. The agent has all necessary information to use the tool effectively without ambiguity.

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

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

Schema coverage is 100% with clear descriptions (type enum 'company', value as ticker or CIK). The description adds valuable context: notes names are not supported, provides examples ('AAPL', '0000320193'), and instructs to use resolve_entity for names. This extra information helps the agent use parameters correctly beyond the schema.

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

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

Description is highly specific: it states the tool provides a full cross-source profile of US public companies, gives numerous example queries (e.g., 'Tell me about X', 'brief me on Tesla'), and lists all data sources (SEC, XBRL, USPTO, news, GLEIF). It also distinguishes from sibling tools like resolve_entity by clarifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear when-to-use. Also gives a when-not-to-use: 'names not supported (use resolve_entity first if you only have a name)'. Thus, usage guidance is explicit and helps the agent choose correctly.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, and the description aligns ('delete'). Description adds context about key-based deletion and use cases, but annotations cover the core behavioral traits well.

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

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

Extremely concise: one sentence for purpose, one sentence for usage guidance, no wasted words.

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

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

For a simple deletion tool, the description covers purpose, usage conditions, and relationships to siblings. No output schema is needed for a delete operation.

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

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

Only one parameter ('key') with a clear schema description. Description doesn't add new information beyond the schema, which already fully documents the parameter. 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 the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes from siblings 'remember' and 'recall' by explicitly pairing with them.

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

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

Provides explicit when-to-use scenarios ('context is stale, task is done, clear sensitive data') and mentions alternatives ('Pair with remember and recall'), offering excellent guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral detail: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown format. This adds context beyond annotations without contradicting them.

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

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

The description is concise: three sentences cover purpose, process, and use cases. It is front-loaded with the core action, no filler content, and every sentence adds value.

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

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

Given two parameters, no output schema, and full annotation coverage, the description adequately explains the tool's behavior and output ('single text blob ready to drop at site-root/llms.txt'). It could mention limitations or error handling, but is sufficient for the simplicity of the tool.

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

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

Schema coverage is 100%, with clear descriptions for 'url' (full URL) and 'max_links' (max number of links, default 25, max 50). The description does not add additional meaning beyond the schema, meeting the baseline expectation.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from sibling tools, which are diverse and not focused on this task.

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: getting a client's site indexed by AI, drafting llms.txt for own project, or auditing competitor AI visibility. It does not explicitly mention when not to use, but context implies it is for llms.txt generation only, and no sibling tool overlaps.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds 'Keyless' (no API key required) and the data source, which are beyond annotations and useful for the agent.

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

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

The description is two sentences, front-loaded with the main action, and contains no redundant information. Every word is meaningful.

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 lack of an output schema, the description hints at the return type (list of commentaries) but does not detail the structure. However, with full parameter coverage and annotations, it is mostly complete for a list 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%, so the description does not need to add parameter details. It includes example textual references but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists commentaries and cross-references on a passage, with examples (Rashi, Targum) and source (Sefaria's link graph). It distinguishes itself from sibling tools like get_text or search_within.

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

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

The description implies usage for retrieving commentaries on a passage but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, leaving some ambiguity.

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

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

Annotations already provide robust behavioral cues (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds 'Keyless' (no authentication needed) which is useful context beyond annotations. However, it does not describe potential pitfalls like rate limits or result formats, keeping transparency adequate but not exceptional.

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 two sentences, no redundancy, and front-loads the purpose. Every word adds value, achieving high information density without verbosity.

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 (2 parameters, no output schema, comprehensive annotations), the description covers the essential information: what it fetches, supported languages, and auth requirement. It could mention pagination or limits, but for a straightforward read tool, it 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 description coverage is 100%, so the baseline is 3. The description does not elaborate on parameter semantics beyond what the schema provides; it merely reaffirms the types of texts. No additional meaning or format details are added for the 'ref' or 'language' parameters.

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

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

The description clearly states it fetches a passage of Jewish text from Sefaria by reference, enumerating the types of texts covered (Torah, Talmud, etc.). It uses a specific verb ('Fetch') and identifies the resource ('passage of Jewish text from Sefaria'). Although sibling 'lookup_ref' exists, the description's specificity about text types and languages distinguishes it well.

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

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

The description implies usage by listing supported text categories and mentioning 'Keyless', but it does not explicitly state when to use this tool over alternatives like 'lookup_ref' or other text-fetching tools. No exclusion criteria or situational guidance is provided.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description does not add any behavioral traits beyond these, but it is consistent. A score of 3 is appropriate given the annotations cover the main behavioral aspects.

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

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

Two sentences, no wasted words, front-loaded with the main action.

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 explains return fields and usage thoroughly.

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

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

The input schema has 100% coverage for the only parameter (include_inactive). The description does not add additional meaning beyond the schema. Baseline 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the return fields, and distinguishes from siblings 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 gives explicit usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly state when not to use it, but it is clear.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds that no API key is needed ('Keyless') and specifies the return structure (validity and completions), providing useful context beyond annotations.

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

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

The description is extremely concise with two sentences that front-load the purpose and key usage details. No redundant or extra information.

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

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

For a simple validation tool with one parameter and strong annotations, the description covers the core functionality, return values, and keyless access. It is nearly complete, though missing potential error handling or limits.

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

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

The input schema covers 100% of the single parameter with a clear description. The tool description does not add new parameter details but mentions 'Keyless' and return information, which are not parameter-specific. 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 validates or autocompletes Sefaria references/titles, using specific verbs and examples. This distinguishes it from sibling tools like get_text, search_within, etc., which have different purposes.

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 indicates when to use (validate/autocomplete references) and notes it is keyless, implying no authentication needed. However, it does not explicitly mention when not to use or provide 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 are all false, but description adds critical behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against quota, and team reads digests daily. 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?

Front-loaded with purpose, then usage, then behavioral details. Every sentence earns its place without redundancy. Optimal length for detailed guidance.

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

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

For a feedback submission tool with no output schema, the description covers purpose, when to use, parameter details, rate limits, and team handling. Complete for an agent to select 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 coverage is 100%, yet description adds value by elaborating on the type enum (defines each option), describing context as optional and specifying pack/tool/vertical, and setting message expectations (1-2 sentences, 2000 chars max).

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific use cases (bug, feature, data_gap, praise) that distinguish it from sibling tools, which are all unrelated.

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 to use (bugs, features, data gaps, praise) and what not to do (don't paste end-user prompt). Provides context on team response and roadmap impact, making usage clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the data is derived from CF analytics-engine, contains no PII, and is cached for 5 minutes to 1 hour depending on window. 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 concise with five sentences covering output, three specific use cases, and data source/behavior. It is well-structured and front-loaded with the primary purpose. Every sentence adds value; no fluff.

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

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

Given the rich annotations (readOnlyHint, idempotentHint, destructiveHint) and comprehensive input schema, the description is complete. It explains the output format, use cases, source, and caching behavior. No output schema is needed as the return values are described in text.

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

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

The input schema provides 100% coverage with an enum and description for the 'window' parameter. The description adds semantic value by explaining the trade-offs: shorter windows surface what's hot, longer windows show steady-state demand. This goes beyond the schema's basic 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 that the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources ('Returns the top tools, top packs, and total call volume') and distinguishes itself from sibling tools like ask_pipeworx by focusing on aggregated usage by other agents rather than direct queries.

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

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

The description explicitly lists three detailed use cases: discovering hot data sources, confirming canonical tools, and seeing alignment of use cases. While it does not explicitly state when not to use this tool, the use cases provide clear guidance. It could improve by naming alternatives like ask_pipeworx for direct queries, but the current guidelines are 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 indicate readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds extensive behavioral context: walks child markets, checks date-axis/threshold-axis ordering, computes partition check with 3pp deviation threshold, applies Jaccard similarity anchor (>=0.30), filters placeholder slugs (>20% threshold), and performs fill check against live CLOB depth. 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 long but well-structured with labeled sections (REQUIRES, SEMANTIC ANCHOR, etc.) and front-loads the key requirement. Every sentence adds value for a complex tool, though it could be slightly more concise by omitting some examples that could be inferred.

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

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

For a complex tool with no output schema, the description fully explains inputs, behavioral details, and outputs (opportunities array, partition_check, fill check). Covers edge cases (empty args failure, low similarity, placeholder filtering, non-realizable edges). References related tool for custom sizing.

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

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

Schema coverage is 100%, so baseline 3. The description adds significant value beyond schema: explains what event and topic parameters are (slug/URL vs seed question), their behaviors (walking markets vs cross-event scanning), and detailed behavioral implications (semantic anchor, partition filter, fill check). This far exceeds the minimal 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 tool's purpose is clearly stated: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and uses specific verbs ('find', 'walks', 'computes') that differentiate it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: event for a specific market slug, topic for cross-event scanning. Warns that calling with no args fails. Recommends event mode for specific markets and notes that cross-event catches patterns missed by single-event. Mentions alternative polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is clear. The description adds valuable behavioral context, such as caching (1h at KV level), details on edge calculation, slippage, and warning flags like 24h-move warnings. It also explains that Fed bets are excluded from ranking. This goes well beyond what annotations provide.

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

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

The description is excessively long and dense, containing detailed model explanations, specific numeric thresholds, and internal design notes. While structured into segments, it could be substantially shortened to focus on essential information for agent invocation. The first sentence is effective, but the rest is verbose.

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

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

Given the tool's complexity (9 parameters, no output schema, intricate response structure), the description is remarkably complete. It explains the three response segments, their internal logic, all fields in opportunities, cache behavior, and diagnostics. Without an output schema, the description fully documents what agents can expect.

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 already has a clear description. The tool description does not add significant new meaning to the parameters beyond what is in the schema; it only provides brief additional context (e.g., 'skips opportunities that are too small'). 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly targeting the 'what should I bet on today' use case. It distinctly describes three model families and response segments, making it specific and distinguishable from siblings like polymarket_arbitrage, though it does not directly compare to 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?

The description includes context like 'Built for what should I bet on today' and explains knobs like min_liquidity and max_spread_pp for filtering, but does not explicitly state when to use this tool versus sibling tools such as polymarket_arbitrage or polymarket_kalshi_spread. There is no when-not-to-use guidance.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds significant context: it explains data source (daily snapshots), trend computation, limits (60-day TTL, daily closes), and response shape. This goes beyond what annotations provide, though not exhaustively covering all edge cases.

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

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

The description is front-loaded with purpose and is well-structured: purpose, response fields, then limits. It is lengthy but every sentence contributes useful information. Minor redundancy with schema details could be trimmed, but overall structure is effective.

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

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

Given no output schema, the description thoroughly explains the output structure (tracked with fields, expired with lifespan, snapshot dates), along with constraints (TTL, daily vs intraday). All aspects of the tool's behavior are covered, making it complete for the complexity level.

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

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

The input schema covers both parameters (days, window) with descriptions. The tool description repeats these with minor additions (max 30, default 1wk). Since schema coverage is 100%, the description adds marginal value, justifying a baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question about edge history. It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis rather than current snapshots, and describes the detailed output structure (tracked[], expired[], snapshot_dates[]).

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 state when to use this tool versus alternatives like polymarket_edges. While the contrast is implicit, there is no direct guidance on when to choose this over siblings, nor any mention of when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about walking the ladder, returning verdicts (clean/degraded/cannot_fill), and warns about directional risk. Does not contradict annotations. Adds value beyond structured fields.

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: core purpose first, then modes, then output details, then usage guidance. Every sentence provides value, though slightly long. 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?

Despite no output schema, the description thoroughly lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains basket-specific outputs (capture_ratio, thin_legs, forced_directional_risk). Complete for an agent to understand behavior and outputs.

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 elaborates on each parameter: market vs event modes, side values with defaults, size_usd meaning per mode and constraints (clamp 10–1,000,000). Adds substantial meaning 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 tool does a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and lists specific output fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by its role and usage context.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains risks of skipping it (partial fills converting arb into unhedged directional position). Provides clear when-to-use and why.

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

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

Discloses detailed behavioral traits beyond annotations: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters. No contradiction with readOnlyHint/openWorldHint/idempotentHint/destructiveHint annotations.

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

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

Well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS), but slightly long. Every sentence adds value; could trim minor redundancy but overall efficient for a complex tool.

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

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

Thoroughly covers edge cases, temporal alignment, compatibility warnings, and response structure. Without an output schema, the description fully explains what to expect, making it complete for informed tool selection.

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

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

Schema describes all three parameters (100% coverage), but the description adds crucial context: defines each mode, lists valid topic values, explains override behavior, and provides examples. Significantly enhances usability.

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 spreads between Kalshi and Polymarket for the same question. It explains two modes (topic and explicit) and distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Explicitly describes when to use each mode: topic for pre-mapped shortcuts, explicit for custom pairings. Warns that most pre-mapped topics return compatibility warnings, guiding users away from non-tradeable pairs.

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

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

Description aligns with annotations (readOnlyHint, idempotentHint, destructiveHint false) and adds context about scoping and pairing with remember/forget, enhancing transparency.

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

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

Four concise sentences, front-loaded with core functionality, 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?

Adequate for a simple tool with good annotations and schema, but lacks explicit description of return value format.

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

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

Schema covers the parameter fully; description reiterates the behavior (omit key to list) but does not add significant new detail beyond examples.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, distinguishing it from sibling tools like remember and forget.

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

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

Provides explicit use cases (look up stored context) and scoping (per identifier), though does not list when not to use or alternatives beyond paired tools.

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

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

The description adds significant behavioral detail beyond annotations: the mark_read flag behavior (flags returned events read so next call shows newer ones), the persistence of the feed, and the alternative access method. Annotations already provide readOnlyHint, idempotentHint, etc., and the description complements rather than contradicts.

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: purpose, return details, filter+mark_read, and alternative endpoint. Each sentence earns its place, front-loading the core action. No unnecessary words.

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

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

With 5 optional parameters and no output schema, the description explains filtering, mark_read effect, and an alternative endpoint. It mentions what each returned alert carries (source, citation_uri, raw payload), which is sufficient for understanding the response. Minor omission: does not explain 'limit' or 'unread_only' behavior explicitly, though these are in schema.

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 providing examples (e.g., type "sec_8k"), clarifying ISO timestamp for 'since', and explaining the effect of mark_read on subsequent calls. It does not redundantly restate all schema descriptions but enriches understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed with a specific verb+resource combination. It explicitly mentions returning recent alerts with source, citation_uri, and raw payload, 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 context for polling ("Polls work fine") and mentions an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. However, it does not compare to sibling tools like 'subscribe' or 'list_subscriptions', missing explicit when-to-use guidance versus alternatives.

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

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

Annotations already declare read-only, idempotent, open world. Description adds detailed behavior: fans out to SEC EDGAR, GDELT/GNews fallback, USPTO, and mentions API sunset. 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?

Single paragraph is dense but well-structured, front-loading purpose with example queries. Every sentence adds value without redundancy.

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

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

Despite no output schema, description explains return format (changes[], total_changes, citation URIs). Fallback behavior and source details are covered. Sufficient for agent understanding.

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

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

Schema covers all parameters. Description adds value by explaining since format with examples (ISO/relative), value as ticker or CIK, and type restriction to company.

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

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

The description clearly states the tool returns a change feed for a company, with example queries like 'What's new with X'. It distinguishes from sibling tool 'entity_profile' by specifying when to use each.

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

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

Provides explicit guidance on when to use this tool vs entity_profile, and offers typical parameter values (e.g., '30d' for since). No further guidance needed.

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 provide idempotent and non-destructive hints; description adds scoping by identifier, persistence details (authenticated persistent, anonymous 24h), which are useful 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?

Four sentences, front-loaded with purpose, each sentence adds value. Efficient but could be slightly shorter.

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 is complete: covers usage, persistence, and pairing with recall/forget.

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

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

Schema coverage is 100% and already describes key and value. Description adds examples but does not significantly add 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?

The description clearly states the tool's purpose: to save data for reuse, with specific examples (resolved ticker, address, etc.) and distinguishes from sibling tools like 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 tells when to use (when discovering something worth carrying forward) and pairs with recall/forget, but no explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds valuable context that each call cascades through several endpoints, auto-disambiguates company names, and replaces 2-3 manual lookups. 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 somewhat lengthy but well-structured: starts with example queries, then usage guidance, then detailed type breakdowns. Every sentence adds value; minor conciseness improvements possible but overall effective.

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

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

For a tool with two entity types and no output schema, the description fully explains inputs, outputs, and behavior. It covers return fields (ticker, CIK, RxCUI, citation URIs) and the cascading lookup process. No gaps given the 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%, but description adds significant meaning by providing examples of valid values (e.g., 'AAPL', '0000320193', 'ozempic') and explaining auto-disambiguation for company inputs. No parameter information is missing.

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 concrete example queries like 'What's the ticker for...' and explicitly states it resolves names to canonical identifiers. It distinguishes from sibling tools by specifying supported types (company, drug) and the outputs (ticker, CIK, RxCUI).

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?

Directly says 'Use FIRST whenever you have a name but need an ID.' Provides explicit guidance on when to use vs. manual lookups and details input acceptance for each type. Clear context on when this tool is appropriate.

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

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

Annotations already mark as read-only, idempotent, open-world. Description adds that it probes each entity with ai_visibility_check, ranks, and returns score/confidence/signal density. No contradictions. Could mention that it calls ai_visibility_check internally multiple times.

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 parenthetical. Front-loaded with purpose, followed by mechanism and use case. No redundant information. Every sentence adds value.

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

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

Given no output schema, description adequately specifies return format (ranked list with score, confidence, signal density). Explains composition with ai_visibility_check and special handling of first entity. Complete for four-parameter 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?

All parameters are described in schema (100% coverage). Description adds value by explaining that the first entity in 'entities' is treated as subject for narrative, and clarifies use of 'models' and '_apiKey'. This goes beyond 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, uses ai_visibility_check, ranks results, and surfaces most/least recognized. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Describes use case for competitive AI-marketing audits with an example question. While it implies when to use, it does not explicitly state when not to use or list alternatives, though siblings are available.

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, destructiveHint, idempotentHint, openWorldHint. The description adds valuable context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list on timeout. No contradictions with annotations.

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

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

The description is a single paragraph but front-loaded with the composite nature and purpose. Every sentence adds value, covering usage, limitations, and error handling. Could be slightly more structured with bullet points, but it is efficient and clear.

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

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

Given no output schema, the description explains return fields in detail. It covers error behavior (partial failures), performance (bundlephobia delay), and constraints (NPM only). For a tool with 2 params and no output schema, this is highly 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%. The description adds context: package accepts scoped packages, version defaults to latest. It also explains the output summary block fields, which is beyond schema. This adds value beyond the baseline of 3.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It specifies the verb 'scan' and resource 'dependency'. It also distinguishes from siblings by mentioning 'NPM ecosystem only in v1' and listing alternatives for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides when not to use (PyPI/Maven/Cargo/Go) and references sibling tools for those cases.

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 critical behavioral details beyond annotations: embedding model, chunking strategy (500-char windows), character cap (200K) with truncation and flagging, and output format (offsets, similarity scores). No contradiction.

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

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

Three sentences, concise and structured: definition, use case + output, 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?

For a 3-param tool with no output schema, description fully explains return value, constraints, and relationship to sibling tool. Complete and 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 descriptions cover all 3 params (100%). Description reinforces with examples for 'query' and defaults for 'limit', adding practical value beyond schema.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling tools like ask_pipeworx_grounded by emphasizing context-saving and offset-based verification.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear when-to-use and how-it-fits 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?

Description indicates creation of a new subscription per call, implying non-idempotent behavior, but annotations set idempotentHint=true, creating a direct contradiction. Description itself adds useful behavioral details (RSS, delivery limitations, webhook auto-disable), but the contradiction forces a score of 1 per guidelines.

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 well-structured but relatively long; could be slightly more concise without losing essential 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 3 parameters (2 required) and no output schema, description fully covers all parameters, return value, prerequisites, limitations, and delivery channel specifics, leaving no obvious gaps.

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

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

Schema coverage is 100%, and description significantly enhances meaning by providing concrete examples for each type and delivery subfield, adding constraints (SMS cap, webhook auto-disable) beyond schema.

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

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

Clearly states the verb 'create' and resource 'proactive monitoring subscription to a live-data event stream'. Distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly mentions prerequisites (Pipeworx OAuth account) and supported types. Provides context for when to use (proactive monitoring) but does not explicitly contrast with alternatives like manual polling.

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

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

The description adds rich behavioral context beyond annotations: it returns example questions with exact tool+argument shape, is non-destructive, and covers the effect of omitting or specifying a topic. Annotations already indicate readOnly and idempotent, so the description complements them.

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

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

The description is a single paragraph that is information-dense but still efficiently structured, starting with common user queries and ending with usage instructions. It could be slightly tighter but remains clear and valuable.

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

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

Given no output schema and only one optional parameter, the description fully covers the tool's purpose, behavior, and usage. It explains the output format and provides enough detail for an agent to decide when to use it.

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

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

The description enriches the schema by listing example topic values ('finance', 'pharma', etc.) and explaining that omitting the parameter yields a cross-category spread. This adds significant meaning beyond the schema's generic 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 is the onboarding entry point for a connected agent, returning category-bucketed example questions. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by advising to use this tool first.

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

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

The description explicitly advises to use this tool first when unfamiliar with Pipeworx, and to learn how to call meta-tools. It also explains when to omit or pass a topic, giving clear usage context.

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

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

Annotations indicate idempotentHint=true but no destructive hint. The description adds key behavior: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts,' which clarifies soft-delete and aligns with idempotency. 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?

Two sentences with no wasted words. The key information (action, constraint, side-effect) is front-loaded and efficiently communicated.

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 purpose, ownership constraint, and behavioral side-effect (soft-delete) completely. No gaps.

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

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

Schema coverage is 100%, and the description adds no additional parameter detail beyond 'by id.' The schema itself describes the id parameter well. 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 'Cancel a subscription by id,' specifying the action (cancel) and resource (subscription). This distinguishes it from siblings like 'subscribe' and 'list_subscriptions.'

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing a clear condition for use. It does not explicitly state when not to use, but the context is sufficient for this simple operation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the return format (verdict, structured form, actual value, citation, percent delta), the data source (SEC EDGAR + XBRL), and efficiency gains. 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 slightly lengthy but well-structured, front-loaded with example queries. Every sentence contributes value: purpose, usage, domain, return format, and efficiency benefit. 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 a single parameter with full schema coverage, no output schema, and rich annotations, the description adequately covers the tool's function, domain, use case, and output. It is sufficient for an AI agent to understand when and how to invoke it.

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

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

Schema coverage is 100% with a single 'claim' parameter having a clear description. The description reinforces the parameter's meaning with examples but does not add significant new semantic information beyond what the schema provides. 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 provides specific example queries and clearly states the tool's purpose: natural-language claim verification against authoritative sources for company-financial claims. It distinguishes from siblings by noting it replaces 4-6 sequential calls.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also defines the domain (company-financial claims). It lacks explicit when-not-to-use guidance but is clear enough given sibling context.

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