Internet Archive

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

The description discloses read-only probing (consistent with annotations), API key pass-through to Anthropic with cost implication, and output structure (per-model fields + combined view). This adds significant context beyond annotations, which already declare readOnlyHint, openWorldHint, and idempotentHint.

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

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

The description is a single, well-structured paragraph of 4 sentences: core function, model options with defaults, return format, and 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?

The description covers all parameters, output format, and use cases. It explains model choice and cost implications. However, it does not mention limitations like rate limits or token limits, which would be useful given no output schema. Annotations partly compensate with openWorldHint and idempotentHint.

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 crucial meaning: default model, optional nature of 'models' and '_apiKey', and the role of 'context' for disambiguation. It clarifies that omitting 'models' uses only Workers AI and that '_apiKey' is only needed for Anthropic.

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 entities and scores visibility 0-100. It specifies default model and optional Anthropic probing. It differentiates from siblings like 'scan_competitor_ai_presence' by mentioning specific use cases (AI-marketing audits, pre-launch checks).

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: use for visibility audits, brand checks, competitive monitoring. It explains when to use which models (free default vs. paid Anthropic). However, it does not explicitly mention when not to use this tool or compare to similar siblings like 'scan_competitor_ai_presence'.

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. The description adds that the tool returns structured answers with stable pipeworx:// citation URIs and routes to thousands of tools, which provides useful behavioral context beyond annotations.

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

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

Description is moderately long but well-organized with examples and lists. Every sentence adds value, though some redundancy (multiple aliases) could be condensed. Front-loaded with the key preference directive.

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 return format (structured with citation URIs). For a complex routing tool, the description is complete enough to set expectations, though more detail on result structure could help.

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 6 parameters all aliases for 'question'. The description does not add new parameter-level details since the schema already covers the single string input. Baseline 3 is appropriate as the description focuses on usage rather than parameter semantics.

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

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

The description clearly states the tool's purpose: answering factual questions about current/historical data from authoritative sources. It explicitly differentiates from web search with 'PREFER OVER WEB SEARCH' and lists specific domains (SEC filings, FDA, etc.), making the scope unmistakable.

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

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

Provides clear guidance on when to use: for factual queries like 'what is', 'look up', 'find', etc. Includes examples and specifies it handles many authoritative sources. Lacks explicit 'when not to use' but the preference over web search implies coverage.

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 return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and lists explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). This adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and does not contradict them.

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

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

The description is concise yet comprehensive, with each sentence providing essential information: purpose, routing, extraction method, return format, refusal reasons, cost trade-off. No redundant or vague statements.

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 there is no output schema, the description fully explains the return values for both success and failure cases. It also covers the tool's behavior (selecting from 3,659 tools, filling arguments, extracting answer) and provides enough detail 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?

Schema coverage is 100%, with all 6 parameters documented as aliases for 'question'. The description does not add additional semantics beyond what the schema provides. 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling tool 'ask_pipeworx' by noting the extra LLM call cost and the fact-based extraction method.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific examples (financial verdicts, legal claims, medical lookups, public statements). Also advises preferring ask_pipeworx for casual lookups.

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

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

The description extensively covers behavioral traits beyond annotations: market resolution, classifier fan-out patterns, response shapes, resolver contract, parent_event extractor, news fallback mechanisms, safety for low-confidence matches, closed market handling, and wide spread warnings. Annotations already indicate read-only, idempotent, non-destructive; the description adds rich detail 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 quite long and detailed. While well-structured with sections (classifiers, fan-out examples, response shapes), it could be more concise. Some details like exhaustive fan-out examples and deep response structure may be excessive for a summary. Front-loaded with purpose and inputs.

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 fan-out classifications, error handling, response shapes), the description is very complete. It covers low-confidence matches, closed markets, wide spreads, fallback mechanisms, and resolver contract. Without an output schema, the description adequately explains return fields.

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

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

Schema coverage is 100% with descriptions. The tool description adds value by explaining the 'market' parameter input types (slug, URL, question text) and providing examples. It also clarifies the 'depth' default and 'include_raw' size implications. While the schema is adequate, the description enhances usability.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies acceptable inputs (slug, URL, question text) and output (evidence packet + market vs model comparison). This distinguishes it from sibling tools like polymarket_edges or polymarket_arbitrage, though not explicitly.

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

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

The description explicitly states: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear when-to-use guidance. However, it does not mention when not to use or contrast with 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?

Adds extensive behavioral context beyond annotations: data sources (SEC EDGAR, FAERS), specific metrics, handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. Annotations already indicate read-only, idempotent, non-destructive; description enriches understanding.

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 packed with useful information but slightly long. However, it is front-loaded with the core purpose and usage examples, making it efficient for an AI agent to parse.

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

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

Covers both entity types, return data (paired data + citation URIs), and replaces multiple lookups. Given no output schema, it provides sufficient expectations. Missing details on error handling or pagination, but acceptable.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the 'values' parameter with examples (tickers/CIKs vs drug names) and clarifies data sources per type, which aids schema 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 uses specific verbs like 'compare' and 'side-by-side comparison' and clearly distinguishes the tool from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups'. It covers both entity types and gives example queries.

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

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

Provides explicit when-to-use scenarios (e.g., 'X vs Y', 'rank these companies') and explicitly prefers this tool over sequential lookups. No when-not-to-use is needed as the use case is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by specifying return format: top-N tools with names, descriptions, full input schemas with examples, and that results are ready to call directly. No contradiction with annotations.

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

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

Description is approximately 4 sentences, front-loaded with core purpose, concise without fluff. Every sentence adds meaningful 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 role as a discovery tool with no output schema, the description sufficiently explains what is returned (top-N, schemas, examples, ready to call). Sibling context is large but description doesn't need to enumerate; it clearly positions the tool as the first step.

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 parameters. Description adds useful context: 'Accepts task, q, description, search as aliases' and default/max for limit. This supplements schema well.

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

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

Description clearly states 'Find tools by describing the data or task' with a specific verb and resource. It lists diverse domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools which are specific tools for specific tasks.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear context for when to use. Does not specify when not to use or name alternatives, but the guidance is clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds substantial behavioral context: it fans out across SEC EDGAR, XBRL, USPTO, GDELT/GNews, GLEIF; lists exact returned fields; notes patents API sunset and soft-fail behavior; and specifies input requirements (ticker or zero-padded CIK). No contradiction with annotations.

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

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

The description is front-loaded with examples and purpose, making it easy to grasp quickly. However, it is moderately verbose, including details like the patents sunset explanation. While every sentence provides value, it could be slightly more concise 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 (parallel search across multiple sources, no output schema), the description thoroughly explains what the tool returns: cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. It also documents limitations (patents sunset, name support requiring resolve_entity). This is complete for an agent to invoke correctly.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds value by explaining that type is limited to 'company' and value must be ticker or zero-padded CIK, and that names are not supported. This goes beyond the schema's enum and simple description.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call,' provides multiple example queries, and distinguishes it from chaining individual lookups. It specifies the resource (profile) and action (produce comprehensive output from multiple sources).

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity first if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructive and idempotent hints. The description adds context about clearing sensitive data and pairing, but does not detail behavior on missing keys or irreversibility, which is acceptable for a simple deletion tool.

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

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

Two concise sentences with no waste; first sentence states purpose, second provides usage guidance.

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

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

Given minimal complexity (one parameter, no output schema), the description covers purpose, usage, and pairing, making it fully informative 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%; the description does not add information beyond the schema's 'Memory key to delete'. 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 'Delete a previously stored memory by key', specifying the verb and resource, and distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly enumerates when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier', and suggests alternatives with 'Pair with remember and recall'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is clear. The description adds behavioral context (fetches page, extracts title/description/key links) beyond annotations, though it doesn't need to add much. 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 four sentences long, front-loaded with the main action, and uses efficient phrasing. Every sentence serves a purpose (what it does, how it does it, output format, use cases). No wasted words.

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

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

Despite lacking an output schema, the description explains the output is 'a single text blob ready to drop at site-root/llms.txt', which is sufficient for a simple tool. It covers input, behavior, and output without gaps.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add new meaning beyond summarizing the tool's behavior. 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 verb ('Generate'), the resource ('llms.txt file'), and scope ('for any URL'). It lists actions (fetches, extracts, emits) and output format, distinguishing it from sibling tools like scan_competitor_ai_presence which have different purposes.

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

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

The description explicitly provides use cases ('useful for: getting a client's site indexed...') which helps the agent decide when to invoke it. It does not explicitly state when not to use or mention alternatives, but the purpose is specific enough that confusion is unlikely.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by specifying the exact metadata fields returned (title, creator, etc.) and the return of a details_url, plus the note about being keyless. It does not contradict annotations and provides concrete behavioral details beyond 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 three concise sentences: first stating purpose and output, second giving usage guidance, third noting authentication. No wasted words, front-loaded with key information.

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

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

For a simple metadata fetch tool with one parameter and no output schema, the description covers purpose, returned fields, prerequisite action, and auth requirement. Annotations supply the safety profile. The description is complete and self-sufficient.

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

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

Schema coverage is 100% with a clear description of the 'identifier' parameter. The tool description reiterates 'by identifier' but adds no further semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Fetch' and the resource 'Internet Archive item's metadata by identifier'. It lists specific fields returned and distinguishes itself from the sibling tool 'search_items' by explicitly instructing to use that tool first to find an identifier.

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

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

The description provides explicit guidance: 'Use search_items first to find an identifier' and notes that the tool is 'Keyless', indicating no authentication is needed. This clearly tells 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by specifying the return fields and the constructed download_url, but does not elaborate on rate limits, authentication (keyless is mentioned but not detailed), or other behaviors beyond what the annotations imply.

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

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

The description is extremely concise with two sentences, front-loading the core purpose. Every word is informative without redundancy.

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

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

Given the tool's simplicity and the presence of rich annotations, the description covers the essential aspects: what the tool lists, the output fields, and the prerequisite step. The lack of an output schema is mitigated by explicitly listing return fields in the description.

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

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

Both parameters (identifier, limit) are fully described in the input schema with 100% coverage. The description adds no additional parameter-specific information beyond what the schema already provides, meeting the baseline of 3.

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

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

The description clearly states the verb 'List', the resource 'downloadable files for an Internet Archive item', and enumerates the fields returned (name, format, size, download_url). It distinguishes from sibling tools like search_items and get_metadata by positioning them as prerequisites.

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

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

The description explicitly instructs to use search_items or get_metadata first to find an identifier, providing clear context for when this tool should be called. However, it does not specify when not to use it or mention alternative tools for filtering.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a behavioral detail: it returns only the caller's active subscriptions (scoping). However, it does not disclose other traits like pagination or rate limits, so the added value beyond annotations is moderate.

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

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

Two concise sentences: the first states purpose and return fields, the second gives usage guidance. No fluff or 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 a simple tool with one optional boolean parameter, good annotations, and no output schema, the description adequately covers what the tool does, returns, and when to use it. Minor omission: no mention of pagination or ordering, but not critical.

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

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

The single parameter 'include_inactive' is fully described in the input schema (coverage 100%). The description does not add further meaning beyond implying default behavior (active subscriptions). Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, params, etc.). The name matches the purpose, and it distinguishes from sibling tools '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 explicitly advises when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it does not explicitly state when not to use it.

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

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

The description adds valuable behavioral context beyond annotations, including rate limits (5 per identifier per day), free usage, no impact on tool-call quota, and that feedback affects the roadmap. This compensates for the absence of annotations like readOnlyHint or destructiveHint.

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 (4 sentences) and well-structured: purpose first, then usage guidelines, then constraints. Every sentence adds essential information with no wasted words.

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

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

Given the moderate complexity (3 parameters including a nested object, no output schema), the description fully covers all parameters, usage context, and constraints. It addresses potential pitfalls (e.g., not pasting user prompts) and is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining each enum choice for 'type', providing context for the optional 'context' object, and specifying the message character limit (2000 chars). While not exhaustive, it enhances understanding without redundancy.

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 sibling tools by its unique feedback function.

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

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

The description explicitly lists when to use the tool for bugs, feature requests, data gaps, and praise. It also states what not to do ('don't paste the end-user's prompt'), providing clear exclusions and context for correct usage.

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

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

Description reveals data source (CF analytics-engine), no PII, and caching (5min-1h). Annotations already cover safety and idempotency; description adds valuable context beyond those.

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

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

Five sentences, each adds value. Front-loaded with primary purpose, then use cases, then data source details. 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?

Covers all key aspects: input, output (top tools/packs/volume), windows, use cases, data source, caching. Lacks explicit return format details, but acceptable for a simple tool without output schema.

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

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

Schema description coverage is 100% with detailed enum and default. The tool description adds no new parameter info beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool returns top tools, packs, and call volume over a recent window. Includes three specific use cases, making the purpose distinct from sibling tools like discover_tools.

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

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

Explicitly lists three scenarios for use (discovering hot data sources, confirming popular tool, aligning use case). Does not explicitly state when not to use, but context is clear.

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

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

Annotations indicate read-only, idempotent, open-world. Description adds behavioral details: parameter requirement, semantic anchor (Jaccard similarity >=0.30), partition filter (placeholder slugs), and response 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?

Well-structured with clear sections, front-loaded with requirement and advice. Slightly verbose but every sentence provides value. Could be tightened slightly 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?

Comprehensive description covers all aspects: input requirement, behavior of both modes, filtering details, and response format. Given no output schema, it fully explains return values including partition_check structure.

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

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

Schema coverage is 100%, but description adds extra meaning: full Polymarket URLs accepted for event parameter, explanation of how topic param triggers cross-event scanning. Adds context beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, with two distinct modes (event and topic). It distinguishes itself from sibling tools like polymarket_edges and polymarket_kalshi_spread by specifying its unique function.

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

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

Explicitly requires one of 'event' or 'topic', warns that no args fails, and recommends which mode to use for specific cases. Provides detailed context on when to use cross-event mode vs single-event mode, including what patterns each catches.

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 extensively details behavioral traits: caching (1h keyed on knobs), response structure (by_segment, fed_candidates, diagnostics), model families, edge calculation including slippage, and market warnings. Annotations already indicate read-only and idempotent, but the description adds critical context beyond annotations.

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

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

The description is very long but structured logically: purpose first, then segment details, then parameter explanations. Some redundancy exists (e.g., repeated mention of segments), but overall it is well-organized and front-loaded with the most important information.

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

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

Given the tool's complexity (3 model families, 9 parameters, no output schema), the description is exceptionally complete. It explains all return fields (edge_pp_net, kelly_fraction, etc.), diagnostics for empty segments, and knob interactions. No output schema is needed given this thoroughness.

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?

Despite 100% schema coverage, the description adds significant meaning for each parameter, such as explaining why min_partition_leg_kelly is needed instead of min_kelly for partition arbs, and detailing the effects of slippage_pp and min_liquidity. This goes well 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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifying the three response segments and distinguishing itself from sibling tools like polymarket_arbitrage.

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

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

The description explicitly states the tool is built for 'what should I bet on today' and explains how agents can discover opportunities without paging. It provides context on when to use it but does not explicitly mention when not to use it or compare directly with all 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?

Discloses behavioral traits beyond annotations (readOnlyHint, etc.): explains compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal alignment considerations, and skipped_cross_type/subtype counters. This fully informs the agent about potential edge cases.

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

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

The description is front-loaded with purpose and modes, then structured into response and safety fields. While slightly verbose, each sentence provides useful information; no waste. Earns a 4 for density of useful content.

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

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

Given no output schema, the description comprehensively covers what the tool returns (leg prices, spreads, safety fields) and handles edge cases (non-equivalent shapes, temporal mismatches). Fully sufficient for correct agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the interaction between parameters (topic vs explicit tickers, override behavior) and the two modes, going 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question, using a specific verb ('Cross-venue spread'). It distinguishes itself from sibling tools like polymarket_arbitrage (intra-venue) by focusing on inter-venue comparison.

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

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

Explicitly describes two usage modes (topic shortcuts and explicit tickers) and provides caveats: 'Real cross-venue spreads are rarer... most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' This tells the agent when results may be unreliable, aiding correct invocation.

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

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

Annotations already declare read-only, non-destructive, idempotent. Description adds: scoping by identifier and the effect of omitting the key. No contradictions.

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

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

Three sentences, front-loaded with action, examples in second, pairing in third. 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?

For a simple tool with one optional param and full annotations, the description covers all essential context: retrieval vs listing, scope, and intentions.

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

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

Schema coverage is 100% with a description. Description adds the critical nuance that omitting the key lists all keys, which goes beyond schema.

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

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

Clearly states the dual function: retrieve a specific value or list all keys. Distinguishes from siblings 'remember' and 'forget' by specifying the complementary pair.

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

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

Provides explicit when-to-use examples (look up context like ticker, address, notes) and why (avoid re-deriving). Mentions pairing with remember/forget and scoping.

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

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

The description discloses the mutation effect of mark_read=true, which goes beyond the readOnlyHint and idempotentHint annotations. However, this creates a contradiction because setting mark_read changes state, conflicting with the idempotentHint=true annotation. Description adds value but inconsistency reduces reliability.

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

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

The description is well-structured with the main action upfront, followed by key details. It is concise without being terse, including only relevant information. A minor reduction might be possible, but overall effective.

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

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

Given no output schema, the description covers returned fields and side effects. Parameters are fully described in schema. The alternative endpoint and polling guidance round out the context. Lacks only explicit if-then conditions or error scenarios.

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 schema already documents each parameter. The description adds some extra context (e.g., example filter 'sec_8k', explains mark_read effect), but does not significantly enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool pulls fired events from a subscription feed, with specific details about returned fields (source, citation_uri, raw event payload). While it does not explicitly distinguish from siblings, it is specific enough to convey the tool's purpose.

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

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

The description provides usage context: filtering by type/since, marking events read, and mentions polling is fine. It also points to an alternative GET endpoint, giving the agent guidance on when to use this tool versus other access methods.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent, but the description adds crucial behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback logic, USPTO soft-failure due to PatentsView API sunset, and acceptance of both ISO dates and relative shorthands. This far exceeds what annotations convey.

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 yet efficiently structured. It leads with an example-driven purpose, then details sources and fallbacks, parameter guidance, return format, and the alternative tool. Every sentence adds information; there is no redundancy or filler.

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 logic, date parsing, soft-failure, grouped output), the description covers all essential aspects. There is no output schema, but the description outlines the return structure (changes grouped by source, total count, citation URIs). The alternative tool is also mentioned, providing complete decision 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?

The input schema already describes all three parameters (100% coverage) with basic descriptions. The description adds value by providing concrete examples for 'since' (e.g., '7d', '30d', '3m', '1y') and a recommendation to use '30d' or '1m' for monitoring, and clarifies that 'value' accepts tickers or CIK numbers. This enriches but doesn't replace 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 opens with concrete query examples ('What's new with X', 'latest on Y'), then defines the tool as a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and contrasts with sibling entity_profile, which provides static profiles. This makes the purpose unmistakable and distinctive.

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

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

Description explicitly directs agents to use 'entity_profile instead when you want the static profile,' providing a clear alternative. It also gives example queries and explains fallback behavior (GDELT→GNews). However, it does not explicitly state when not to use this tool beyond the alternative, slightly limiting 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?

The description adds behavioral details beyond annotations: key-value pairs scoped by identifier, persistence differences (authenticated vs anonymous), and retention time (24 hours). No contradiction with annotations.

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

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

The description is concise with three sentences, front-loads purpose, and is well-structured. Minor redundancy ('later' appears twice) but overall efficient.

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

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

For a simple two-parameter tool with no output schema, the description adequately covers purpose, usage, behavior, and pairing with recall/forget. Could mention if overwriting is allowed, but generally 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%, but the description adds meaningful context by giving key naming conventions ('subject_property', 'target_ticker') and clarifying value can be any text, which helps the agent understand usage 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 saves data for reuse, specifies the resource (key-value pair), and distinguishes from sibling tools recall and forget by naming them.

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

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

The description gives explicit when-to-use guidance with examples ('when you discover something worth carrying forward') but does not explicitly state when not to use or provide alternatives beyond recall/forget.

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 read-only, idempotent, non-destructive. The description adds that it cascades through multiple internal endpoints and returns citation URIs, which adds useful behavioral context beyond what annotations provide.

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

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

The description is front-loaded with example queries, then explains usage, then details each type. It is compact but comprehensive, though slightly verbose in listing output fields.

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 and two entity types, the description covers input formats, output content (including citation URIs), and internal behavior (cascading lookups). It is complete enough for an agent to 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 already covers both parameters with descriptions and enums. The description adds examples for accepted value formats, auto-disambiguation for company, and details on output structure (ticker, CIK, RxCUI, etc.), enhancing 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 resolves names to canonical identifiers, lists example queries, and specifies supported types (company, drug) with details on what each returns. It distinguishes from siblings by being the primary lookup 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 says 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups, providing clear context. No explicit 'when not to use' but sufficient for most cases.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining the probing process, ranking logic, and output structure (score, confidence, signal density per entity), 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?

Four sentences, no fluff. First sentence defines purpose, then explains process, use case, and output. Front-loaded and efficient.

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

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

Covers purpose, process, output format, and use case. No output schema, but description details return fields. Mentions entity count constraint (2-8). Could mention potential rate limits, but overall sufficient for an agent.

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

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

Schema has 100% coverage, so parameters are already well-documented. The description adds extra context: the first entity is treated as the 'subject' for narrative, which is not in the schema, enhancing 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?

Description clearly states the tool compares AI visibility across multiple entities, ranks them by score, and surfaces the most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on competitive AI-marketing audits.

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

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

Provides explicit use case: competitive AI-marketing audits, with an illustrative question. Implies when to use this over ai_visibility_check (multiple entities) but does not explicitly state when not to use or list 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral context: fans out across sources, partial failures degrade gracefully with sources_failed list, and bundlephobia first measurement can take 5-30s. 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 a single dense paragraph that conveys all necessary information without fluff. It could be slightly more structured (e.g., bullet points) for easier scanning, but every sentence earns its place.

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

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

Given no output schema, the description details the return summary block, per-advisory detail, links, and alternative versions. It covers ecosystem scope, partial failure behavior, and timing. Annotations and schema are rich, so the description completes the picture effectively.

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

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

Schema has 100% coverage with descriptions for both parameters. Description adds value by stating scoped packages are accepted, version defaults to latest, and provides an example ('18.3.1'), enhancing the schema's documentation.

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 is a composite check for npm packages using deps.dev and bundlephobia, with a specific verb and resource. It distinguishes from potential alternatives by noting its ecosystem restriction and mentioning direct deps.dev usage for other ecosystems.

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

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

Explicitly tells when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also states limitations: NPM only in v1, and mentions alternative for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns specific fields (identifier/title/creator/year/mediatype/downloads) and notes it is 'Keyless' (no API key required). 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 two sentences plus a note, all essential. It is front-loaded with the core purpose and free of 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?

Despite no output schema, the description mentions return fields. It covers query syntax, filter, disambiguation, and keyless access. Adequate for a 4-parameter tool with one required parameter.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces with examples (e.g., 'apollo', 'creator:NASA') and clarifies the mediatype filter, adding value 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 verb 'search', the resource 'Internet Archive items', and the scope (books, audio, video, software, images). It gives examples and explicitly distinguishes from Wayback Machine snapshots, which differentiates it from sibling tools.

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

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

The description provides clear context for when to use: to find archived items via Lucene queries with optional mediatype filter. It explicitly states what NOT to use for (Wayback Machine snapshots), but does not mention alternatives among siblings.

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

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

Adds significant behavioral detail beyond annotations: returns passages with offsets and scores, uses BGE-base-en embeddings, 500-char windows, 200K char cap with truncation flag. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Well-structured: starts with core purpose, then usage context, then technical details. Slightly verbose with embedding/window specifics, but no wasted sentences overall.

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

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

Covers output format (passages with offsets and scores), limitations (200K char cap), and pairing with another tool. No output schema, so description compensates. Lacks explicit error handling details, but sufficient for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the text cap and provides example queries, but does not add substantial new semantic meaning beyond the schema's parameter descriptions.

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

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

The description clearly states 'semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and the context-saving value.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear context. However, it does not explicitly exclude other scenarios or mention sibling tools directly.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds that it creates a subscription and returns an id, requires OAuth, and notes SMS caps and phone verification. 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 well-structured, starting with a clear purpose, then detailing types and delivery. While somewhat lengthy, every sentence adds necessary information. Could be slightly tightened but remains 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 (multiple subscription types, nested params, optional delivery) and absence of output schema, the description covers return value (subscription id), prerequisites (OAuth account), and operational constraints (SMS cap, verification). No gaps identified.

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 each parameter with concrete examples and constraints (e.g., ticker+items for sec_8k, SMS cap, phone verification). This adds significant value beyond the raw 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 'Create a proactive monitoring subscription to a live-data event stream' and lists supported types and delivery channels, effectively distinguishing it from sibling tools like list_subscriptions or 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 context on when to use this tool (creating subscriptions), specifies required Pipeworx OAuth account, and gives examples for each type. However, it doesn't explicitly state when not to use it or compare with 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 readOnly, openWorld, and idempotent. The description adds valuable behavioral context: it returns live example questions with tool+argument shapes, and explains topic filtering. No contradiction.

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

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

The description is concise and front-loaded with alternative phrasings. Every sentence provides essential information without fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: covers purpose, usage, parameter options, and categories. No gaps.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema by listing possible topic values and explaining that omitting gives a cross-category spread.

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

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

The description clearly states the tool is the onboarding entry point that returns category-bucketed example questions. It distinguishes itself from siblings as a first-use tool to explore Pipeworx capabilities.

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

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

The description explicitly says to use this first when you don't know what Pipeworx can do, and to learn about meta-tools. It lacks explicit exclusions or alternative tool comparisons, but the context is clear.

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

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

The description adds behavioral context beyond annotations: ownership enforcement and soft-delete behavior. It aligns with annotations (destructiveHint=false, idempotentHint=true) without contradiction.

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

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

The description is two sentences with a parenthetical, containing only essential information. No fluff or redundancy.

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

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

Given the annotations and single-parameter schema, the description covers all necessary context: cancellation action, ownership, and soft-delete behavior. No output schema exists, so return value is not expected.

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 does not add further meaning to the 'id' parameter beyond what the schema already provides (uuid returned by subscribe).

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

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

The description starts with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes from sibling tools like 'subscribe' (which creates) and 'list_subscriptions' (which lists).

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

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

The description implies usage context by stating ownership enforcement and that the row is deactivated, not deleted. It lacks explicit when-not-to-use instructions but provides clear context for proper invocation.

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 context beyond annotations: it reveals data sources (SEC EDGAR + XBRL), return format (verdict types, actual value, pipeworx:// citation, percent delta), and consolidates multiple steps. This is consistent with the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is concise yet packed with essential information: example queries, purpose, limitations, return values, and efficiency benefit. Every sentence adds value, and the structure is well-organized with clear headings.

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 and high schema coverage, the description adequately explains the tool's functionality, domain, data sources, and output. There is no output schema, so the explicit description of return values is crucial and well-provided.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by providing natural-language examples and clarifying the domain (company-financial claims). This extra context enhances understanding of what constitutes a valid claim.

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 verifies natural-language claims against authoritative sources, specifically company-financial claims via SEC EDGAR and XBRL. It defines the verb (validate/verify), resource (claims), and scope, and distinguishes from siblings by noting it replaces 4-6 sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also mentions the v1 limitation to company-financial claims, providing context on when to use it. While it doesn't explicitly list when not to use it, the limitation serves as a guideline.

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