Hathitrust

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds critical context: default model (workers-ai, free), optional Anthropic via _apiKey (passed straight through), and return 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?

The description is three sentences: purpose and output, model options and key handling, return structure and use cases. Each sentence is essential, no fluff, front-loaded with the primary function.

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 details the return per-model (score, confidence, signals, raw_response) plus combined view. All parameters are covered, and use cases are given. For a probing tool with good annotations, this is fully adequate.

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

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

Schema coverage is 100% with all parameters described. The description adds value beyond schema: clarifies default model, specifies that _apiKey is 'optional' and 'only needed if anthropic is in models', and explains context disambiguation. Does not fully detail all nuances but compensates adequately.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score per model (0-100). It distinguishes from siblings like scan_competitor_ai_presence by focusing on any brand/business/product/topic, making it unique.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly state when not to use or provide alternatives, though the context signals and sibling list make the niche clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that the tool returns structured answers with stable pipeworx:// citation URIs and dynamically routes to 3,745 tools. This adds valuable behavioral context beyond annotations, though it could be more specific about limitations (e.g., handling of ambiguous queries).

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

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

The description is a single paragraph that front-loads the key priority statement. It is reasonably concise but could be slightly shorter without losing clarity. The examples add value without being excessive.

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

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

Given the tool's complexity (routing to thousands of tools), the description provides a clear overview of purpose, data sources, and output format. It explains the return value (structured answer with citations) despite no output schema. It does not differentiate from sibling ask_pipeworx_grounded, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the parameters. The description does not add additional parameter meaning beyond noting that the tool accepts natural language questions and fills arguments. This meets the baseline expectation but does not provide extra depth.

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

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

The description clearly states the tool's purpose: to answer factual questions about current or historical data from authoritative sources, distinguishing it from web search and listing specific data types (SEC filings, FDA drug data, etc.). It uses specific verbs like 'routes' and 'returns' and explicitly contrasts with web search.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and provides examples of when to use (e.g., 'what is', 'look up', 'find'). It advises using even when web search could answer. However, it does not mention when to avoid using this tool or compare with sibling ask_pipeworx_grounded, so it's slightly lacking in exclusion criteria.

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 nondestructive nature. The description adds crucial behavioral details: it uses only tool result for extraction, returns structured refusals with reasons (not_in_source, no_tool_match, etc.), and incurs an extra LLM call. No contradiction with annotations.

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

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

The description is somewhat long but well-structured, front-loading the core purpose and then adding necessary details (refusal reasons, use cases, comparison). Every sentence adds value, though minor trimming could improve conciseness.

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

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

For a tool with 31 siblings and high-stakes usage, the description is remarkably complete: it explains extraction mode, refusal reasons (including enumerating them), return fields, cost trade-off, and explicit usage scenarios. Agents have all context needed to decide and use correctly.

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

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

Schema coverage is 100% with one required parameter (question) and five aliases documented. The description does not add additional parameter semantics beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool provides hallucination-resistant answers for high-stakes reads, routing through a large tool set and extracting answers solely from results. It also distinguishes itself from the sibling ask_pipeworx by noting its extra LLM call and refusal mechanism.

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

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

Explicitly states when to use this tool (answers to be quoted/cited/acted on, must not invent facts) and when to prefer the cheaper alternative ask_pipeworx (casual lookups). Provides clear guidance for the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds extensive behavioral details: market resolution, classifier fan-out, safety short-circuits, resolver contract, parent event extraction, news fallback behavior, resolution-rule risk, and tradeability warnings. No contradiction with annotations; the description greatly enriches transparency.

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

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

The description is verbose but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the core purpose. Every sentence adds necessary detail for correct invocation, though some redundancy exists (e.g., repeated mention of market_match). Still, the structure aids parsing.

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

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

Given the tool's complexity (3 params, no output schema, many edge cases), the description is exceptionally complete. It covers input formats, output structure, safety mechanisms, resolution matching, parent events, news fallback, and cancellation rules. An agent can determine exactly when and how to use the tool without additional 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 descriptions for all three parameters. The description adds meaning beyond the schema: explains input format variations for market, details fan-out behavior and response shapes, and clarifies the use of depth and include_raw. This helps an agent understand parameter impact beyond type definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, accepts multiple input formats (slug, URL, question), and returns an evidence packet with market-vs-model comparison. It distinguishes from siblings like polymarket_edges by focusing on a single bet research rather than edge detection or 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 explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and covers edge cases (low-confidence matches, closed markets, wide spreads). However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, so usage differentiation is implied rather than 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 declare readOnlyHint=true and idempotentHint=true. The description adds value by detailing the output (existence check, count, reading URLs) and the 'Keyless' nature, enhancing transparency beyond annotations.

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

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

Two sentences efficiently convey purpose and output. Front-loaded with the key action and resource, no wasted words.

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

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

Given no output schema, the description sufficiently explains return values (existence, count, URLs). The tool is simple with two params, and the description covers all needed 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 descriptions for both parameters. The description does not add new meaning beyond naming HathiTrust as the target, so baseline 3 is appropriate.

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

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

The description clearly states the tool checks for existence of full-view scanned copies on HathiTrust, including count and URLs. It uses specific verbs and resource (HathiTrust), and distinguishes from sibling tools like lookup_by_identifier by specifying the 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 implies use for a quick convenience check via 'Keyless', but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like lookup_by_identifier for non-HathiTrust lookups.

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

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

Annotations indicate read-only, open-world, and idempotent behavior. The description adds context: it mentions parallel processing, correct handling of off-calendar fiscal years for companies, data sources (SEC EDGAR/XBRL, FAERS), and that results are sorted by primary metric. No contradiction with annotations.

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

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

The description is detailed but front-loaded with query phrases and core purpose. Every sentence adds value, though slightly verbose; could be tightened without losing clarity.

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

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

Given the tool's complexity (two entity types, data retrieval, sorting, citation URIs), the description fully covers what each type returns, the parallel call efficiency, and replaces up to 15 sequential lookups. No output schema exists, but description compensates well.

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 that 'type' determines data source (company vs drug), 'values' can be tickers or drug names, and adds behavior like parallel processing and sorted results. This goes beyond schema definitions.

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

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

The description starts with common comparison phrases ('Compare X and Y', 'X vs Y') and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It differentiates from siblings like 'entity_profile' or 'lookup_by_identifier' by focusing on comparisons and specifying distinct data sources per type.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also explains what data each type retrieves, aiding tool selection.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds critical behavioral context: never invents facts (explicit gaps[]), returns verbatim evidence with confidence, source, fetched_at, and a citation. It explains decomposition and parallel routing, and notes that facts are pre-verified.

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 relatively long but every sentence adds unique value. Key capabilities are front-loaded. Minor improvements could tighten phrasing, but the structure is logical and complete.

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 absence of an output schema, the description fully explains the return format (structured findings packet with evidence, confidence, source, citation, gaps) and even mentions expected execution time (15-60s). No gaps in required 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 descriptions for both parameters. The description adds value by clarifying depth levels (quick=3, standard=5, thorough=8) and noting that thorough requires a paid plan, as well as emphasizing that broad/multi-part questions are fine.

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

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

The description uses specific verbs and resources ('Grounded multi-source research', 'Decomposes...routes...extracts') and clearly distinguishes from sibling tools like ask_pipeworx by specifying use cases for broad/multi-part questions versus single lookups.

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

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

Explicitly states when to use ('Use for broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'). Also provides prerequisites (Pipeworx account) and depth restrictions (paid plan for 'thorough').

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 context beyond readOnly/idempotent annotations: returns top-N relevant tools with full input schemas and curated examples, ready to call directly. No contradictions.

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

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

Front-loaded with purpose, then usage guidelines and behavioral details. Slightly long but efficient; 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 purpose, usage, behavior, return structure, and parameter aliases. No output schema, but description adequately explains what to expect.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that query has many aliases (q, task, search, description) and mentions limit, providing extra context 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 finds tools by describing data/task, lists many domains, and distinguishes itself from sibling tools as a discovery/search tool.

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

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

Explicitly advises to call this first when many tools are available and you need an overview, and specifies use cases like browsing, searching, looking up tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the USPTO patents API sunset (soft-fail), news fallback (GDELT→GNews), and that it returns specific fields. No contradictions. The description adds value beyond the annotations.

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

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

The description is detailed but front-loaded with examples and a clear purpose. Every sentence provides value, though the list of returned fields is somewhat verbose. Could be slightly tighter without losing clarity.

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

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

Given no output schema, the description lists all key return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), caveats (patents soft-fail, news fallback), and input constraints. This is very complete for a tool with 2 params and 100% schema coverage.

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% (both params described). The description adds meaning: explains that value can be ticker or zero-padded CIK, that names are not supported, and ties it to resolve_entity. It also clarifies the type param is limited to 'company' for now.

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

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

The description starts with example queries and states 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from chaining single-source lookups and from sibling tools like resolve_entity and compare_entities.

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

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

The description says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and explains that names are not supported, telling users to 'use resolve_entity first if you only have a name.' This provides explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true, idempotentHint=true, and readOnlyHint=false. Description adds context about clearing sensitive data, which aligns with destructive behavior. No contradictions, but no additional behavioral details 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 no fluff. Every word earns its place, and the most important information (action and usage) is front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage context, and relationship with siblings. Missing explicit mention of success/error behavior, but not critical for this 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%, with parameter 'key' described as 'Memory key to delete'. Description does not add additional meaning or constraints beyond the schema, so baseline score of 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?

Description clearly states 'Delete a previously stored memory by key', which is a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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

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

Explicitly lists when to use: when context is stale, task is done, or clearing sensitive data. Mentions pairing with remember and recall, but does not explicitly state when not to use or alternatives.

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

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

Annotations already declare the tool as safe (readOnlyHint, idempotentHint, non-destructive). The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and produces a specific output format. No contradictions with annotations.

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

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

The description is concise and well-structured: it starts with the core action, explains the process, specifies the output, and lists use cases. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description adequately explains the output format ('standard llms.txt markdown format', 'single text blob') and covers key usage scenarios. The tool's purpose and behavior are fully conveyed.

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 both parameters (url and max_links) with 100% coverage. The description reiterates the purpose but does not add new semantic details beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file', and describes the action of fetching a page, extracting metadata, and outputting standard markdown. It implicitly distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than visibility scanning.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt, auditing a competitor') that clarify when to use this tool. However, it does not mention when not to use it or explicitly compare 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?

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds context about the return content (bibliographic fields, scanned copies with flags) and 'Keyless' indicating no authentication. This goes beyond annotations without contradicting them.

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

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

The description is two focused sentences plus a concrete example. No redundant words. Front-loaded with the core purpose.

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

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

For a simple read tool, the description covers inputs and outputs well. However, it does not address edge cases like missing record, error handling, or rate limits. Given no output schema, a bit more detail on return structure 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 the description adds context: an example record number and instruction to obtain from lookup_by_identifier. This helps the agent understand the parameter's origin and format 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 specifies the verb 'Get', the resource 'single HathiTrust catalog record', the identifier 'record number', and the output: full structured bibliographic metadata and scanned copies with view flags. It distinguishes from siblings like lookup_by_identifier, which returns record numbers.

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 an example and hints at when to use it (after obtaining record_number from lookup_by_identifier). However, it lacks explicit guidance on when to prefer this over sibling tools like check_full_view or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the list of returned fields and scope (caller's subscriptions), but does not mention any additional behavioral traits such as pagination or rate limits. With annotations covering the key behavioral aspects, the description adds some but not extensive context.

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

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

The description is two sentences, front-loaded with the purpose, and uses no unnecessary words. Every word is informative.

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

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

Given that the tool is simple (1 optional parameter, no nested objects, no output schema), the description covers the purpose, return fields, and usage context adequately. It does not explain the output format beyond listing field names, but that is sufficient for this 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% for the single parameter (include_inactive). The description does not add any extra meaning beyond what the schema's description already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the return fields. It explicitly distinguishes the tool from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

The description provides context on when to use this tool: 'to review what you're monitoring before adding more or to find an id to cancel.' It implies when not to use it (when you want to add or cancel directly), but does not explicitly name alternatives like 'subscribe' or 'unsubscribe'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond annotations: it explains the return format (bibliographic records plus copies with full-view/limited flags) and notes that no API key is needed ('Keyless'). This is additive 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 no wasted words: first sentence states the action and supported identifiers, second describes returns, third adds keyless scope. Information is front-loaded and every sentence adds value.

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

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

Given no output schema, the description adequately explains return values (bibliographic records plus copies with access flags). Parameters are fully covered by schema and examples. The tool is simple, and no critical details are missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by listing example identifier values ('424023' for OCLC, '9780030110405' for ISBN) and clarifying that identifiers are standard. This provides practical context for parameter usage, earning a score above baseline.

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

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

The description clearly states the tool's purpose: lookup HathiTrust's digitized-book holdings by standard identifiers. It lists specific identifier types (OCLC, LCCN, ISSN, ISBN, htid, recordnumber) and describes the return of bibliographic records plus scanned copies with access flags. This is specific and distinguishes it from siblings like check_full_view or get_record.

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

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

The description includes 'Keyless — covers 18M+ volumes' which implies broad coverage but does not explicitly state when to use this tool vs alternatives like check_full_view, get_record, or search_within. There is no guidance on prerequisites or when not to use, making it insufficient for an agent to choose correctly among many sibling tools.

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

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

Annotations are all false, so the description carries the burden. It discloses that the tool is rate-limited to 5 per identifier per day, free, and doesn't count against quota. This adds behavioral context beyond what annotations provide. No contradictions.

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

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

The description is concise with four sentences, each serving a purpose: explaining the tool's function, providing use cases, giving content guidelines, and noting rate limits/cost. 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?

Given the tool's simplicity (3 params, no output schema), the description covers all necessary aspects: purpose, usage, rate limiting, cost, and content guidance. It is complete and helps the agent invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing usage examples for the 'type' parameter (e.g., bug, feature) and advising on message content (be specific, 1-2 sentences). It does not repeat schema details but enhances understanding.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It uses specific verbs ('Tell', 'broken, missing, or needs to exist') and distinguishes itself from siblings by being the only feedback tool.

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: for bugs, feature requests, data gaps, or praise. It also advises on how to describe the issue (in terms of tools/packs, not end-user prompts). While it doesn't explicitly state when not to use it, the context is clear and alternatives are not needed as there is no sibling feedback tool.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds value by disclosing the data source (CF analytics-engine), lack of PII, and caching behavior (5min-1h depending on window), going beyond what structured annotations provide.

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

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

Three sentences that are front-loaded and efficient. Every sentence serves a purpose: function, use cases, data characteristics. No redundant or filler text.

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 read-only tool with no output schema, the description sufficiently covers purpose, parameters, use cases, and caching. Could mention the return format (top tools, packs, volume) more explicitly, but overall complete.

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

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

Schema coverage is 100% with one enum parameter. The description explains the meaning of window choices: shorter for hot now, longer for steady-state demand. This adds contextual nuance beyond the schema's simple enum listing.

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 top tools, top packs, and total call volume over a recent window, using a specific verb and resource. It distinguishes from siblings by focusing on aggregated trending data from other AI agents, not individual tool calls.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning with agent needs). No direct comparison with sibling tools or when-not-to-use guidance, but the use cases are clear and actionable.

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

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

The description goes far beyond annotations by detailing the tool's behavior: it requires one parameter (else fails), explains the fill check with book depth, threshold conditions (Jaccard similarity, placeholder filtering), and response structure. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with the critical requirement. Every sentence adds value, though some details (like Jaccard threshold and partition filter) could be considered dense. Still, it earns a high score for clarity.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively covers input requirements, internal logic, response format (with field examples), and links to related tools. It leaves no critical gap for an AI agent to understand invocation and output.

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?

While the input schema already describes both parameters, the description adds significant meaning: it provides concrete examples of slugs and seed questions, explains the purpose of each mode, and notes that full Polymarket URLs are accepted for the event parameter.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with two distinct modes (event and topic) explicitly defined. It distinguishes itself from sibling tools by explaining its unique approach and referencing polymarket_fill_risk for custom sizing.

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 when to use each mode ('event' for a specific market, 'topic' for cross-event scanning) and explicitly directs to polymarket_fill_risk for custom sizing, providing clear guidance 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 is extremely detailed about behavioral traits: it explains the three model families, edge calculations, Kelly fractions, filters, and output structure. Annotations already indicate readOnlyHint=true and idempotentHint=true, and the description adds rich context about caching, diagnostics, and tradeable-edge knobs. 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 very long and detailed, which is necessary given the tool's complexity. However, it could be more structured; the model family explanations are embedded in prose rather than bullet points or separate sections. While front-loaded with a clear purpose, the excessive detail may overwhelm some agents. It earns its place but could be more concise.

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

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

The tool has no output schema, so the description must explain return values thoroughly. It does so: it describes the by_segment structure, fed_candidates, _diagnostics, and what each segment contains. It also mentions caching. Given the tool's complexity and 9 parameters, the description is remarkably complete, covering edge calculation details, filters, and output format.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant extra value beyond the schema: it explains the rationale for slippage_pp (zero trading fees but bid/ask spreads), tradeable-edge filters like max_spread_pp and min_liquidity with specific recommendations, and the min_partition_leg_kelly parameter's behavior. It enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It is specific about the resource (Polymarket markets) and the action (scan and return opportunities). The title 'Polymarket Edges' aligns well. This distinguishes it from siblings like 'polymarket_arbitrage' which likely focuses on specific arbitrage strategies.

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

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

The description provides clear context: built for 'what should I bet on today' and mentions that agents can discover opportunities without paging hundreds of markets. It implies the tool is for broad opportunity discovery. However, it does not explicitly state when not to use this tool versus alternatives like 'polymarket_edge_tracker' or 'polymarket_arbitrage'. The guidelines are present but not exhaustive.

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 and non-destructive behavior. The description adds extensive behavioral details: response structure (tracked, expired, snapshot_dates), edge decay computation, data source (daily closes, not intraday), and limits (60-day TTL, snapshot gaps). No contradictions.

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

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

The description is well-structured and concise, with no wasted sentences. It front-loads the core purpose, then explains arguments, response, and limitations in a logical order.

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 absence of an output schema, the description fully explains the return values and edge cases (expired edges, snapshot gaps). It covers all necessary information for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the description adds minimal value beyond what's in the schema. It restates defaults and constraints but does not provide new insights or examples that 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 explicitly states the tool's purpose: 'Edge persistence and decay telemetry' and answers a specific question about edge age. It distinguishes itself from siblings like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description provides clear context for when to use it ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying usage for historical analysis. However, it does not explicitly state when not to use it or compare 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?

Annotations declare readOnlyHint, idempotentHint, etc. The description adds detailed behavioral context: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict (clean|degraded|cannot_fill), per-leg fill details, thin_legs[], and forced_directional_risk. No contradiction with annotations.

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

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

The description is dense and well-organized with separate sections for modes and bold key terms. However, it is somewhat verbose and could be slightly more concise while retaining all essential 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?

No output schema exists, so the description fully explains return values for both modes, including edge cases like thin legs and directional risk. It provides a comprehensive picture of what the tool returns and under what conditions.

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

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

Schema coverage is 100%, but the description enriches meaning: explains side defaults for single-market and basket modes, clarifies that size_usd in basket mode is settlement notional, and notes clamping range (10–1,000,000). Adds context beyond the schema.

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

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

The description clearly states the purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with specific return fields. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on pre-trade fill risk assessment.

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

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

Explicitly advises when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why partial basket fills create unhedged directional risk and states the requirement for one of 'market' or 'event' parameters.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond annotations, detailing compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and the meaning of various response fields. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with purpose and modes, then details safety fields. While comprehensive, it is slightly lengthy but every sentence earns its place, providing dense information without redundancy. A minor trim would be possible, but overall clarity is high.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly explains the response structure (venue prices, top spreads, safety fields, temporal alignment). It covers edge cases and what to expect, making it complete for agent interpretation.

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

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

With 100% schema coverage, the baseline is 3, but the description significantly enhances parameter understanding by explaining the two modes (topic vs explicit), listing all pre-mapped topic values, and clarifying override behavior. This added context is valuable beyond what the schema provides.

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

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

The description explicitly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like compare_entities and polymarket_arbitrage. It details two modes (topic shortcuts and explicit pairing) and explains the core functionality clearly.

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

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

The description provides explicit guidance on when to use the tool (cross-venue spread analysis) and when not to, by explaining compatibility warnings (non-equivalent bet shapes, semantically unrelated events, temporal misalignment). It also notes that real spreads are rare and pre-mapped does not imply tradeability, setting appropriate 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context about scoping to identifier (anonymous IP, BYO key hash, account ID), 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?

Description is concise (three sentences), front-loaded with primary action, and every sentence adds value. 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?

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers purpose, usage, scoping, and related tools completely.

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

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

Schema coverage is 100% and describes the 'key' parameter. Description adds valuable semantics: omitting key lists all saved keys, enhancing understanding beyond schema.

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

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

The description explicitly states the tool retrieves a value saved via 'remember' or lists all keys when omitted, clearly distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

Provides explicit context for when to use (look up stored context) and scoping details (identifier-based). Mentions pairing with 'remember' and 'forget', though lacks explicit when-not scenarios.

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

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

The description adds context beyond annotations, such as the effect of mark_read to flag events read and the availability of the same feed via a direct GET endpoint. It aligns with the readOnlyHint and idempotentHint 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 composed of five concise sentences, each providing distinct information without redundancy. It is well-structured and front-loaded with the core purpose.

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

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

Given no output schema, the description covers return fields, filtering, and side effects of mark_read. It also mentions an alternative access method, making it complete for a read-only tool.

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

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

With 100% schema coverage, the description reiterates parameters but adds practical examples (e.g., type: 'sec_8k') and explains the mark_read behavior. This provides extra value beyond the schema definitions.

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

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

The description clearly states it pulls fired events from the subscription feed, specifies return fields (source, citation_uri, payload), and filtering options. It distinguishes itself from sibling subscription management tools like list_subscriptions or subscribe.

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 polls work fine and provides an alternative GET endpoint for scripts and dashboards. While it gives good context, it does not explicitly state when not to use this tool versus 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?

The description details the multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback logic, and soft-fail for USPTO. It also mentions the output structure (changes[], total_changes, URIs). Annotations already provide readOnlyHint and idempotentHint, and the description adds significant context without contradiction.

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

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

The description is front-loaded with example queries and is dense with useful information. While it is somewhat long, every sentence adds value; minor improvements could shorten it slightly without loss.

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

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

Given the tool's complexity (multiple sources, fallback, parameter options, and no output schema), the description is remarkably complete. It covers sources, fallback, output fields, citation URIs, and soft-fail behavior, and contrasts with sibling tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the 'since' parameter with examples like '7d', '30d', '1y' and recommending '30d' or '1m' for typical monitoring, as well as clarifying that 'value' accepts ticker or CIK.

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 provides a change feed for a company over a recent time window, with example queries like 'What's new with X' and 'latest on Y'. It distinguishes itself from the sibling 'entity_profile' by specifying when to use the alternative.

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

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

It gives explicit example queries indicating when to use this tool and provides a direct alternative ('Use entity_profile instead when you want the static profile'). It also describes the fallback behavior between GDELT and GNews, aiding decision-making.

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

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

Description discloses key-value pair storage, scoping by identifier, and persistence details (24 hours for anonymous). Annotations indicate idempotent and non-destructive; description aligns and adds behavioral richness 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, each earning its place: purpose, usage, persistence details, pairing with siblings. Front-loaded and 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?

Low complexity tool with two simple string parameters, no output schema, and annotations present. Description covers all needed context: purpose, usage, behavior, parameter semantics, and pairing with related tools.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples of key patterns and value types, and explains scoping, which enhances understanding beyond schema.

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

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

Description clearly states 'Save data the agent will need to reuse later', specifies examples (resolved ticker, target address, etc.), and distinguishes from sibling tools recall and forget by mentioning pairing.

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 you discover something worth carrying forward'. Provides context on persistence differences between authenticated and anonymous sessions. Could explicitly mention when not to use, but strong positive guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description reveals that each call cascades through several internal endpoints, replacing 2-3 manual lookups. This adds operational context about efficiency and composite behavior, which aligns with and enriches the annotation 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 a single paragraph that front-loads the core use case with example queries, then details supported types. Every sentence adds value, but the structure is somewhat dense with technical specifics. It is concise without being overly terse.

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 moderate complexity and full schema coverage (with no output schema), the description covers input semantics, return values for both types, and even internal cascading behavior. It does not address error handling or edge cases, but for a straightforward lookup tool, it provides sufficient context for an agent to use it correctly.

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

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

With 100% schema description coverage, the baseline is 3, but the description goes far beyond the schema. It explains the return values for each type (e.g., for company: ticker + CIK + company_name + URI; for drug: RxCUI + ingredient + brand + citation). It also clarifies acceptable input formats (ticker, CIK, or name for company; brand or generic for drug). This adds substantial meaning beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers needed by other tools. It gives specific examples (ticker, CIK, RxCUI) and supported entity types. However, it does not explicitly distinguish itself from the sibling tool 'lookup_by_identifier', which could also perform identifier resolution, so it misses full sibling 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?

The description instructs 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. It lists supported types and what they return. However, it does not mention when not to use the tool or compare it against alternatives like 'lookup_by_identifier', leaving the agent without exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. No contradictions. Could mention rate limits or internal tool usage more explicitly, but sufficient.

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, no wasted words. Purpose is front-loaded, structure is clear: what it does, how it works, when to use, what it returns. 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?

With 4 parameters, no output schema, the description explains return format (ranked list with score, confidence, signal density). It mentions sibling tool ai_visibility_check but doesn't explicitly state it's called internally. Still complete enough for effective use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: first entity is 'subject' for narrative, context disambiguates, models can be omitted. This improves parameter understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (likely different comparison type).

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 for 'competitive AI-marketing audits' with a concrete example question. It implies when not to use (single entity checks go to ai_visibility_check) but doesn't provide explicit exclusions, still strong guidance.

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

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

Discloses key behaviors beyond annotations: composite call with two data sources, graceful degradation on partial failures, bundlephobia's first measurement can take 5-30 seconds, and that sources_failed will list timeouts. Annotations (readOnlyHint, etc.) are consistent and add 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?

Well-structured: front-loaded with purpose, then sources, usage guidance, limitations, and failure behavior. Every sentence adds value with no redundancy. Length is appropriate for the tool's complexity.

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

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

Comprehensively covers the tool's complexity: lists all returned fields (summary block, advisories, links, alternatives), addresses partial failures and timeouts, and specifies ecosystem limitations. Since there is no output schema, the description fully compensates.

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 package and version described in schema). The description adds no new parameter meaning beyond what schema already provides (e.g., scoped package acceptance, version default). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia to answer 'should I add this npm package?'. It specifies the verb 'scan' and resource 'dependency' with distinct scope (npm ecosystem). This differentiates 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?

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also provides exclusion guidance: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps avoid misapplication.

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 details beyond the annotations: it specifies the embedding model (BGE-base-en), window size (500-char overlapping windows), similarity metric (cosine), character cap (200K chars), and truncation behavior (flagged). These details explain how the tool works internally, which the annotations (readOnly, idempotent) do not cover.

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

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

The description is a single, well-organized paragraph. It front-loads the purpose, then covers usage, return values, pairing, and technical details. Every sentence adds value, and there is no redundancy or fluff. It is concise yet comprehensive.

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

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

For a tool with no output schema, the description adequately explains return values (top-N passages with offsets and similarity scores) and constraints (cap, truncation). It also provides technical details (embeddings, windowing) and suggests a complementary tool. Given the annotations already cover safety and idempotency, the description is complete.

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

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

The input schema has 100% description coverage, with each parameter already well-described. The description adds minimal new information about parameters (only reinforcing that the text should be an already-pulled record and showing example queries). Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record' with specific verbs ('search') and resource ('inside a fetched record'). It distinguishes from siblings by focusing on internal search within an already-fetched record, and it mentions pairing with ask_pipeworx_grounded, setting it apart from other search tools like deep_research.

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

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

The description provides explicit usage guidance: 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context). It also suggests pairing with ask_pipeworx_grounded for grounded answers. It lacks explicit when-not-to-use guidance, but the positive 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?

The description contradicts the idempotentHint: true annotation. Creating a new subscription on each call returns a new ID, which is not idempotent. The description otherwise adds useful behavioral details (account requirements, delivery constraints), but the contradiction is a serious issue.

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 reasonably concise given the complexity, with front-loaded purpose and structured use of lists and examples. A minor reduction in verbosity could improve it, but it is 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?

The description covers account prerequisites, type-specific parameters, delivery options with constraints, return value, and even webhook failure behavior. Despite no output schema, it adequately explains what the agent needs to know 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%, and the description adds significant meaning beyond the schema with concrete examples for each type and delivery channel, and explains constraints like phone verification and daily caps. This greatly helps 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 explicitly states 'Create a proactive monitoring subscription to a live-data event stream', clearly identifying the action (create) and resource (subscription). It also lists supported types and delivery channels, distinguishing it 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?

The description provides clear context on when to use it (for persistent monitoring) and requirements (Pipeworx OAuth account), but does not explicitly exclude scenarios or mention alternative tools. The context is clear but lacks explicit exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the tool returns categorized example questions with exact tool+argument shapes, drawn from a live catalog. No contradiction with annotations.

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

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

The description is slightly long but efficiently packs essential information. It front-loads alternative user queries and clearly structures the purpose, then details the output. Minor redundancy but overall effective.

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

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

Given the tool's complexity (onboarding, one optional parameter, no output schema), the description is complete. It explains input options, output nature (category-bucketed example questions with tool shapes), and usage context. 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%. The description adds meaning beyond the schema by explaining that omitting the topic gives a cross-category spread, and provides example focus areas. This helps the agent understand when to use the parameter.

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 an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs and distinguishes itself from sibling tools like ask_pipeworx and entity_profile.

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

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

The description explicitly advises using this tool first when the agent doesn't know what Pipeworx can do, and explains when to pass a topic versus calling without arguments. This provides clear guidance on when and how to use the tool.

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

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

Beyond annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds ownership enforcement and that historical events remain available via recent_alerts. This provides useful behavioral context.

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

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

Two sentences with no wasted words. The action is front-loaded, and key details (ownership, deactivation) are provided succinctly.

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 single-parameter tool with annotations, the description covers purpose, usage constraints, and side effects adequately. No critical information is missing.

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

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

Schema coverage is 100%; the description of the 'id' parameter as 'Subscription id (uuid) returned by subscribe' adds useful context beyond the schema's basic description.

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

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

The description clearly states 'Cancel a subscription by id', specifying the action and resource. It distinguishes from siblings like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation.

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

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

The description provides context on ownership (only own subscriptions) and the fact that the row is deactivated not deleted, guiding when to use. However, it does not explicitly state when not to use or mention alternatives, but the clarity is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it returns a verdict (confirmed, approximately_correct, refuted, inconclusive, unsupported) along with structured data and citation. It also mentions the data source (SEC EDGAR + XBRL). 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 front-loaded with natural-language triggers and usage guidance, followed by domain details and return format. Every sentence adds value; there is no redundancy or fluff. It is appropriately sized for the tool's simplicity.

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 single parameter with full schema description, comprehensive annotations, and no output schema, the description provides complete context: purpose, triggers, supported domain, return values, and the fact that it replaces multiple calls. No gaps are evident.

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

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

With 100% schema coverage, the parameter is already described in the schema. The description adds meaningful context by explaining the natural-language nature of the claim and providing examples, plus specifying the supported claim types (company-financial). This adds clarity beyond the schema.

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

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

The description clearly specifies the tool's purpose: natural-language claim verification against authoritative sources. It provides multiple trigger phrases ('Is it true that…', 'fact check', etc.) and explicitly states the domain (company-financial claims for public US companies). It implicitly distinguishes from sibling tools by focusing on factual claim verification, which is not covered by any listed sibling.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides clear context by mentioning the supported domain and that it replaces multiple sequential calls, but does not explicitly list alternatives or cases when not to use the tool.

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