Quotes

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

Beyond annotations (readOnly, idempotent), the description adds billing transparency (free default model, BYO key for Anthropic) and explains the probing behavior and output structure. No contradictions.

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

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

Four sentences, front-loaded with main action, each sentence adds value without redundancy. Efficient and clear.

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

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

Despite no output schema, the description fully specifies the return format. All parameters are explained with usage context, and the tool's purpose is fully covered.

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 meaningful context: default model for 'models', explanation of '_apiKey' necessity, and role of 'context' for disambiguation. This goes beyond the schema.

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

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

The description clearly states the tool probes LLMs for entity knowledge and returns a visibility score per model. It uses specific verbs and resources, and distinguishes from siblings like scan_competitor_ai_presence by focusing on visibility scoring.

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 concrete use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use the API key for Anthropic. However, it does not explicitly compare to alternatives or state when not to use.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description goes further by explaining the routing behavior across thousands of tools and sources, the stable citation URIs in the response, and that it is a single fast call. This adds useful operational context beyond the annotation flags.

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

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

The description is longer than typical but front-loaded with 'PREFER OVER WEB SEARCH' and each sentence adds value: coverage domains, routing mechanism, trigger phrases, examples, and escalation paths. Slight redundancy such as 'default entry point' and 'works on every tier' keeps it from a 5, but it's well organized.

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

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

There is no output schema, so the description compensates by stating it returns 'the structured answer with stable pipeworx:// citation URIs' and by clarifying when to escalate to grounded or deep_research. It covers selection, invocation, and expected output; only error/edge-case behavior is absent, which is acceptable for a well-scoped 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 all six parameters documented as aliases for 'question.' The description repeats the natural-language nature and examples but doesn't add parameter-level detail beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the semantic load.

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 'PREFER OVER WEB SEARCH' and explicitly states it routes questions to 5,529 tools across 1,455 sources, returning structured answers with pipeworx:// citation URIs. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research and lists concrete domains (SEC filings, FDA, FRED/BLS, etc.), making its scope 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 provides explicit when-to-use guidance: 'START HERE for most questions' and 'works on every tier, one fast call,' while directing users to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. It also lists trigger phrases and examples, clearly contrasting with web search alternatives.

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

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

The description adds substantial context beyond the annotations: candidate routing improvements are enabled live when under test, no candidate is active now so it matches ask_pipeworx exactly, and results are compared against the stable router. It also clarifies it is a full working router, not a fallback stub. No contradiction with annotations.

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

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

Three sentences deliver purpose, current state, and usage guidance without redundancy. Each sentence adds distinct value, and the structure is front-loaded with the core definition.

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

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

For a tool with a single required question field, no output schema, and rich annotations, the description fully explains its beta nature, relationship to the stable sibling, live experimental behavior, and expected response shape. No significant gaps.

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

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

The input schema covers 100% of parameters with descriptions clarifying that all six are aliases for a single question field. The description adds no parameter-specific information beyond 'same arguments', so the schema carries the full burden. 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 identifies the tool as a beta version of ask_pipeworx, a universal router that routes questions to 5,529 tools. It distinguishes it from siblings by its experimental edge and candidate routing improvements.

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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing', giving a clear when-to-use context. It does not explicitly state when not to use it, but the mention of the stable router implies a preference for the stable version when reliability is 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?

Adds substantial behavioral detail beyond annotations: the extraction-only constraint, explicit refusal reasons ('not_in_source', 'no_tool_match', etc.), the return envelope fields, and the extra LLM call cost. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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 longer than typical descriptions, every sentence earns its place: purpose, mechanism, return format, refusal reasons, use cases, and cost trade-off. The key differentiator is front-loaded in the first sentence.

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

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

Despite having no output schema, the description fully explains the return envelope and failure modes, making it complete for selecting and invoking the tool correctly. It also covers the routing breadth and grounding strategy context sufficiently.

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 all aliases documented as equivalent to the question. The description only restates that the input is a natural-language question, adding no parameter syntax or semantics beyond what the schema already provides.

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

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

The description clearly identifies this as a hallucination-resistant 'grounded' answer mode, distinguishing it from sibling tools like ask_pipeworx by emphasizing extraction only from tool results. It specifies the exact behavior: picks the right tool, fills arguments, fetches data, and extracts the answer using ONLY what the result contains.

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: 'whenever an answer will be quoted, cited, or acted on' and lists high-stakes examples. It also names the alternative (ask_pipeworx) and explains the trade-off (costs one extra LLM call), with clear preference for casual lookups.

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

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

The description discloses numerous behavioral traits beyond annotations: low-confidence short-circuit, closed market handling, wide-spread illiquidity, resolution-rule risk parsing, and fallback mechanisms for news sources. Annotations already indicate read-only and idempotent; no contradiction.

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

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

The description is excessively long (~900 words), mixing essential guidance with detailed internal mechanics (e.g., fan-out examples, resolver contract). Front-loaded but not concise; agents may struggle to parse key points quickly.

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

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

Despite no output schema, the description fully explains return shapes (result.market, result.analysis, result.evidence), edge cases (dead markets, low-confidence, wide spreads), and safety mechanisms. Covers all aspects needed for correct 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% (baseline 3). The description adds meaning for depth ('quick = 2-3 evidence sources, thorough = full fan-out') and include_raw ('keeps responses under ~20KB'), enhancing agent understanding beyond schema details.

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 exact inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). No ambiguity.

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 recommends use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not compare with sibling tools but provides clear context for when to invoke.

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

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

The description adds significant behavioral context beyond annotations: it lists the four possible verdicts, explains that 'verified' comes with a citation, and clarifies that 'paraphrase_of_verified' returns the actual text. Annotations already declare readOnlyHint and idempotentHint, and the description aligns without contradiction.

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

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

The description is two sentences, each serving a distinct purpose: the first explains what the tool does and its outputs, the second states its usefulness. No redundant or extraneous 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 (two parameters, one required, no nested objects) and the presence of an output schema, the description fully covers the tool's behavior and return values. It explains all verdicts and their implications, making it complete for agent use.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the role of 'claimed_author' ('narrows the check') and the overall purpose of each parameter in context, going slightly beyond the schema's basic descriptions.

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

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

The description clearly states the verb ('check attribution'), the resource ('quotes'), and the output (four distinct verdicts). It distinguishes itself from siblings like 'validate_claim' or 'search_quotes' by focusing specifically on verifying popular attributions.

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 names target users and use cases ('journalists, researchers, anyone tired of fake Mark Twain quotes'). It implies when to use this tool, though it does not explicitly state when not to use or list alternative tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it explains that it fetches data from SEC EDGAR/XBRL or FAERS, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs, surpassing the annotation-only information.

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 somewhat verbose with many trigger phrase examples, but it is well-structured: starts with purpose, then usage, then parameter details. Every sentence adds value, though some could be shortened without losing clarity.

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

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

Despite no output schema, the description explains the return format (paired data + citation URIs) and covers edge cases like off-calendar fiscal years. It thoroughly addresses the complexity of comparing multiple entities across two domains, making it fully informative for correct tool 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 descriptions for both parameters. The description enriches this by explaining what each type yields (revenue, net income, etc. for company; adverse-event counts for drug) and gives examples for 'values' (tickers, drug names), adding meaning beyond the schema.

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

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

Description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases like 'compare X and Y' and 'which is bigger'. It distinguishes from sequential single-pack lookups, making the purpose unambiguous and specific.

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 strong guidance on when to use it. It also details the two entity types (company/drug) and what data each pulls, helping the agent decide appropriately.

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

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

Despite annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false), the description adds rich behavioral context: account requirements, paid tier for 'thorough', parallel decomposition, gap recovery, never-invented evidence, return format with hop and citation_uri, semantic excerpting, and expected latency. This goes far beyond what annotations convey, disclosing limitations and failure modes.

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 quite dense and long, but it front-loads the most critical operational constraint (account required) and packs many valuable details. Every sentence carries information, but the length is near the upper bound; some reiteration exists around depth levels and gaps[] across different sentences. It is structured with semicolons and em-dashes, but would benefit from clearer paragraph separation.

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 (2 params, no output schema, high-stakes research behavior), the description is remarkably complete: it covers authentication, pricing tiers, what kind of results to expect, failure mode (empty gaps[] for non-catalog topics), latency, and citation fetchability. No output schema exists, so describing return format is essential and done thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema: it explains the depth levels' behavioral implications (gap-recovery hop, contradictions scan, paid plan), and describes the question parameter as 'broad/multi-part is fine — decomposition is the point', which aids selection. It doesn't provide syntax examples, but the added behavioral semantics justify 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 uses a specific verb+resource ('Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources') and clearly distinguishes from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx. It also explains what it returns (findings packet, gaps[], contradictions[]) which solidifies its unique purpose.

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

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

Explicit when-to-use: 'Best for broad/multi-part questions over structured data'. Explicit when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx' and 'For a single lookup use ask_pipeworx'. Also names alternatives (ask_pipeworx) and provides a signup/account condition that affects usage.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe, read-only behavior. Description adds that results include full schemas and are ready to call, but does not contradict 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?

Front-loaded with purpose, then usage, then output details. Every sentence is informative 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?

Despite no output schema, description thoroughly explains output format (top-N tools with names, descriptions, schemas, examples) and covers usage guidance, making it complete for agent invocation.

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

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

Schema covers all 6 parameters (100% coverage). Description adds context that query accepts natural language and multiple aliases, and gives examples, enriching the schema's explanations.

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 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing this discovery tool from sibling data-retrieval tools.

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

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

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

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds context about multi-source fan-out, specific return fields, patent API sunset with soft-fail, and fallback behavior, which adds value beyond annotations.

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

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

The description is a single block but every sentence adds value. It front-loads with examples and then details. Could be more structured with bullet points but is appropriately sized for the complexity.

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

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

Without output schema, the description explains return values in detail (cik, filings, fundamentals, etc.) and mentions API status. However, it lacks information on error handling (e.g., unknown ticker), which would improve completeness.

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

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

Schema coverage is 100%, and description adds significant meaning: explains the type enum (only company), and for value explains ticker or zero-padded CIK with example, and explicitly states names not supported. This fully compensates 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 produces a full cross-source profile of a US public company in one parallel call, listing specific sources and return fields. It distinguishes itself from siblings by explicitly preferring over chaining and mentioning resolve_entity for names.

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 strong guidance on when to use (holistic company view) and what not to do (names not supported, use resolve_entity). It also mentions preferring over chaining but does not give explicit when-not scenarios, missing some edge cases.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the description adds no extra behavioral context. It does not describe side effects like what happens if key is missing, but given annotation coverage, score is adequate.

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 the action and resource, followed by usage guidance. No superfluous words.

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

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

For a simple tool with one parameter, annotations, and no output schema, the description fully covers purpose, usage, and sibling relationships. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning to the 'key' parameter beyond the schema's description, which is sufficient.

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

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

The description uses a specific verb 'Delete' and resource 'previously stored memory by key', clearly distinguishing the tool's function. It also references sibling tools 'remember' and 'recall', showing its place in a family.

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

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

Explicitly states when to use the tool: 'context is stale, task is done, or want to clear sensitive data'. It also mentions pairing with 'remember and recall', guiding context on alternatives.

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

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

The description adds behavioral context beyond annotations: it explains the internal steps (fetch, extract, emit) and output format ('single text blob'). This complements the annotations (readOnlyHint, idempotentHint, destructiveHint) without contradiction.

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

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

The description is three sentences with zero wasted words. It front-loads the primary function, then immediately gives output format and use cases, making it easy 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?

For a simple two-parameter tool with full schema coverage and informative annotations, the description is complete. It covers purpose, output, and use cases. Missing error handling details are acceptable at this complexity level.

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

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

The input schema already provides 100% coverage with descriptions for both parameters. The description adds no further parameter-specific detail (e.g., format guidance for 'url' or explanation of 'key links' selection), so it meets but does not exceed the baseline.

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

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

The description begins with a clear action verb ('Generate') and specific resource ('llms.txt file') and scope ('for any URL'). It lists three distinct use cases (client indexing, own project, competitor audit) that distinguish it from sibling tools like scan_competitor_ai_presence.

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

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

The description provides clear use-case scenarios ('Useful for...') that guide when to invoke the tool. However, it lacks explicit exclusions or direct mentions of alternative tools, which would warrant a higher score.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already cover safety. The description adds value by describing the return structure: 'Returned object contains nested scenes with their speeches and lines.' 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 with no fluff. First sentence states function and return content; second provides usage context and confirms nesting. 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 output schema exists and annotations are rich, the description fully informs the agent of the tool's purpose, usage, and return structure. No gaps.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description does not add extra parameter details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Return the full text of an entire act (all scenes within it)', specifying the verb (return) and resource (full act). This distinguishes it from siblings like get_scene and get_chapter.

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

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

Provides explicit guidance: 'Use this to read a full structural unit at once.' Does not mention when not to use or name alternatives explicitly, but 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 read-only, idempotent, non-destructive behavior. The description adds that the tool returns 'all paragraphs in order', which is useful behavioral context beyond the annotations.

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

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

Two sentences plus an example, no wasted words. The purpose is front-loaded in the first sentence. The example is compact and illustrative.

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 comprehensive annotations, the description is complete. It explains the output format (full text, paragraphs in order) and provides usage context.

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

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

Schema coverage is 100%, so the description adds little beyond the schema. However, the example provides concrete values for parameters, which aids understanding. 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 action: 'Return the full text of a chapter from a novel/prose work'. It specifies the resource and includes an illustrative example. Among siblings, get_chapter is distinct from get_act and get_scene, which target plays.

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

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

The description advises using list_full_text_works to discover chapter-based works, providing a clear prerequisite. While it doesn't explicitly state when not to use the tool, the context is sufficient for correct selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and mutability. The description adds that it returns lines in order, but does not disclose any behavioral traits beyond what annotations and schema imply.

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 plus an example, no wasted words. The main action is front-loaded, followed by a compelling example and use cases.

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 that an output schema exists, the description does not need to explain return values. It sufficiently covers what the tool does, how it works (full text in order), and when to use it.

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

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

The input schema already describes all four parameters with 100% coverage. The description's example provides concrete values (e.g., author_id='william-shakespeare') which adds context but does not significantly augment 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 it returns the full text of a specific scene, including every speech and line in order. The concrete example with Hamlet's 'To be, or not to be' scene makes the purpose unmistakable. It distinguishes itself from siblings like get_act and get_chapter.

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 mentions the tool is 'useful for context, citation, or close reading,' providing clear use cases. It does not explicitly state when not to use it or list alternatives, but the sibling tools (e.g., get_act) imply the appropriate scope.

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 and idempotent hints, so the description's addition of output structure and the note about author ID being used elsewhere adds useful context beyond annotations.

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

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

The description is a single sentence that efficiently conveys purpose and output details. No wasted words; structure is front-loaded and clear.

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

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

Given no parameters and an existing output schema, the description adequately covers the tool's behavior. It mentions all key output fields and their utility, making it complete for agent understanding.

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

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

With zero parameters and 100% schema coverage, the baseline is 4. The description adds no parameter details (none needed) but provides value by explaining the output fields.

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 'Return all authors available in the corpus' with specific verb and resource, and it details the included fields. It distinguishes the tool from siblings by being the only author-listing operation.

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?

While the description does not explicitly compare with alternatives, it clearly implies use when a full list of authors is needed. The lack of parameters and straightforward nature make usage obvious, but it could mention that this is the canonical way to get author IDs.

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 safe read-only behavior. The description adds that the tool returns works with full text 'loaded' and distinguishes it from excerpt-only works, which provides additional behavioral context beyond the annotations.

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

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

Two sentences: first defines the tool's output, second gives usage context. No wasted words, front-loaded with the key action.

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

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

For a no-parameter tool with a clear purpose and output schema, the description is complete. It explains what the tool returns and how to use it for deeper analysis, which is sufficient.

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

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

No parameters exist (schema is empty). Baseline for 0 parameters is 4. The description does not need to add anything, and schema coverage is 100%.

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

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

The description clearly states it lists works with full text (every scene, speech, line) as opposed to excerpts, and distinguishes it from sibling tools like search_quotes. It also explicitly ties it to further deep lookup via get_scene and get_act.

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: 'Use this to discover what is available for deep structural lookup via get_scene and get_act.' It implies the purpose and sequence of use, though it doesn't explicitly state when not to use.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds return field details but no additional behavioral traits beyond annotations. Minimal extra disclosure.

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

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

Three sentences, each with clear purpose: first states function and output, second gives usage guidance. No unnecessary words or repetition.

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

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

Complete for a simple list tool: purpose, returned fields, usage context, and implicit parameter behavior all covered. Annotations and siblings provide sufficient surrounding context.

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

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

Schema coverage is 100% with clear description for include_inactive. Description implies default active listing but adds no meaning beyond what schema already provides. Baseline score applies.

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

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

Description uses specific verb 'list' with resource 'subscriptions' and scope 'caller's active'. Clearly distinguishes from sibling tools subscribe/unsubscribe by stating its role in reviewing before adding or finding id to cancel.

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: 'review what you're monitoring before adding more or to find an id to cancel', directly addressing alternatives among siblings.

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

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

Beyond the all-false annotations, the description reveals rate-limiting ('Rate-limited to 5 per identifier per day'), free access ('Free; doesn't count against your tool-call quota'), anonymous claim_token return, the ability to later poll status using that token, and the team's digest cadence ('reads digests daily'). This is substantive behavioral disclosure well beyond the structured 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 information-dense; each sentence carries operational weight. It is front-loaded with the primary purpose and organized into clear sections (what, when, where-not, workflow, limits). It is slightly verbose for a feedback tool, but the length is justified by the need to disambiguate from other MCP servers and explain the claim_token flow.

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

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

The description covers purpose, usage, exclusions, rate limits, token mechanics, and follow-up behavior—comprehensive for a simple feedback tool. There is no output schema, but the description explains the only meaningful return value (claim_token) and how to read status later. Minor gap: it does not describe what happens for authenticated users beyond the implied success response, but for the tool's simplicity this is sufficient.

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

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

The input schema already covers all four parameters with descriptions, so the baseline is 3. The description adds valuable usage nuance: claim_token must be used 'with no other arguments', provides an example call format, and tells users to 'describe the issue in terms of Pipeworx tools/packs' and not paste end-user prompts. This goes beyond schema descriptions.

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

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

The description opens with a specific, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly identifies the resource (Pipeworx team/tools) and differentiates from siblings by explicitly scoping to 'tools served by this Pipeworx connection' and referring to other MCP servers as out of scope.

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

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

The description gives explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit when-not-to-use scenario ('if the tool came from a different MCP server... file it with that server instead'). This is direct usage guidance that also positions it against alternatives like ask_pipeworx. It also states the rate limit, which helps set expectations.

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

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

Description adds significant value beyond annotations: data source (CF analytics-engine), no PII, caching window, and self-aggregating nature. 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?

Concise, front-loaded, with bullet points for use cases. Every sentence contributes meaningful information without redundancy.

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

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

Given simple parameter structure and rich annotations, the description covers purpose, usage, data source, caching, and parameter effect. No gaps.

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

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

Schema description covers 100% of the parameter. Description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific use cases. It distinguishes from siblings like 'discover_tools' by focusing on trending usage data.

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

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

Three explicit use cases are provided, but no direct when-not-to-use or alternative tool references. However, the context is clear enough for an agent to decide when this 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 (readOnlyHint, openWorldHint, etc.) are present, and the description adds rich behavioral context: explains algorithms, output structure (opportunities[]), edge cases (low similarity, placeholder filtering, fill check), and warns about realizable vs theoretical edge. 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 fairly long but well-structured into sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though slightly dense. Could be marginally more concise, but still very effective.

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

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

Given the tool's complexity (2 params, no output schema, annotations present), the description is thorough. It explains output structure, fill check, when not to trade, and references another tool for custom sizing. An AI agent can confidently use this tool based on the description.

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

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

Schema coverage is 100%, but the description adds extensive meaning beyond the schema: explains slug format, topic mode logic, examples, and even that full Polymarket URLs are accepted. This greatly helps an agent use parameters correctly.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and uses specific verbs and resources, differentiating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly tells when to use each parameter: no args for trending scan, event for a specific market, topic for cross-event scanning. Provides examples, recommendations, and explains when not to trade via fill check. Also references polymarket_fill_risk for custom sizing.

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

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

The description adds significant behavioral context beyond annotations: it reveals the 1-hour KV-level caching, outlines the edge calculation methodology (including edge_pp_net, kelly_fraction, liquidity, spread, volume, and 24h-move warning), and discloses limitations like the Fed signal unreliability. Annotations already indicate read-only, idempotent, non-destructive operations, and the description aligns with and enriches these traits.

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

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

The description is well-structured with clear sections (model families, knobs, diagnostics), but it is overly verbose, containing lengthy algorithmic details and inline code-like explanations. While informative, it could be more concise without losing essential 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 complexity (9 parameters, no output schema), the description is remarkably complete. It explains the three model families, edge calculation, tradeable-edge filters, diagnostics for empty segments, caching behavior, and Fed bet handling. All relevant context for an agent to decide when and how to invoke the tool is covered.

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 provides extensive additional meaning for each parameter. For example, slippage_pp explains the default rationale (zero trading fees but bid/ask depth), advises tuning, and ties to edge calculation. min_partition_leg_kelly clarifies its specific use for partition arbs. All parameters are thoroughly contextualized 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 it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly identifies the tool's purpose as 'what should I bet on today' and differentiates it by describing three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) with detailed methodology, distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The description specifies the tool is built for discovering opportunities without paging hundreds of markets, providing clear context for use. However, it does not explicitly state when not to use this tool or directly compare it to alternatives like polymarket_edge_tracker or polymarket_fill_risk, which are listed as siblings.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds critical behavioral details: history depth is bounded by 60-day TTL, decay numbers come from daily closes (not intraday), and snapshots are written only on cache-miss. No contradictions with annotations.

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

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

The description is well-structured: purpose first, then detailed response format, then limitations. It is slightly verbose (response details could be in an output schema), but front-loading the core purpose and using clear sections makes it effective.

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

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

Given no output schema, the description thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) with their semantics and limitations. This provides sufficient context for an agent to understand what data to expect and the boundaries of the tool.

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

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

Schema description coverage is 100% (both parameters documented). The description reinforces defaults and constraints (days: default 14, max 30; window: default '1wk') and explains their role in the snapshot family. Adds value beyond schema by tying parameters to the response structure.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers 'how long has this edge existed and is it shrinking?' and distinguishes from sibling tools like polymarket_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 provides usage context by contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It implies when to use this tool (for historical persistence analysis) but does not explicitly mention when not to use or list alternative tools.

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

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive. Description adds rich behavioral details: walks the ladder, returns specific fields, explains verdict categories and forced directional risk, providing context beyond annotations without contradiction.

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

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

Description is detailed and well-structured with capitalized key terms and clear sections, but is relatively long (~150 words). Every sentence adds essential information for the complex tool, earning a slight deduction for 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 thoroughly explains all return fields for both modes, including verdict categories, thin_legs, forced_directional_risk, and edge cases like partial fills. Covers risks and usage context comprehensively.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds significant value by explaining parameter interactions across dual modes, interpreting size_usd differently for single-market vs basket, and providing examples of default behavior and clamping.

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and explicitly differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

Provides explicit usage guidance: REQUIRES one of market or event, specifies defaults and modes, and states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', including risks of partial fills and thin books.

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, idempotentHint), description details safety fields, compatibility warnings, temporal alignment, and skipped cross-type/subtype counters. It explains that real spreads are rare and pre-mapped topics may not be tradeable.

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

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

The description is comprehensive but not overly verbose. It front-loads key information and each sentence serves a purpose. Minor length could be trimmed slightly, but overall well-structured.

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

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

Despite lacking an output schema, the description fully explains the response (leg-by-leg prices, top_spreads_pp, safety fields, temporal_alignment). It covers edge cases and limitations, making it self-contained for correct tool 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 descriptions for each parameter. The tool description adds context like the full list of topic shortcuts, override behavior, and response structure, far exceeding 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 states it computes cross-venue spreads between Kalshi and Polymarket, and the title reinforces this. It distinguishes from sibling tools like polymarket_arbitrage by focusing on the same resolving question across venues.

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

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

Explicitly describes two modes (topic and explicit), lists available topic shortcuts, and warns when spreads may not be meaningful (compatibility_warning conditions). It tells agents when not to use, e.g., when bet shapes are non-equivalent or temporal alignment is false.

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, destructiveHint. Description adds example of output but no additional behavioral traits like error handling or rate limits.

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 sentence plus example—extremely concise and front-loaded. No redundant 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?

With output schema and annotations present, description is adequate for a simple lookup. Lacks details on error cases or return format, but sufficient for typical use.

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

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

Schema has 100% coverage with clear descriptions. Description reinforces parameter groupings (act/scene vs chapter) and provides a concrete example, adding value beyond schema.

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

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

Description uses specific verb 'Look up quotes' and resource 'structural address within a work', clearly distinguishing from sibling tools like search_quotes or random_quote. The example reinforces the purpose.

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

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

Description implies usage for known structural addresses but lacks explicit when-not-to-use or alternative tool names. Context from sibling tools suggests differentiation, but not stated.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by describing the result structure (citation with work, year, speaker, source URL), which goes beyond annotations.

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

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

Two sentences with zero waste. First sentence states primary action and filters; second describes output. Perfect front-loading of key information.

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

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

Given the simple tool with 4 optional parameters, comprehensive annotations, and an existing output schema, the description is fully complete. It covers purpose, filters, and result content without needing to detail return values.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions filter options that match the schema but adds no new meaning beyond what the parameter descriptions already provide.

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 returns a random quote from a corpus with optional filters, and specifies result contents (citation info). This distinguishes it from siblings like search_quotes which return filtered results.

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

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

The description does not explicitly state when to use this tool versus alternatives. While the name and purpose imply it's for random quotes, no guidance on when not to use it or which sibling to prefer is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: omitting key lists all, scoping to identifier, and pairing with remember/forget, adding value beyond annotations.

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

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

Three succinct sentences that front-load the action, then provide usage context and scoping. 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?

Fully covers retrieval, listing, scoping, and pairing for a tool with one optional parameter and no output schema. Annotations cover safety.

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 parameter description. Description repeats the omit-to-list behavior and adds examples, but does not add new parameter-level semantics beyond the schema.

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

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

Clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. Distinguishes from sibling tools remember 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 concrete use cases (ticker, address, research notes) and scoping info. Lacks explicit when-not-to-use, but the context is clear enough.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that mark_read updates state to prevent re-fetching same alerts and includes return fields (source, citation_uri, payload). 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?

Single paragraph of 5 sentences. Front-loaded with main action and return value. Could use bullet points for parameters but is still efficient and clear.

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

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

Covers returned fields, filtering, stateful mark_read behavior, polling suitability, and alternative access. No output schema but describes key return elements. Sufficient for a 5-param tool with no nested objects.

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

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

All 5 parameters are described in schema with 100% coverage. Description enriches each with concrete examples (e.g., 'sec_8k' for type, ISO timestamp format, behavior of mark_read and unread_only). Adds meaning beyond schema.

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

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

Clearly states the tool pulls fired events from a subscription feed and returns most recent alerts. Specific verb 'Pull' and resource 'alerts from subscription feed' distinguishes it from sibling tools like search or analysis 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 usage context: fetching recent alerts, filtering by type/since, and marking read. Mentions alternative direct HTTP access for scripts/dashboards, but does not explicitly exclude other cases or compare to similar tools.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds substantial behavioral detail: fan-out strategy (SEC, GDELT→GNews fallback, USPTO with sunset note), relative date parsing, and citation URIs. No contradictions found.

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

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

The description is efficiently structured: starts with representative queries, then lists data sources, fallback logic, parameter details, and return format. Every sentence adds essential information without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return structure (grouped changes, total count, citation URIs). Given the tool's complexity (multiple sources, fallbacks, date formats), the description covers all necessary context.

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

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

Schema coverage is 100%, providing standard descriptions. The description enhances this with usage examples for `since` (e.g., '30d' for monitoring), and clarifies the `value` parameter accepts tickers or CIKs. This adds practical context beyond the schema.

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

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

The description clearly defines the tool as a change feed aggregating SEC filings, news, and patents for a company over a recent window. It explicitly distinguishes itself from the sibling `entity_profile` tool, which provides static profiles.

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

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

The description provides concrete example queries ('What's new with X', 'latest on Y') and directs users to `entity_profile` for static needs. While it lacks explicit 'when not to use' statements, the guidance is clear and practical.

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?

Disclosures include scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions—adding value beyond annotations. However, it does not mention whether writing a duplicate key overwrites the value, nor any capacity limits. Minor gap for a storage tool.

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

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

Four sentences, front-loaded with purpose. Each sentence adds value: purpose, usage guidance, technical detail, and pairing with related tools. 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, persistence, and pairing. For a simple key-value store with fully described parameters and annotations, this is fairly complete. Missing overwrite behavior and error handling, but likely acceptable given tool simplicity.

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 examples for key and value. The description adds context: stored as a key-value pair scoped by identifier, and purpose ('reuse later'). This provides meaning beyond the schema, justifying a score 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's purpose: 'Save data the agent will need to reuse later.' It specifies the verb 'save' and the resource 'data as key-value pair', and distinguishes itself from siblings like 'recall' and 'forget'. Examples of usage (ticker, address, preference) reinforce the purpose.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It pairs with 'recall' and 'forget' for retrieval and deletion, providing clear guidance on alternatives. Also differentiates between authenticated and anonymous sessions.

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 readOnlyHint and idempotentHint already set, the description still adds substantial behavioral detail: it explains cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit handling of unresolved identifiers under `unresolved`, source labeling for each identifier, and ownership hierarchy data. This goes well beyond the annotations and helps the agent predict edge-case behavior.

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

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

The description is dense but not bloated; it front-loads example queries and the "Use FIRST" directive, then structures supported types clearly. The company type explanation is a long parenthetical, but every sentence carries useful information. It could be slightly more streamlined, but it remains easily scannable.

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 identifier sources, two entity types, no output schema), the description is remarkably complete. It covers what is returned for each type, how unresolved identifiers are handled, degradation behavior, and the fact that it replaces multiple manual lookups. An agent has enough context to invoke the tool correctly and understand the response shape.

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 enhances this by explaining the semantics of each type value in depth (e.g., that "company" accepts ticker, CIK, or name and returns a cross-source identity spine; that "drug" returns RxCUI plus ingredient and brand). It adds meaning beyond the schema's brief parameter descriptions by detailing expected outputs and internal behavior.

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: resolving user-spoken names to canonical/official identifiers like CIK, LEI, RxCUI, and FIGI. It provides concrete example queries (e.g., "What's the ticker for…") and explicitly says it should be used first when a name needs an ID, distinguishing it from sibling tools that provide broader entity profiles or comparisons.

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

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

The description gives explicit usage guidance: "Use FIRST whenever you have a name but need an ID." It also details supported entity types and what identifiers each returns, clarifying scope. It does not explicitly name alternatives (like entity_profile) or say when not to use it, but the context is strong enough that an agent can infer appropriate use cases.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds that it probes each entity via ai_visibility_check, returns ranked list with score/confidence/signal density, and mentions optional API key. No contradictions, and adds useful context beyond annotations.

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

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

Four sentences, no fluff. First sentence states purpose, second explains internals, third gives example usage, fourth describes output. Well-structured and 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?

Description explains output format (ranked list with score, confidence, signal density) which compensates for missing output schema. Covers key usage context but doesn't detail error handling or model validation scenarios. Adequately 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 minor nuance (first entity treated as subject for narrative) but mostly repeats what the schema already provides. Does not significantly enhance 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 compares AI visibility across multiple entities, performs internal probing, ranks results, and identifies most/least recognized. It is well-differentiated from sibling tool 'ai_visibility_check' which operates on a single entity.

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 a concrete use case (competitive AI-marketing audits) and implicitly distinguishes from the single-entity sibling tool. However, it does not explicitly state when not to use or provide direct comparisons to alternatives.

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

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

The description adds behavioral context beyond annotations (readOnlyHint, idempotentHint) by detailing partial failure handling, timeout behavior (5-30s for new versions), and the fact that sources_failed lists timed-out sources while returning other data.

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

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

The description is a single paragraph but efficiently conveys purpose, usage, and behavior. It is slightly dense but well-organized with clear clauses. Loses a point for being a bit long.

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

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

Given complexity (composite tool) and absence of output schema, the description thoroughly covers return values (summary block, details, links, alternatives), ecosystem scope, error handling, and timeout behavior, leaving no ambiguity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds extra value: scoped packages like '@types/node' are accepted, and version defaults to latest when omitted. Also describes the output structure.

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 composite check for npm packages, specifying the exact question it answers ('should I add this npm package'), and distinguishes it from sibling tools by naming the data sources (deps.dev, bundlephobia) and the ecosystem (NPM).

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

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

Explicitly tells when to use: 'whenever an agent asks "is X safe / popular / small"', and when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context about matching both canonical text and popular paraphrases, which is a key behavioral trait not covered by annotations.

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

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

Two sentences that are front-loaded with the verb and resource, followed by a concise illustrative example. No unnecessary words or repetition.

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 is adequate for a tool with 4 parameters and an output schema. It explains the unique paraphrasing feature. However, it could briefly mention that quotes are returned (though output schema covers this).

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds examples but no additional meaning beyond the schema. Baseline 3 is appropriate as the schema already documents parameters well.

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

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

The description clearly states 'Search quotes by substring' and provides a concrete example ('protest' finding Hamlet's quote), specifying verb and resource. It distinguishes itself from sibling tools like check_attribution or random_quote by highlighting the paraphrasing feature.

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

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

The description implies usage for searching quotes with substring matching and paraphrasing, but does not explicitly state when to use this tool versus alternatives (e.g., check_attribution, search_within). No exclusions or sibling comparisons are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant detail: embedding model (BGE-base-en), window size (500-char overlapping), cap (200K chars with truncation flag), and output format (passages with offsets and scores). This goes well 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?

Single paragraph, but dense and efficient. Front-loaded with purpose and usage. Every sentence adds value. Could benefit from bullet points for readability, but 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 compensates by detailing return type (passages with offsets and scores), truncation behavior, and pairing advice. For a 3-parameter tool with full schema coverage, this is complete and covers agent needs.

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

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

Schema description coverage is 100%. The description adds value by providing examples for query ('supply-chain risk') and clarifying defaults (limit default 5). The text parameter's existing schema description is reinforced with 'already pulled' context. Slightly above baseline 3 due to meaningful examples.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb+resource. It distinguishes from sibling tools by explaining its use case for large records and pairing with ask_pipeworx_grounded, providing clear differentiation.

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' and suggests an alternative workflow with ask_pipeworx_grounded. Provides clear context and pairing guidance, effectively helping the agent 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?

Annotation contradiction: description implies non-idempotent behavior (each call returns a new subscription id), but annotation sets idempotentHint: true. No other significant behavioral gaps.

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, front-loaded purpose, and each sentence contributes meaningful information. Slightly long but appropriate for the complexity.

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

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

Covers prerequisites, type-specific filters, delivery options with constraints, and return value. Missing output schema is compensated by clear return statement. Adequate for the tool's complexity.

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

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

Schema coverage is 100%, and description adds substantial value with type-specific example structures, items codes, and delivery channel details (SMS cap, webhook signing). Baseline 3, upgraded due to rich additional semantics.

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream, lists supported types and delivery channels. Distinguishes from sibling tools like list_subscriptions 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?

Provides explicit requirements (Pipeworx OAuth account), type-specific examples, and delivery channel constraints (SMS cap, phone verification). Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds value by explaining the return format (category-bucketed examples with exact tool calls) and that it draws from the live catalog. No contradictory behavior disclosed.

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

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

The description is longer than average but well-structured, starting with user-facing questions, then explaining output and usage. Every sentence adds value; no fluff. Could be slightly shorter but maintains clarity.

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

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

Given the tool's simplicity (1 optional param, no output schema, rich annotations), the description is complete: it explains when to use, what the output contains, and how to narrow by topic. The 'Use this FIRST' guidance fills the context gap for an onboarding tool.

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

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

The schema has 100% coverage for the single optional 'topic' parameter. The description adds context by listing example values (finance, pharma, betting, etc.) and explains that omitting it gives a full spread. This goes beyond the schema's description.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It lists common user phrasings and distinguishes itself from sibling tools by being the first use. No ambiguity.

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

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

The description explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to use the optional topic parameter. It does not explicitly exclude other scenarios, but the context is clear. Sibling differentiation is present.

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 key behaviors beyond annotations: deactivation (not deletion), preservation of historical events via 'recent_alerts'. Consistently with idempotentHint=true and 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?

Two concise sentences with no waste. Front-loaded with core action, then context. 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?

Covers action, ownership constraint, effect, and related tool. Lacks mention of return value, but given simple nature and existing annotations, this is acceptable. Slight improvement possible.

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

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

Schema coverage is 100%. The description adds no new meaning about the 'id' parameter beyond what the schema already provides (uuid returned by subscribe). 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?

Clearly states it cancels a subscription by id, distinguishing it from sibling tools like 'subscribe'. Specific verb and resource make 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use. Lacks explicit alternatives or when-not, but the simple action is adequately guided.

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

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

The description adds significant behavioral context beyond the annotations: it details the structured SEC EDGAR fast path vs. grounded fallback, explains the meaning of could_not_verify (and that it is NOT evidence for/against), and distinguishes unsupported. This is crucial for correct agent behavior and goes well beyond the readOnly/openWorld/idempotent hints.

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

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

The description is front-loaded with trigger phrases and a clear definition, then systematically covers usage, internal routing, return values, and a critical caveat. While a bit long, every sentence provides unique value for a complex tool; there is minimal fluff. It's slightly denser than necessary but well-structured.

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

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

Despite having no output schema, the description fully explains what the tool returns (verdict, value, citation, reasoning), the error semantics, and the two distinct processing paths. It also mentions efficiency (replaces 4–6 sequential calls). Given the tool's complexity and the rich annotations and schema, this description is complete enough for an agent to select and 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?

The input schema already covers both parameters with detailed descriptions (100% schema description coverage). The tool description does not add any parameter-specific semantics beyond what the schema provides; it only references the claim conceptually. Per the rubric baseline, a 3 is appropriate since the description adds no extra parameter insight.

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 and specifically defines the tool as natural-language claim verification, using multiple trigger phrases like "fact check" and "verify the claim that…". It distinguishes this from general research tools by stating it checks whether 'something a user said is factually correct' and describes concrete verdict outputs. This clearly separates it from siblings like deep_research or ask_pipeworx_grounded.

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 instruction: "Use whenever the agent needs to check whether something a user said is factually correct." It also clarifies the two distinct internal paths for financial vs. other claims. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5 but is clearly context-rich.

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