Quotable

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), description adds cost transparency (free default, BYO key for Anthropic), key handling, and return structure (per-model + combined view). No contradictions with annotations.

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

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

Two sentences, front-loaded with main action and output, followed by usage guidance and return structure. 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?

No output schema, but description fully covers return type (per-model {score, confidence, signals, raw_response} + combined view), all 4 parameters explained, and optional context usage. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: default model, BYO key usage, and context disambiguation role, justifying a 4.

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

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

The description clearly states the tool probes LLMs for visibility scores (0-100) per model, with specific verb (probe, score) and resource (business/brand/product/topic). It distinguishes from sibling Q&A tools like ask_pipeworx by focusing on visibility scoring rather than factual questions.

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 cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides default model and cost details. Does not explicitly list when to avoid, but sibling differentiation is clear from purpose.

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

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

Annotations already mark this readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context: it routes the question, fills arguments automatically, returns a structured answer with stable pipeworx:// citation URIs, and covers live news via news-feeds packs. No contradiction with annotations.

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

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

The description is front-loaded with the core directive and behavior, then provides trigger phrases and examples, then alternative routing. It is longer than strictly necessary, but the domain list and examples earn their place because they reduce ambiguity about what 'factual questions' means.

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 high-complexity router tool with no output schema, the description covers the key things an agent needs: what the tool does, when to prefer it, what input to provide, what output to expect (structured answer with citation URIs), and when to use deep_research instead. It is slightly less explicit about how ask_pipeworx differs from ask_pipeworx_beta or ask_pipeworx_grounded, but for the main selection decision it is complete.

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

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

The schema already documents the single 'question' parameter and its aliases at 100% coverage. The description adds beyond that by specifying the kinds of questions that belong in the parameter, listing trigger phrases like 'what is', 'look up', 'find', 'get the latest', and giving six concrete domain examples, so the agent can shape the input correctly.

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

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

States a clear verb+resource pair: routes the user's factual question to the right tool among 5,798 tools across 1,517 verified sources. It explicitly positions itself as the default over web search and even names deep_research as a sibling alternative for broad questions, so an agent can tell what this tool is for.

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

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

Gives explicit 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and specific examples including unemployment rate, 10-K, adverse events, patents, forecast, and clinical trials. It also names deep_research as the alternative for broad/multi-part questions, giving clear when-to-use and 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 mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context: candidate routing improvements are enabled live when under test, no candidate is currently active, and this is a full working router rather than a fallback. This goes beyond the 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 front-loaded with the tool's identity and relationship to ask_pipeworx, then efficiently explains the current experimental state and usage. Each sentence contributes useful information, though the specific tool count and date are slightly dense and could become stale.

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 router with no output schema, the description compensates by referencing the same response shape as ask_pipeworx. It also covers experimental status, current parity with the stable router, and the fact that it does not fall back to anything. It relies somewhat on the agent already understanding ask_pipeworx, but within the sibling context this is acceptable.

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

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

Schema description coverage is 100%, with the aliases and the question parameter fully documented. The description adds only that the arguments match ask_pipeworx, which is a generic reference rather than parameter-specific detail. The schema carries the burden here, so the 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 this is a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes the experimental routing edge from the stable router, leaving no ambiguity about what the tool does and how it relates to its siblings.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and explains that it currently matches ask_pipeworx because no candidate is active. It gives clear usage context, though it does not explicitly contrast with ask_pipeworx_grounded or state when not to use it.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: answers are extracted ONLY from tool result content, refusals are explicit with a full reason enum (including data_truncated and tool_error), and a verbatim-quote evidence field is always returned. It also discloses the reliability-relevant trade-off (extra LLM call). No contradiction with the annotations.

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

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

Four sentences, and every clause earns its place: purpose/differentiator, complete return contract, when-to-use, and when-not-to-use with cost rationale. The key differentiator is front-loaded in the opening phrase. The density is justified by the tool's complexity — no output schema exists, so the return-shape documentation is necessary, not padding.

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

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

With no output schema, the description fully compensates by specifying the exact success shape {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and every refusal reason. The single required parameter is documented in the schema, safety is covered by annotations, and sibling routing is clarified against ask_pipeworx. Nothing needed to invoke this tool correctly is missing.

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 schema fully documents the single conceptual parameter 'question' as natural-language text with five aliases listed. The description adds context about what the question triggers (routing across 5,798 tools, argument filling, data fetch) but no parameter-specific syntax or format details. Per the rubric, baseline 3 applies when the schema carries the load, which it fully does.

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

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

The description opens with a specific, differentiating phrase: 'Hallucination-resistant answer mode for high-stakes reads' — a distinct mode with a concrete guarantee. It identifies the resource (Pipeworx, same 5,798-tool routing as ask_pipeworx) and explicitly distinguishes itself from the sibling ask_pipeworx by the grounded-extraction behavior. The return contract (success shape vs. refusal shape) makes what this tool does 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?

Provides an explicit when-to-use rule: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also gives an explicit when-NOT-to-use rule and names the preferred alternative: 'prefer ask_pipeworx for casual lookups,' citing the concrete cost driver (one extra LLM call).

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. It details the fan-out process, response shapes, resolver contract with confidence levels, parent_event extraction, news fields with fallback, safety short-circuits, closed market handling, wide spread warnings, and cancellation rule parsing. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false).

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

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

The description is approximately 700 words, very detailed but not concise. While front-loaded with core purpose, the abundance of examples, classifiers, and edge cases makes it lengthy. Could be more structured with subsections or bullet points.

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

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

Given the tool's complexity (multiple classifiers, fan-out, response shapes), the description is extremely complete. It covers all major aspects: low-confidence matches, closed markets, wide spreads, cancellation rules, and detailed response structure. No output schema exists, so the description carries the full burden and succeeds.

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

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

Schema coverage is 100% with descriptions for each parameter (market, depth, include_raw). The tool description adds overall context but not per-parameter additional meaning beyond examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and differentiates from siblings like polymarket_edges and polymarket_arbitrage by its 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 explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides examples of fan-out and how to interpret results. However, it does not mention when not to use it or compare directly to other tools.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses specific behavior: for company type it pulls latest 10-K data with correct fiscal year handling, for drug type it pulls FAERS counts, FDA approvals, and trial counts. It also states results are sorted by primary metric and includes citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with example queries and a clear command to prefer this tool. It provides pertinent details about data sources and sorting. While it is relatively long, every sentence serves a purpose and there is no extraneous information. Minor redundancy in listing example queries could be trimmed slightly.

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

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

Given the complexity of supporting two entity types with different data sources, the description covers all essential aspects: input constraints, data provenance, sorting behavior, and output format (paired data + URIs). There is no output schema, but the description adequately describes return values. The tool's purpose and usage are fully specified.

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

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

The input schema already provides descriptions for both parameters (type enum and values array). The description enriches this by explaining what each type returns (SEC data vs. FAERS data) and gives concrete examples of valid values (tickers/CIKs for companies, drug names). Schema coverage is 100%, so the description adds moderate extra value.

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

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

The description includes multiple example queries ('Compare X and Y', 'which is bigger', 'rank these companies') and explicitly states it performs side-by-side comparison of 2–5 companies or drugs. It clearly distinguishes from siblings like entity_profile by noting it replaces 8–15 sequential lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool over alternatives. It also specifies the input patterns (e.g., tickers for companies, names for drugs) and the number of entities (2–5).

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

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

The description goes well beyond the annotations by covering auth requirements, latency expectations, the never-invent guarantee via explicit gaps[], contradictions[], hop fields, resolvable citation_uris, and semantic excerpting of large records. It does not contradict the readOnly/openWorld/idempotent annotations.

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

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

The description is long but mostly earns its length given the tool's complexity. It front-loads the account requirement and sibling alternative, but the single-lookup routing is stated twice and the dense single-paragraph format makes it harder to scan.

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?

Even without an output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citation, gaps[], contradictions[], and hop field. It also explains timing, citation fetchability, and how deep-record content is excerpted, so an agent knows what to expect and how to interpret results.

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

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

The input schema already documents both parameters fully, including the depth enum's hop behavior, default, and paid tier. The description mostly reinforces this rather than adding new syntactic meaning, though it does provide a concrete example question and contextual notes on latency and gap recovery.

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

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

The description clearly identifies a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources, decomposing questions into facets and routing them to 5,798 tools in parallel. It also distinguishes itself from open-web search and from sibling ask_pipeworx, so an agent can tell exactly what this tool does.

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?

Usage guidance is explicit: use deep_research for broad or multi-part structured-data questions, and use ask_pipeworx instead for single lookups or when not signed in. It also states the account requirement and paid plan needed for the thorough depth, leaving little ambiguity about 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool returns '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,' which expands on the response behavior beyond annotations.

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

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

The description is two sentences with no wasted words. The first sentence states the core purpose, and the second packs rich detail about return format and usage context without being 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 no output schema, the description adequately explains what is returned (tool names, descriptions, schemas with examples, ready to call) and lists example domains. It could mention pagination or error handling, but is sufficient 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% with descriptions for all 6 parameters. The description mentions query aliases ('task, q, description, search'), which is already documented in the schema. It adds no substantial new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It also lists specific domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that handle individual 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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context, though it doesn't explicitly mention when not to use it or list alternatives beyond the implicit sibling set.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses behavior: parallel fan-out across multiple sources, fallbacks like GDELT→GNews, soft-fail on USPTO patents, and the meaning of empty sections vs. failures. It also explains name resolution and private-company behavior, giving an agent an accurate model of expected outcomes.

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

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

The description is dense and every sentence carries useful information, but it is a single long paragraph with many embedded clauses and lists, which hurts scannability. It is front-loaded with examples and purpose, yet would benefit from bullets or clearer segmentation for the lengthy return-field and source-fanout 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 there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates fields, source fallbacks, resolved/unresolved behavior, and expected empty-result semantics. No critical invocation or interpretation detail appears missing.

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

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

Although the schema already covers 100% of the parameters, the description adds meaningful semantic detail: 'type' values are interchangeable, 'value' can be a ticker, zero-padded CIK, or company name, and name resolution happens via SEC EDGAR. This materially improves an agent's understanding beyond the schema alone.

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

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

The description clearly identifies a specific action and resource: producing a full cross-source profile of a US public company, triggered by phrases like 'Tell me about X' and 'brief me on Tesla.' It also distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making its role and scope clear to an agent.

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 when to prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also covers edge cases like private companies and empty FDA sections. However, it does not name specific sibling tools nor explicitly state when not to use it beyond the holistic-view framing.

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 confirms destructive nature (delete) consistent with annotations (destructiveHint=true). No contradictions; does not add beyond annotations but aligns well.

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

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

Two sentences: first sentence states purpose, second provides usage guidelines. No wasted words, front-loaded.

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

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

Simple tool with one parameter and annotations; description covers purpose, usage, and parameter. No output schema needed; complete for its complexity.

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

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

Only one parameter 'key' with description 'Memory key to delete', which matches schema. Schema coverage 100%, so baseline 3 applies; no extra semantic detail added.

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 'Delete a previously stored memory by key', using a specific verb and resource. Distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides three use cases (stale context, task done, clear sensitive data) and recommends pairing with remember and recall.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already indicate a safe, read-only, idempotent operation. The description adds process details: fetches the page, extracts title/description/links, and outputs markdown. 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 two sentences plus a bullet list, front-loading the core purpose and use cases. Every sentence adds value without redundancy or unnecessary detail.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully covers functionality, output format, and use cases. It clarifies the output as a text blob for deployment, compensating for the lack of output 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%, and both parameters (url, max_links) are described in the schema with details. The description does not add new semantic meaning beyond what is already in the schema, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: to generate a production-ready llms.txt file for any URL, enabling AI crawlers to index the site. It specifies the action, resource, and target audience, and distinguishes itself from sibling tools, none of which directly compete.

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, drafting for own project, or auditing a competitor. It guides when to use the tool but lacks explicit exclusions or alternatives, though siblings offer related but distinct functions.

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 annotations already establish read-only, idempotent, and non-destructive characteristics. The description adds meaningful behavioral context: it returns 'bio, description, and total quote count,' and reveals that the list mode is unordered and cannot be searched—information not available from 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 two sentences long, front-loaded with the primary action, and every phrase earns its place—covering the lookup mode, the fallback list mode, and the critical limitation without redundancy.

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

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

Given the presence of an output schema and full parameter descriptions, the description rounds out the context by explaining the two usage modes and the list's unordered nature. This is sufficient for a read-only lookup tool; no missing prerequisites or error scenarios are critical.

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

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

The schema descriptions fully cover both parameters (slug with pipe-separated support, limit with range and rounding), so the description adds limited semantic detail. The only extra is the usage recommendation to prefer slug, which is more about context than parameter meaning. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Look up an author by slug' and specifies the resource (authors) and the key (slug). It also distinguishes the list mode and notes the limitation ('upstream list is unordered and cannot be searched'), differentiating it from search-focused siblings like search_quotes.

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 direct usage guidance by instructing users to 'prefer passing a slug' and explaining that the list mode is unordered and non-searchable. This implies when to use slug versus list, though it does not explicitly name alternative tools or exclusion scenarios.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing return fields and the optional include_inactive parameter behavior, without contradicting annotations.

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

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

Two sentences, first states purpose, second gives 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?

Given simple input schema, no output schema, and comprehensive annotations, the description fully covers necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with a clear description for the single boolean parameter. The description does not add extra meaning beyond the schema.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists the returned fields, distinguishing it 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?

Explicitly advises use for review before adding subscriptions or to find an id to cancel, providing clear context and alternative tool reference.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying that tags are sorted by popularity, which is behavioral info not captured in annotations.

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

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

The description is two sentences with no filler. It front-loads the purpose and immediately gives actionable 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?

With zero parameters and rich annotations, the description fully covers what the agent needs to know. The output schema exists, so return value details are unnecessary.

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 tool has zero parameters, so baseline is 4. The description adds meaning beyond the schema by explaining the output (tags sorted by popularity) and its intended use.

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 all available quote tags sorted by popularity, and explicitly connects its output to the random_quote tool. This distinguishes it from siblings like random_quote and search_quotes.

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 implicitly guides usage by stating when to retrieve tags and how to use them with random_quote. It does not explicitly state when not to use it or list alternatives, but the purpose is clear enough.

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

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

Beyond the annotations (which are all false, indicating the description carries the burden), it discloses that filing without an account returns a claim_token, how to later use that token to check status, the rate limit (5 per identifier per day), that it is free, and that it does not count against the tool-call quota. This is rich behavioral context with no contradiction to 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?

Although the description is long, every sentence serves a purpose: purpose, use cases, exclusions, token mechanism, rate limit, and cost. It is front-loaded with the core purpose and then flows logically into guidelines and consequences. No wasted words.

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

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

The description fully covers the tool's behavior for an agent: what it does, when to use, exclusions, token flow, rate limits, and expected team response. It is complete even without an output schema, and it stands out clearly among the sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic guidance: it scopes the feedback to tools served by this Pipeworx connection, instructs describing issues in terms of Pipeworx tools/packs, and explicitly says not to paste the end-user's prompt. These constraints are not fully captured in the schema and add real value.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from sibling tools by focusing on feedback submission rather than research or queries, and it enumerates the exact triggers (bug, feature/data_gap, praise).

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 (bug, feature/data_gap, praise) and a clear when-not-to-use exclusion: tools from a different MCP server. It also directs the user to file elsewhere for external server issues and gives practical instructions about what to include (Pipeworx tools/packs) and what to avoid (end-user prompt).

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, open-world, idempotent, non-destructive traits. Description adds valuable context: data derived from CF analytics-engine, no PII, caching 5min-1h. No contradictions.

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

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

Concise, front-loaded with purpose, then use cases, then technical details. Every sentence adds value with no wasted words.

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

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

Covers purpose, usage, data source, privacy, caching. The only gap is the exact return structure (e.g., object fields), but the description states what is returned conceptually. Adequate for a simple tool.

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

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

The input schema already fully describes the single parameter with enum values and meaning. The main description adds no extra parameter guidance beyond mentioning windows exist. High schema coverage (100%) sets baseline at 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?

Clearly states the tool returns top tools, top packs, and total call volume over configurable windows. Distinguishes from siblings like discover_tools by focusing on trending usage.

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 three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and explains window choices (shorter for hot, longer for steady-state). No alternatives 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?

Provides extensive behavioral details beyond annotations: monotonicity checks, partition-sum checks, semantic anchor Jaccard similarity, placeholder filter, fill check with theoretical vs realizable edge. It warns against unexecutable trades. Annotations (readOnly, openWorld, idempotent, non-destructive) are consistent with description.

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

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

Well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) for readability. However, the description is quite lengthy; while justified by complexity, a slightly more concise presentation could improve efficiency.

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 details the response structure (opportunities[], gap_pp, suggested_trade, reasoning, partition_check, fill_check). It covers edge cases and limitations, making it self-contained for a complex tool.

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

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

The description adds significant meaning beyond the input schema: explains event accepts slugs or URLs, topic is a seed question, and provides usage recommendations. Schema coverage is 100%, and the description enriches parameter 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 finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event) and differentiates from sibling tools by focusing on arbitrage detection methods.

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 for each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It explains when to use cross-event over single-event and directs to polymarket_fill_risk for custom sizing. It also advises not to trade when fill check shows zero realizable edge.

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 extensive behavioral context: five model families, response structure, caching, and diagnostics. It also notes that Fed candidates are excluded due to unreliable data, providing transparency 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 long but well-organized with sections and bullet points. Every sentence adds value, though it could be slightly more concise given the density of information.

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

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

Despite no output schema, the description thoroughly explains the response structure including segments, knobs, and diagnostics. It also covers caching and caveats about Fed data, 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?

Schema coverage is 100%, but the description adds significant value for each parameter, such as suggesting slippage adjustments for thin partitions and explaining why min_kelly does not filter partition arbs. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the resource (Polymarket markets) and the action (scanning returning opportunities), and the purpose is distinct from siblings like polymarket_arbitrage.

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

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

The description explicitly says it's built for 'what should I bet on today' and mentions that agents discover opportunities without paging hundreds of markets. However, it does not mention when not to use it or compare with alternatives among siblings, though the context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and no destructive action. The description adds extensive behavioral details: response structure (tracked, expired, snapshot_dates), that snapshots are written on cache-miss (gaps mean no scan), decay from daily closes, and history bounds. 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 front-loaded with purpose and includes all necessary details: args, response, limits. While somewhat dense, every sentence serves a purpose. Better structuring (e.g., bullet points for response) could improve, but it is efficient for 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 tool's complexity, the absence of an output schema, and the richness of the input schema, the description fully explains what the tool does, its inputs, outputs, and constraints. It covers both the data returned and caveats like snapshot gaps and decay derivation.

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 context beyond schema names: for 'days' it explains lookback range and default, and for 'window' it explains snapshot family. This enriches the bare parameter descriptions.

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

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

The description states a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question: 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from siblings like polymarket_edges (which likely provides current edges) and polymarket_arbitrage.

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

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

The description gives clear context for when to use the tool (e.g., distinguishing a fresh wide edge from an old one) and explains limits like the 60-day snapshot TTL. However, it does not explicitly state when not to use it or name alternatives like polymarket_edges for current data.

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

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

The description details behavioral traits beyond annotations: it explains the two modes, required parameters (one of market/event), return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict), and warns about risks like thin legs and forced directional risk. This adds context that annotations (readOnlyHint, destructiveHint) do not cover.

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

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

The description is well-structured: a one-sentence summary, followed by clear sections for SINGLE-MARKET and BASKET modes with bold headings. Every sentence adds value, and it ends with a concise usage recommendation. No redundancy or 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 the tool's complexity (two modes, no output schema), the description fully explains inputs, behavior, outputs, and risks for both modes. It lists all return fields, default values, constraints (size_usd clamp), and critical warnings. This covers all necessary context for an agent to use the tool correctly.

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

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

Although schema coverage is 100%, the description enriches parameter meaning: it explains size_usd differently for single-market vs basket ('max spend on buys, target proceeds on sells' vs 'settlement notional'), clarifies side defaults ('auto' for basket), and notes that one of market/event is required despite schema not marking them required.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by recommending its use before acting on their signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills create directional risk).

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses significant behavioral caveats: Kalshi fees are not modeled, spreads are gross, compatibility_warning and compatibility_codes can be non-empty even when matches exist, unclassified legs are skipped, null temporal alignment does not mean aligned, and pairing is based on keyword overlap rather than a shared resolver. This far exceeds what annotations alone 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 dense and long, but almost every sentence adds a distinct caveat, mode detail, or safety disclosure that is necessary for correct use. It front-loads purpose and modes, though the flow of safety fields and warnings could be tightened without losing information.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains response fields, matching behavior, compatibility codes, skipped-leg counters, temporal alignment semantics, fee limitations, and the key caveat that pre-mapped topics are not automatically tradeable.

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

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

The schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful parameter semantics: topic auto-fetches the matching event on each venue, explicit event ticker/slug parameters override the topic-mapped sides, and both invocation modes use the same matching logic.

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

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

The description states a specific verb-plus-resource purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling arbitrage/edge tools by emphasizing that the spread is gross, not a net tradeable edge, and by naming the two venues explicitly.

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

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

It provides explicit two-mode usage semantics: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug, and states that both modes run the identical token-overlap matcher. It warns that most pre-mapped topics currently return compatibility warnings, but it does not name sibling tools as alternatives or say when to use this instead of a related venue tool.

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

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

With annotations indicating read-only, idempotent, and non-destructive behavior, the description adds useful context: returns quote text, author, and tags, and tags come from a fixed list. This goes beyond annotations and clarifies the response shape and tag source. No contradiction found.

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

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

Two concise sentences that front-load the primary action, include filter examples, return contents, and a valuable tag-list tip. No redundant wording, every sentence earns its place.

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

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

Given the tool's simplicity, the description covers the core purpose, optional filters, return contents, and the tag prerequisite. An output schema exists, so return details are not required. It could mention the default limit or the random nature per call, but the description is already sufficient for most use cases.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters. The description's mention of 'tag' and 'author slug' aligns with the schema but adds no new semantics. The fixed-list note is also present in the schema, so the description contributes minimal additional parameter meaning.

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

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

The description clearly states the tool's function: 'Get a random quote' with optional filters by tag or author slug. It also mentions return contents (quote text, author, tags), making the purpose explicit. It doesn't explicitly differentiate from sibling search_quotes, but the random nature is 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 gives clear usage context: use when you want a random quote, optionally filtered. It also provides a direct pointer to list_tags as a prerequisite for tags, which is helpful. However, it doesn't explicitly mention when not to use this tool or alternatives like search_quotes, so it's not a full 5.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: scoping ('Scoped to your identifier...'), behavior when key omitted (list all), and pairing with remember/forget. 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 compact and well-structured: first sentence states the main action, then elaborates on when to use, scoping, and sibling pairing. Every sentence adds value with no wasted words.

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

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

Given no output schema, the description adequately explains what is returned (a value or list of keys) and mentions scoping. For a read-only retrieval tool with clear annotations, this is complete.

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

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

Schema coverage is 100% and already describes the parameter clearly ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but adds only minimal extra semantics beyond pairing with siblings. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list) and resource (saved values/keys), and distinguishes from sibling tools remember and forget.

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

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

The description explicitly says when to use: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It implies when not to use (use remember or forget) and names those sibling tools directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the return fields (source, citation_uri, raw payload) and the behavior of mark_read (flags returned events as read), which is beyond what annotations provide. 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 no wasted words. It front-loads the primary purpose, then details parameters and usage. Each sentence contributes meaningfully, achieving high density of information 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?

Despite no output schema, the description explicitly states what each alert carries. It covers all parameters, usage patterns, and even an alternative API. For a read-only, idempotent tool with comprehensive annotations, this description is fully adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by clarifying that 'type' filters by subscription type, 'since' is an ISO timestamp, and 'mark_read' flags events as read. This goes beyond repeating schema definitions, providing actionable context.

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

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

The description clearly states it pulls fired events from the subscription feed and returns the most recent alerts. It specifies the resource (alerts) and the action (pull/return), distinguishing it from sibling tools by focusing on alert retrieval. The verb 'Pull' and resource 'fired events' are specific and unambiguous.

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

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

The description provides explicit guidance on filtering by type and since, using mark_read, and notes that polling works fine. It also mentions an alternative endpoint for scripts/dashboards. While it doesn't explicitly state when not to use this tool, the context is sufficient for an AI agent to decide.

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

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

Annotations already declare readOnly, openWorld, idempotent hints. Description adds transparency about fan-out to multiple sources, fallback on rate limits, and soft-failure for USPTO. Describes return structure with groups and citation URIs.

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

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

Description is a single paragraph but well-structured with example queries first, then technical details. Every sentence adds value. Could be slightly more concise but still efficient.

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

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

For a multi-source, fallback, date-parsing tool without output schema, the description is thorough. Explains sources, fallback, date formats, soft-failure, and return structure. No gaps observed.

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%, baseline 3. Description adds valuable context: explains 'since' accepts ISO or relative shorthand and that 'value' accepts ticker or CIK. Enhances understanding beyond schema.

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

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

Description clearly states it provides a change feed for a company (SEC, news, patents) in a given window. Uses specific verbs and example queries. Distinguishes from sibling tool 'entity_profile' via explicit usage guidance.

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 this tool versus 'entity_profile' (static profile). Explains fallback mechanism (GDELT→GNews) and provides guidance on 'since' parameter formats (ISO or relative).

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 persistence behavior beyond annotations: authenticated users get persistent memory, anonymous sessions retain for 24 hours. Also implies overwriting (idempotent). 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?

Five sentences, front-loaded with purpose, then usage guidance, then behavioral detail. No redundancy or filler. 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 rich annotations and schema, description fully covers purpose, usage, and behavioral traits. No missing information needed for tool selection or invocation.

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

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

Schema coverage is 100% with inline descriptions for key and value. Description adds context by stating 'stored as a key-value pair' and providing examples, which reinforces parameter roles beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later' with specific verb (save), resource (memory), and context (across sessions). Distinguishes from siblings recall and forget by mentioning them explicitly.

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

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

Provides explicit usage context: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Also advises pairing with recall/forget for retrieval/deletion.

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?

Even with readOnly/openWorld/idempotent annotations, the description adds substantial behavioral context: each call cascades through several lookup endpoints, LEI/FIGI enrichment degrades gracefully, unresolved identifiers are explicitly listed under `unresolved`, identifiers are labelled with their source, and non-ticker instruments resolve when appropriate. This goes far beyond what annotations indicate.

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 examples and the core purpose, but it is extremely dense and runs on as a single wall of text with many parentheticals. There is a lot of valuable information, but it could be organized into focused bullets or shorter sentences to improve scannability. Some redundancy exists between the opening example list and the later input-format 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?

Given the tool has two parameters, no output schema, and no explicit per-parameter format hints in the schema, the description is remarkably complete. It covers supported entity types, accepted input forms, resolution behavior, candidate disambiguation, source labeling, unresolved identifiers, graceful degradation, and why internal cascading reduces manual lookups. An agent has all the information needed to invoke it correctly.

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

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

Although schema coverage is 100%, the description greatly enriches the parameter meanings. It explains what `value` may contain for company (ticker, CIK, ISIN, or name) versus drug (brand or generic), gives concrete examples, and adds a critical warning to pass only the entity name, not the full noun phrase, because trailing security-class words will fail the FIGI lookup. This is exactly the kind of semantic guidance an agent needs.

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

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

The description states a specific verb and resource: resolve a user-spoken name into canonical/official identifiers that other tools require as input. It opens with concrete example queries ('What's the ticker for...', 'find the CIK for...') and the 'Use FIRST whenever you have a name but need an ID' rule makes the tool's role unmistakable.

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

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

The description gives an explicit when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also scopes supported entity types (company, drug) and explains when the tool should not assert a single answer (when a bond issuer name matches multiple instruments, it returns candidates). However, it does not name sibling tools or state when-not-to-use conditions such as 'use entity_profile if you need a full profile rather than an ID.'

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

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

Annotations declare readOnly, idempotent, and non-destructive. The description adds that it internally calls ai_visibility_check, requires an _apiKey for certain models, and returns a ranked list with score, confidence, signal density. 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 three sentences, front-loads the purpose, and contains no fluff. Every sentence adds value.

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

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

Given the complexity of comparing multiple entities and calling another tool, the description covers purpose, input behavior, and output structure. No output schema exists, but the description adequately specifies return fields. The entity limit (2-8) is in the 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% with descriptions. The description adds extra meaning: the first entity is treated as 'subject' for narrative, which is not in the schema. This provides valuable guidance for usage.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probing each with ai_visibility_check and ranking results. It differentiates from the sibling ai_visibility_check (single entity) and describes output, making 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 a clear use case ('competitive AI-marketing audits') and example question. However, it does not explicitly tell when not to use the tool or mention alternatives like ai_visibility_check for single entities, though this is implied through context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds crucial behavioral details: it fans out to two services (deps.dev and bundlephobia), notes that bundlephobia's first measurement can take 5-30 seconds, and explains partial failures degrade gracefully with a sources_failed list. 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 informative but somewhat lengthy. However, it is front-loaded with the core purpose and each sentence adds value. Minor improvement would be to shorten the list of return fields, but overall it maintains good structure.

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

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

Given the complexity of the tool (composite check, two services, multiple return fields) and no output schema, the description is remarkably thorough. It lists all return fields in parentheses, explains failure behavior, and mentions version history and links. The agent can fully understand inputs, outputs, and edge cases.

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

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

Schema coverage is 100%, with both parameters described. The description adds value beyond the schema: it clarifies that scoped packages (e.g., '@types/node') are accepted for the 'package' parameter, and that 'version' defaults to the latest published version. This enhances semantic understanding.

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

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

The description clearly states the tool's purpose as a composite check for npm packages covering license, advisories, version history, and bundle size. It specifies the exact use case ('should I add this npm package') and distinguishes from alternatives by noting ecosystem limitations and mentioning deps.dev:version for other package managers.

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

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

Explicitly provides usage guidance: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'.' It also includes when not to use (other ecosystems) and directs to alternative tools, which is exemplary for an AI agent's decision-making.

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 no additional behavioral context such as rate limits, permission requirements, or search quirks; it merely restates the return of matching quotes, which is already implied by the tool's purpose.

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 exactly two sentences, front-loaded with the action 'Search quotes by keyword or phrase,' and contains no redundant or superfluous words. It is efficiently structured and immediately informative.

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 search tool with a well-documented schema and annotations, the description is minimally adequate but lacks any usage context or mention of pagination or the limit's rounding behavior. The output schema likely covers return values, but the description could still note when to choose this tool over alternatives.

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 both 'query' and 'limit' described in detail, including the bucketing behavior for limit. The description's 'keyword or phrase' adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search quotes by keyword or phrase' with a specific verb and resource. It also specifies what is returned ('matching quotes with author names and topic tags'), distinguishing it from siblings like random_quote and get_authors.

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 no guidance on when to use this tool versus alternatives. It only states the operation without any exclusions, prerequisites, or named alternatives such as random_quote or search_within.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flag). 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 well-structured: purpose first, then usage guidance, then technical details. Every sentence adds value without redundancy. 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 lacking an output schema, the description explains return values (top-N passages with character offsets and similarity scores). It also provides technical details (embedding, chunking, limit) that are essential for correct usage. The description is complete for a search-within-text 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% (all three parameters have descriptions). The description adds helpful examples for the query parameter and clarifies the default for limit (5). It also reiterates the max character limit for text. This adds some value beyond the schema, justifying a 4 above 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 performs semantic search inside a fetched record, using specific verbs ('search inside') and resources ('fetched record'). It distinguishes from siblings by contrasting with ask_pipeworx_grounded and implying it is not for fetching data but for searching within already-fetched text.

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: 'when the record is too big to cram into the prompt'. It also explains the benefits (saves context, returns only relevant passages) and mentions a complementary tool (ask_pipeworx_grounded) for grounding over passages.

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

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

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds critical details: return value, always-on feed, optional channels, rate limits, and verification requirements. No contradictions.

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

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

The description is well-organized and front-loaded, but slightly verbose with minor redundancy (e.g., repeating delivery details). Overall, each sentence adds value.

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

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

Given the tool's complexity (multiple types, delivery channels, authentication), the description covers all necessary context: return value, prerequisites, type parameters, and delivery constraints. No output schema but return stated.

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

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

Schema coverage is 100%, but the description enriches parameter understanding with type-specific examples, delivery channel constraints, and prerequisites. This significantly aids correct invocation 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 creates a proactive monitoring subscription and returns a subscription ID. It effectively distinguishes from sibling tools like list_subscriptions and unsubscribe, which handle different operations.

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?

Prerequisites (Pipeworx OAuth account) are explicitly stated, and supported types with delivery channels are detailed. However, it lacks explicit 'when not to use' guidance, though context implies alternatives like listing or unsubscribing.

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

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

Annotations already mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds that it returns 'category-bucketed example questions (company financials, drugs & clinical trials, etc.) — each with the exact tool + argument shape that answers it, drawn from the live catalog of thousands of tools.' This provides detailed behavioral context beyond annotations.

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

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

The description is slightly long but front-loaded with natural language queries, then clearly explains the tool's function and output. Each sentence adds value, though a minor trim could improve conciseness without losing content.

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

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

Given no output schema, the description fully explains what the tool returns (categorized example questions with tool calls) and mentions its role in learning meta-tools. It covers all necessary context for an onboarding/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% with one parameter (topic) described. The description adds example values (finance, pharma, etc.) and clarifies that omitting the parameter gives a cross-category spread, enhancing the schema's meaning.

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

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

The description starts with common user queries and clearly states it is the onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings like ask_pipeworx and entity_profile by specifying its role in helping users discover capabilities and tool usage.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides strong when-to-use guidance. It also mentions optional topic filtering but does not explicitly state when not to use it or list alternatives, though the context is clear.

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

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

Adds ownership enforcement and deactivation behavior beyond annotations. Aligns with idempotentHint and destructiveHint. No contradictions.

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

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

Two sentences, each essential: purpose and behavioral constraints. 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?

Fully addresses purpose, preconditions (ownership), side effects (deactivation, history), and ties to sibling recent_alerts. Adequate for a single-param tool.

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

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

Description repeats schema's parameter description but adds no new semantic context. Full schema coverage justifies baseline 3.

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

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

Explicit verb 'Cancel' with resource 'subscription by id'. Distinguishes from siblings like subscribe (creates) and list_subscriptions (lists).

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?

Clearly states ownership enforcement and that cancellation is deactivation not deletion, with direction to recent_alerts for history. Could be stronger with explicit when-not-to-use but suffices.

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 by explaining critical behavioral nuances: the semantics of each verdict (especially could_not_verify vs unsupported), the two distinct processing paths (SEC EDGAR for financial claims, grounded pipeline for others), and the caveat that could_not_verify must not be used as evidence. This aligns with and enriches the openWorldHint annotation.

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

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

The description is lengthy but well-structured: it opens with trigger phrases, states purpose, gives usage, explains the pipeline, lists verdicts, highlights a critical caveat, and closes with an efficiency claim. Every sentence contributes, though a bit verbose; it earns a 4 rather than 5 due to the length, but there is 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?

With no output schema, the description fully compensates by enumerating the verdict types, the inclusion of citations and reasoning, and explaining error states. It also covers both claim categories, tolerance behavior, and the tool's advantage over sequential calls. This is a complete and self-sufficient description for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description reiterates the tolerance_pct override and provides examples of the claim parameter, but it does not add new parameter-specific semantics beyond what the schema already states. It is adequate but not enhanced.

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

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

The description clearly identifies the tool as a natural-language claim verification tool against authoritative sources, with specific examples of user intents. It distinguishes itself from sibling tools by explicitly framing it as fact-checking, and even mentions replacing 4–6 sequential calls, which sets it apart from generic research or ask tools.

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

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

Provides explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also outlines the two routing paths for different claim types. However, it does not explicitly list when-not-to-use or name alternative sibling tools, so it misses the full 'alternatives' criterion for a 5.

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