Ip Api

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

Annotations already declare read-only, idempotent, and non-destructive. Description adds crucial details: default free model, BYO key for Anthropic with direct payment, and return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

Description is concise and front-loaded with action and output. Slightly verbose on return structure 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?

Covers all relevant aspects: default model, optional Anthropic probing, return format, and use cases. No output schema, but description compensates well by detailing the result 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 description coverage is 100%, so description adds no further parameter meaning beyond schema. 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?

Description clearly states the tool probes LLMs for knowledge of an entity and scores visibility (0-100) per model. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring and probing.

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 context on when to use (AI-marketing audits, brand checks, competitive monitoring) and explains default vs. Anthropic probing. Does not explicitly describe when to avoid or compare to alternatives, but usage is well implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds value by explaining internal routing across 3,751 tools and that output includes stable citation URIs, going 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 dense with useful information and front-loads purpose and usage. Could be slightly more concise but no redundancy. Every sentence serves a 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, description adequately explains expected output (structured answer with citations) and provides enough examples and usage context for the single required parameter. Covers complexity 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% with detailed parameter aliases and descriptions. The description does not add extra meaning for parameters beyond what the schema provides, but lacks format or constraint details. 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?

Explicitly states the tool routes questions to a vast set of sources for authoritative structured data, listing specific domains like SEC filings, FDA drugs, etc. Distinguishes from siblings such as ask_pipeworx_grounded and web search by emphasizing structured answers with citations.

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?

Clear directive to 'PREFER OVER WEB SEARCH' with detailed examples of query types and specific query phrases. Provides context on when to use (factual questions) and contrasts with alternatives, making selection unambiguous.

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 important behavioral details: extraction only from tool result, explicit refusal reasons, and the extra LLM call cost. 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 somewhat long but every sentence adds value: purpose, process, return format, usage guidance, refusal reasons. Front-loaded with the core idea. 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 complexity of the tool (multiple aliases, no output schema, but rich annotations), the description covers purpose, behavior, return format, refusal reasons, and differentiation from siblings. Complete enough for an agent to select 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% (all parameters documented with descriptions). The description lists the main parameter 'question' and its aliases but adds no deeper semantics 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?

Clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads', explains the process of routing, filling arguments, and extracting answers only from tool results, and distinguishes it from the sibling ask_pipeworx by specifying the extra LLM call cost.

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: 'whenever an answer will be quoted, cited, or acted on' and gives concrete examples (financial verdicts, legal claims, etc.). Also advises preferring ask_pipeworx for casual lookups due to cost.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the batch limit (max 100 IPs) as behavioral context beyond annotations, but no other traits are disclosed.

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

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

The description is extremely concise at 4 words, front-loading the core purpose and limit with no unnecessary information.

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

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

With 3 parameters and 0% schema description coverage, the description fails to provide sufficient context. The output schema exists but the description does not mention it or the optional parameters, leaving significant gaps 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 description coverage is 0%, so the description must compensate, but it does not explain any parameters (ips, lang, fields). The schema examples provide some context, but the description itself adds no meaning for the parameters.

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

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

The description 'Bulk lookup (max 100 IPs)' clearly specifies the action (lookup) and resource (IPs) and includes a batch limit. It distinguishes from the sibling 'lookup' tool, though it does not explicitly contrast 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 implies use for multiple IPs with a maximum of 100, but it does not explicitly state when to use this tool versus alternatives like 'lookup' for single IPs, nor does it provide exclusions or prerequisites.

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 extensive behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), including resolution contract, parent event extraction, news fields handling, safety mechanisms, closed market handling, wide spread handling, and cancellation rules.

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

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

The description is comprehensive but verbose, with many examples and edge cases. While front-loaded with a summary sentence, it could be more concise by trimming redundant explanations.

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

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

Despite no output schema, the description thoroughly covers the response shapes, resolvers, parent events, news fields, safety checks, closed markets, wide spreads, and cancellation rules, ensuring the agent can use the tool correctly in diverse 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 description coverage is 100%, and the description adds significant meaning by explaining the flexibility of the market input (slug, URL, question text), the depth parameter options, and the include_raw parameter's impact on response size.

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

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

The description states the tool's purpose with a specific verb ('Research a Polymarket bet') and resource ('Pipeworx data'), and distinguishes it from siblings by detailing its unique capability to resolve, classify, and fan out to category-specific data packs in one call.

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

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

The description explicitly states when to use the tool ('Use for "should I bet on X"...'), and provides context for various scenarios (low confidence, closed markets, wide spreads). However, it does not explicitly exclude use cases or mention alternative tools for similar tasks.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it notes that data is the 'LATEST 10-K revenue + net income + cash + long-term debt from SEC EDGAR/XBRL,' handles off-calendar fiscal years, and returns sorted results and citation URIs. 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 common query patterns, making it immediately scannable. It then provides necessary detail about data sources and output format. While one sentence is long, every sentence earns its place in enabling correct tool selection and invocation.

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 format (paired data + pipeworx:// citation URIs). It explains the data sources, sorting behavior, and handles edge cases like off-calendar fiscal years. The description is sufficiently complete for an agent to use the tool correctly without additional documentation.

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 both parameters. The description adds meaning by explaining what each entity type pulls (company: financial metrics; drug: adverse events, approvals, trials) and how results are sorted. This contextual information goes beyond the enum labels and array item types.

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 concrete example queries ('Compare X and Y', 'X vs Y', etc.) and clearly states the action: side-by-side comparison of 2–5 companies or drugs in one parallel call. It specifies distinct data sources for each entity type and distinguishes from siblings like 'lookup' or 'entity_profile' by emphasizing parallel retrieval over sequential lookups.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It stops short of listing when NOT to use (e.g., for single entity lookup), but the sibling context and the comparative nature imply the exclusion.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds detailed behavior: decomposition into sub-questions, parallel routing, return of verbatim evidence with confidence/source/citation, explicit gaps[], and expected duration (15-60s). 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 front-loaded with purpose and key details, but somewhat verbose (multiple sentences on behavior and output). Every sentence is informative, so no wasted 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 the complexity of the tool (no output schema), the description fully covers purpose, usage, behavior, parameters, prerequisites, expected output format, and timing. It is complete for an AI agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions. Description adds value by explaining depth enum values (quick=3, standard=5, thorough=8) and associated plan requirements, and clarifies that broad questions are expected for the 'question' 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 performs grounded multi-source research in one call, decomposing questions into sub-questions and routing to 3,751 tools. It differentiates from sibling 'ask_pipeworx' by specifying the use case 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 provides when to use ('broad or multi-part questions') and when not ('use ask_pipeworx for single lookups'), including prerequisites (Pipeworx account) and depth tier limitations (thorough requires paid plan).

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 description doesn't need to restate safety. Description adds that the tool returns 'full input schemas (with curated examples)' and results are 'ready to call directly,' 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?

Two sentences, but the first is long and dense with examples. It front-loads the purpose and usage, but could be slightly more concise by grouping examples. Still, every sentence earns its place.

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

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

Given the number of siblings (27) and parameter count (6), the description covers purpose, usage guidelines, output content (top-N tools with schemas), and even suggests a call pattern ('Call this FIRST'). No output schema, but it explains what is returned sufficiently.

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

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

Schema coverage is 100% (all 6 parameters described in schema). Description adds examples of query values ('look up FDA drug approvals', 'analyze housing market trends') and clarifies that 'task', 'q', 'search', 'description' are aliases for 'query', which adds value beyond the schema's dry 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?

Description uses specific verbs ('find', 'browse', 'search', 'look up', 'discover') and clearly identifies the resource ('tools'). It lists many domains (SEC filings, FDA drugs, etc.), making it easy to distinguish from sibling tools like 'lookup' or 'search_within' which likely have narrower scopes.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' giving clear context on when to use. However, it does not explicitly contrast with sibling tools or mention when not to use.

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

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

Discloses important behaviors beyond annotations: fans out across multiple sources, returns specific fields (cik, filings with URIs, fundamentals sorted by period_end), and notes that the patents API is sunsetting and 'soft-fails until reactivated.' Annotations already indicate read-only, idempotent, non-destructive; description adds valuable context about what actually happens.

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

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

Description is dense but every sentence adds value. Front-loads example queries for quick understanding. Slightly verbose in listing data sources, but that information is necessary for an agent to know what to expect. No wasted words.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (cik, filings with URIs, fundamentals, patents, news, LEI) and their formats. Covers limitations (patents soft-fail) and prerequisites (names not supported). Complete enough for an agent to confidently invoke the tool.

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

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

Schema covers both parameters with descriptions, but the description adds crucial detail: value can be a ticker 'AAPL' or zero-padded CIK '0000320193', and names are not supported. This goes beyond the schema's basic type info. Baseline 3, plus extra clarification justifies a 4.

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

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

The description uses specific verbs like 'profile' and lists concrete examples ('Tell me about X', 'research Acme') that map directly to the tool. It clearly states it returns a 'full cross-source profile of a US public company', distinguishing it from sibling tools that do single-source 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: 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view.' Also gives exclusion: 'Names not supported (use resolve_entity first if you only have a name).' Provides clear context for usage decisions.

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 destructiveHint=true and idempotentHint=true. The description's 'Delete' aligns with destructive behavior but adds no further behavioral context beyond what the annotations provide. This is adequate but not enhanced.

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: the first states the core action, the second provides usage context and related tools. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description fully covers the purpose, usage, and relationship with sibling tools (remember/recall).

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

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

Schema coverage is 100% and the description adds no new meaning beyond the schema's description of the 'key' parameter. The phrase 'by key' is redundant, so the description does not compensate for any lack of schema detail.

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 action and resource. It distinguishes itself from siblings by mentioning 'Pair with remember and recall', making the purpose unambiguous.

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related tools, though it does not explicitly state when not to use.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds behavioral details: fetches the page, extracts title/description/links, and outputs standard markdown format. No contradictions. It could mention failure behavior but not required.

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 concise sentences followed by a bullet list of use cases. It is front-loaded with the main purpose and benefit. No unnecessary words.

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

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

Given the tool has only two parameters, full schema documentation, annotations, and a clear output description ('single text blob'), the description is fairly complete. It could mention error handling for invalid URLs or inaccessible pages, but overall 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% for both parameters. Description adds little beyond the schema: confirms url is a full URL and restates default/max for max_links. Baseline is 3 due to high coverage; description adds marginal value.

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

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

The description clearly states the verb 'generate', the specific resource 'llms.txt file', and the purpose for AI crawler indexing. It distinguishes from siblings by being the only tool focused on generating llms.txt files.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitor visibility. It does not mention when not to use or alternatives, but the use cases are clear and specific.

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, covering safety. The description adds that it returns specific fields and that active subscriptions are listed by default, but does not provide further behavioral context beyond what annotations already 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 two sentences long: the first clearly states the tool's purpose and return fields, the second provides usage guidance. Every sentence is valuable and there is no wasted text. It is front-loaded with the 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?

Given the absence of an output schema, the description compensates by listing the return fields. It mentions the parameter and provides usage context. However, it could note that subscriptions are paginated (if applicable) or that an empty list is returned if none exist, but these are not critical 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?

There is one parameter (include_inactive) fully described in the input schema with a clear description. The tool description does not add any additional meaning or usage details for this parameter beyond the schema. Schema coverage is 100%, so baseline 3 applies.

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

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

The description specifies that the tool lists the caller's active subscriptions and includes the return fields (id, type, params, etc.). It is clear and distinguishes from siblings like 'subscribe' and 'unsubscribe' by implying a read-only list operation, but does not explicitly differentiate.

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

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

The description explicitly states when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on appropriate contexts and directly mentions alternatives (adding more, canceling).

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 the behavioral detail that omitting 'ip' uses the caller's IP, which is valuable context beyond annotations. 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 a single sentence, very concise and front-loaded with the purpose. It could be slightly improved by structuring parameter info, but it's 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?

The tool has 3 optional parameters and an output schema. The description covers the core function and IP fallback but omits explanations for other parameters and output format. Adequate but with clear 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 0%, so the description should explain parameters. It only mentions the 'ip' parameter's fallback behavior but provides no details on 'lang' or 'fields'. This is insufficient given the lack of 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: geolocation for an IP address, with a fallback to the caller's IP if omitted. This is a specific verb and resource, and it distinguishes from siblings since no other tool appears to offer geolocation.

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 when to use (need geolocation for an IP) but does not provide explicit guidance on when not to use or mention alternatives. The context is clear but lacks exclusions.

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

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

The description discloses key behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, does not count against tool-call quota, and that team reads digests daily. This adds significant context not present in annotations.

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

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

The description is concise (4 sentences) and well-structured: it starts with the core purpose, then specifies use cases, then provides behavioral and quality notes. Every sentence adds valuable information without redundancy.

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

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

For a feedback tool with no output schema, the description covers input semantics, usage guidelines, rate limits, and what happens after submission (team reads daily). It is nearly complete, though it does not describe any confirmation or response format, which is acceptable for a fire-and-forget feedback tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by summarizing the enum meanings (bug, feature, etc.) and advising on message quality ('be specific, 1-2 sentences typical, 2000 chars max'). It also indicates that context is optional. This extra guidance lifts the 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: sending feedback (bug, feature, etc.) to the Pipeworx team. It uses a specific verb ('Tell... something is broken, missing, or needs to exist') and resource ('Pipeworx team'), and distinguishes it from sibling tools which are query/research oriented.

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, features, data gaps, praise, and other. It also provides a negative guideline: 'don't paste the end-user's prompt.' Rate limits (5 per day) and quota-free behavior are noted, offering clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds context: data source (CF analytics-engine), no PII, caching window (5min-1h). This complements annotations and discloses important behavioral traits.

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

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

The description is concise, front-loaded with the main purpose, followed by bulleted use cases and data source details. 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, read-only, single-parameter tool, the description fully covers purpose, usage, behavior, and data provenance. No output schema is needed as return shape is clearly described.

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

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

Schema coverage is 100% and already describes the 'window' parameter with enum and meaning. The description does not add new parameter-level semantics beyond what the schema provides, 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 it returns top tools, top packs, and total call volume over a window. It specifies the resource (trending data from Pipeworx) and action (returns). It distinguishes itself from siblings like 'discover_tools' by focusing on recent call volume.

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 use cases and advises window selection based on need (shorter for hot right now, longer for steady-state). Although it does not explicitly mention when not to use, the use cases imply the tool is for trending discovery and validation.

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 input schema by stating 'REQUIRES one of event or topic — call with no args fails', while the schema marks both as optional with zero required parameters. This inconsistency undermines trust. Additionally, despite detailed internal logic, the description lacks clarity on failure modes or side effects.

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

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

The description is lengthy but well-structured with clear sections for event mode, topic mode, response format, and fill check. It front-loads the requirement but could be more concise without losing critical detail.

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

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

For a tool with no output schema, the description adequately explains the response structure including opportunities array and partition_check object. It covers both modes and key algorithmic details, though it omits potential error scenarios or edge cases.

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

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

Schema description coverage is 100%, but the description adds substantial value by explaining the semantic differences between `event` and `topic`, including Jaccard similarity threshold, partition filtering, and fill check logic. This goes far beyond the schema's minimal 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?

Clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes between event mode and topic mode, and implicitly differentiates from siblings like polymarket_fill_risk by focusing on discovery.

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 that one of `event` or `topic` must be provided, with guidance on when to use each. References polymarket_fill_risk for custom sizing, providing an alternative. However, does not address when to use other siblings like polymarket_edges.

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 and idempotent. The description adds extensive behavioral details: caching (1h at KV level), diagnostic output, model families, edge calculations, and exclusion of Fed bets. 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 detailed and structured (by_segment sections), but it is verbose. While informative, it could be more concise for quick agent consumption. Every sentence provides value but the length may hinder scanning.

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 comprehensively explains the response structure (top-level by_segment, fed_candidates, diagnostics) and edge metrics. It covers caching, filter knobs, and edge cases (e.g., partition arbs returning zero kelly). Complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond individual parameter definitions, explaining how parameters like min_liquidity and max_spread_pp act as 'tradeable-edge filters' and how min_kelly and min_partition_leg_kelly differ.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific action verbs and a resource, and the unique methodology (model-driven, structural arbitrage, concentrated longshot) distinguishes it from siblings.

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

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

The description provides context for usage: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It implies when to use but does not explicitly state when not to use or compare with siblings like polymarket_arbitrage.

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, so the tool is safe and non-destructive. The description adds behavioral context beyond annotations, such as how snapshots are created ('cache-miss'), limitations ('60-day snapshot TTL'), and that decay numbers are from daily closes (not intraday). 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 relatively concise given the detail, with a clear front-loaded purpose and structured breakdown of response fields (tracked[], expired[], snapshot_dates[]). It includes limitations at the end. While lengthier than ideal, every sentence adds value, and the structure is logical.

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 comprehensively explains the response structure and each field (tracked, expired, snapshot_dates) along with their subfields (trend, decay_pp_per_day, lifespan_days, etc.). It also covers limitations (TTL, gaps, decay computation). For a complex tool with time-series data, the description is complete and self-contained.

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

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

Schema documentation covers both parameters (days, window) with descriptions and defaults. The description adds minimal extra meaning: it refers to 'snapshot family' for window and mentions clamps (2-30) which are also in schema. Since schema_coverage is 100%, baseline is 3; the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's purpose: analyzing edge persistence and decay from daily snapshots. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and identifies the resource (polymarket_edges snapshots). However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the focus on historical telemetry implies a distinction.

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 explains when to use the tool: to distinguish between fresh and old edges. It provides context ('a fresh wide edge and a 3-week-old wide edge are different trades') and implies usage for historical analysis. It does not explicitly list alternatives or when not to use it, but the context from sibling tool names and the description itself offers sufficient guidance.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds extensive context: it walks the order-book ladder, returns specific fields (e.g., top_of_book, slippage_pp, verdict), and warns about partial fills and directional risk. 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 fairly long but well-structured, front-loading the core purpose, then explaining modes and usage. Each sentence adds necessary detail, though it could be slightly more concise without losing meaning.

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

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

Given no output schema, the description thoroughly explains return values, edge cases (thin books), and risks. It integrates well with sibling tools and provides complete context for safe 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 description coverage is 100%, so baseline is 3. The description adds value by explaining how parameters behave differently in single vs. basket mode (e.g., size_usd meaning, side auto-detection). This goes beyond the schema's basic descriptions.

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

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

The description clearly defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing between single-market and basket modes. It explicitly states to use this before acting on polymarket_arbitrage or polymarket_edges signals, thus differentiating 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 explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains when to use each mode and warns about risks like partial fills converting arb into unhedged positions, giving clear context for use vs. 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, not destructive. Description adds extensive context: compatibility_warning conditions, temporal alignment, skipped leg reasons, and response fields, going well 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?

Front-loaded with purpose, but the description is verbose, repeating details about compatibility_warning and modes. Could be more concise without losing 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?

Despite no output schema, the description thoroughly explains response fields (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and covers both modes and edge cases, making it sufficiently complete for a complex tool.

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

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

Schema coverage is 100% with clear descriptions. The description adds context like topic overrides, but that is already implied. Baseline 3 is appropriate as the description does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states it's a cross-venue spread tool, specifies two modes (topic shortcuts and explicit pairings), and distinguishes it from siblings like polymarket_arbitrage.

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

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

Explains when to use (to find spreads) and provides caveats about pre-mapped topics often being untradeable. Lacks explicit comparisons to sibling tools but gives enough context for appropriate use.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds scope (anonymous IP, BYO key hash, account ID) and the behavior when key is omitted, which enriches understanding beyond annotations.

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

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

Three sentences, front-loaded with core purpose, then usage guidance and pairing with siblings. Every sentence adds information without waste.

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 retrieval tool with 1 optional parameter and no output schema, the description covers purpose, usage, scope, and pairing. Annotations handle safety, so completeness is high.

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

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

The description explains the key parameter's purpose and the special behavior when omitted (list all keys), which adds meaning beyond the schema's basic description. Schema coverage is 100%, but the description still adds value.

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

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

The description clearly states it retrieves a saved value or lists all keys, distinguishing it from sibling tools (remember, forget) by specifying the action and resource.

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

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

Provides explicit use cases (ticker, address, notes) and mentions pairing with remember/forget, though it doesn't explicitly state when not to use this tool over 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, consistent with the description's 'Pull fired events'. The description adds behavioral details: returns source, citation_uri, raw event payload, and the effect of mark_read on subsequent calls. 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 at 4 sentences, with the core purpose front-loaded. It proceeds logically through returns, filtering, mark_read behavior, and alternative access. Every sentence adds value, though it could be slightly tighter.

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 parameter count (5, all optional), no required params, no output schema, and rich annotations, the description covers essential usage: return format, filtering options, mark_read side-effect, and alternative access. It lacks explicit mention of pagination or limit behavior but is sufficient 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?

Input schema has 100% coverage with descriptions for all 5 parameters. The description adds value by explaining the effect of mark_read ('flag returned events read so the next call only shows newer ones') and clarifying that 'since' is an ISO timestamp. This enriches 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 'Pull fired events from your subscription feed', specifying both verb and resource. It doesn't explicitly differentiate from siblings like 'list_subscriptions' or 'recent_changes', but the purpose is unambiguous.

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

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

The description provides guidance on filtering (by type and since) and mentions the mark_read flag for subsequent calls. It also notes an alternative access method (GET endpoint). However, it does not explicitly state when NOT to use this tool or contrast with 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?

Discloses fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, date format flexibility, and return structure (changes[], total_changes, citation URIs). Complements annotations effectively with no contradictions.

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

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

Single paragraph that is information-dense and well-structured. Front-loads purpose with examples. No wasted words, though slightly long.

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

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

Despite no output schema, description fully explains return values and behavior. Covers all key aspects of a complex multi-source 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?

Adds significant meaning beyond input schema: explains type='company' only, since examples with ISO and relative shorthand, value as ticker or CIK. Schema coverage is 100%, but description enriches understanding.

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

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

Description clearly defines the tool as a change feed for a company over a specified window, with explicit use-case phrases and fan-out to multiple sources. It distinguishes from sibling entity_profile 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?

Provides clear context for when to use this tool vs entity_profile (static profile use case). Implies usage for 'latest on Y' or 'updates on Acme'. Does not exhaustively list when not to use, but alternative is well-specified.

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 that memory scoped by identifier, persistence depends on authentication (persistent for authenticated, 24h for anonymous). Annotations already indicate idempotent and non-destructive, and description adds 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?

Three sentences, front-loaded with purpose. Every sentence adds crucial information without redundancy.

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

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

Completely covers storage scope, duration, pairing with other tools, and parameter semantics. No output schema needed for write operation.

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

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

Schema has 100% coverage, but description adds value by explaining key-value pair nature, providing key examples (e.g., subject_property) and value type (any text). This goes beyond schema 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?

Clearly states verb 'save' and resource 'data the agent will need to reuse later'. Distinguishes from siblings 'recall' and 'forget' by specifying the action of storing for later retrieval.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, etc.). Also mentions pairing with 'recall' and 'forget' for complete workflow.

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 it as read-only, idempotent, and non-destructive. The description adds that it 'cascades through several lookup endpoints internally', which informs about internal complexity. It also details the return format for each type, including citation URIs.

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

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

The description is well-structured, front-loaded with example queries, and each sentence adds value. It is slightly long but not overly verbose; all information earns its place.

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

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

Given the complexity of two entity types with different inputs and outputs, the description is complete. It explains purpose, when to use, input formats, and outputs (including citation URIs). There is no output schema, but the description covers return values adequately.

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 examples and clarifies that 'value' accepts ticker, CIK, or name for company, and brand or generic name for drug. It also explains what each type returns, adding meaning beyond the schema.

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

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

The description specifies the tool resolves names to identifiers, lists example queries, and explains supported types (company, drug). It distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an ID' and noting it replaces multiple manual 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 says 'Use FIRST whenever you have a name but need an ID', provides clear context and examples. Does not explicitly state when not to use, but the purpose strongly implies it's for name-to-ID resolution, and alternatives like lookup or entity_profile are not mentioned for this specific function.

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 tool probes each entity with ai_visibility_check, aggregates results, and returns a ranked list with score, confidence, and signal density. It does not mention authorization needs (e.g., Anthropic API key) beyond the schema, but annotations cover safety.

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 unnecessary words. The purpose is stated first, followed by process and a concrete use case. Every sentence adds value, and the structure is logical 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?

The description explains the output (ranked list with metrics), which compensates for the missing output schema. It mentions the relationship to ai_visibility_check. However, it does not explain what 'signal density' means or the allowed entity count range (2-8), which is in the schema but not reiterated. Overall adequate for selection and 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?

The input schema covers 100% of parameters with descriptions. The description adds minimal parameter-specific info beyond the schema, such as that entities are compared and that 'anthropic' model requires _apiKey. The baseline of 3 is appropriate since the schema already provides sufficient parameter details.

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

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

The description states it compares AI visibility across entities side-by-side using ai_visibility_check and ranks results. It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities by specifying batch comparison and ranking. The verb 'compare' and resource 'AI visibility' are specific and accurate.

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

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

The description provides a clear use case: competitive AI-marketing audits. It implies that for a single entity one would use ai_visibility_check. However, it does not explicitly state when not to use this tool or mention alternatives like compare_entities. The context is clear but lacks exclusions.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent. The description adds meaningful behavioral detail: it fans out across two services, and bundlephobia's first measurement may take 5-30 seconds, with partial failures listed in sources_failed. This contextualizes the user's experience beyond what annotations provide. However, it does not mention rate limits or authentication, though these are not critical given the read-only nature.

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 information and well-structured, starting with the core value proposition. While it is somewhat lengthy, every sentence serves a purpose. Could be slightly tightened but remains clear 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?

Despite lacking an output schema, the description fully enumerates the return fields (summary block attributes, per-advisory details, links, alternative versions). It also covers limitations (NPM only, partial failures, timing for bundlephobia) and fallback for other ecosystems, making the tool's contract completely transparent.

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

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

Schema covers 100% of parameters with basic descriptions. The description adds practical context: it explains that the version parameter defaults to the latest published, and that scoped packages are accepted. It also ties the parameters to the overall evaluation goal, making the agent better understand how to use them.

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 composite purpose: a single call to evaluate adding an npm package, covering safety (advisories), size (gzip/minified), and other metrics. It names specific sources and outputs, leaving no ambiguity.

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

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

Explicitly describes when to use: when an agent asks about safety, popularity, or size costs. Also clearly scopes to NPM ecosystem in v1 and directs users to alternative tools for other ecosystems, providing clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds rich behavioral context: embeddings model, window size (500-char overlapping), character cap (200K chars) with truncation and flagging, and offset output for verification.

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 that front-loads purpose and usage, then provides technical details. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores), covers use case, pairing, and technical constraints. This is complete for a retrieval tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning through examples for query, clarifies text truncation behavior, and explains limit's role in returning top-N passages. However, it does not significantly augment the schema's already detailed 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 it performs semantic search inside a fetched record, using specific verb+resource ('search inside a fetched record') and distinguishes from siblings like ask_pipeworx_grounded by noting the pairing strategy.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt' and provides a clear alternative (pair with ask_pipeworx_grounded) and examples (SEC 10-K, article).

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

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

The description adds significant behavioral context beyond the annotations: authentication requirement, idempotency not explicitly stated but implied by idempotentHint, delivery channel limitations (phone verification, SMS cap, webhook auto-disable), and webhook signing details. This compensates for the sparse 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 with front-loaded purpose and organized details by type and delivery. While somewhat long, every sentence provides essential information for a complex tool with many options. Minor improvement could be reducing redundancy in delivery descriptions.

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 parameters, nested objects, 5 types, 3 delivery channels) and no output schema, the description covers most aspects: auth, type examples, delivery options, and constraints. It lacks explicit details about the return structure (only mentions subscription id) and idempotency behavior, but overall is quite 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% coverage, but the description goes beyond by providing concrete examples for each subscription type (e.g., 'items:["5.02"] = officer change') and detailed delivery constraints (phone verification, daily cap, webhook signing). This adds value beyond the schema's property 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 action ('Create a proactive monitoring subscription') and the resource ('to a live-data event stream'). It distinguishes from sibling tools like 'list_subscriptions' and 'recent_alerts' by focusing on creation. The return value ('Returns the new subscription id') is explicitly mentioned.

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 strong guidance on when to use the tool, including authentication requirements ('Requires a Pipeworx OAuth account'), supported subscription types with examples, and delivery channel constraints. However, it does not explicitly contrast with alternatives (e.g., 'use this to create, not to list or delete').

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 safe behavior. The description adds behavioral context: it returns category-bucketed example questions drawn from a live catalog, and notes that calling without arguments gives a full spread while passing a topic focuses the results. 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 efficient and front-loaded with key phrases, then explains behavior and usage in a structured manner. The alternative phrasings at the start might be slightly redundant but they quickly convey the tool's intent. Overall, it is well-organized without unnecessary 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?

Despite no output schema, the description fully explains the return format: category-bucketed example questions with tool+argument shapes. It also covers the effect of the 'topic' parameter and positions the tool as an onboarding guide. Given the tool's complexity and the number of sibling tools, the description is complete enough 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 description coverage is 100%. The schema already describes the 'topic' parameter with examples and the effect of omitting it. The description repeats this information without adding significant new semantics beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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: it is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses multiple phrasings ('What can I ask Pipeworx?', 'give me ideas') and clearly distinguishes itself from sibling tools by positioning it as the first tool to use when the agent doesn't know Pipeworx's 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 gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to call with or without arguments. While it doesn't explicitly exclude alternatives, the 'FIRST' directive provides strong contextual usage advice.

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: ownership check, deactivation (not deletion), and idempotency implied. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are consistent, and description adds valuable 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 concise sentences covering purpose, constraint, and behavior. No wasted words, front-loaded with action.

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

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

Complete for a simple tool with one parameter and no output schema. Covers what it does, constraints, and side effects (deactivation, not deletion). 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 covers 100% of the single parameter with description. Description adds no extra meaning beyond 'by id', but baseline of 3 is appropriate given full schema 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 'Cancel a subscription by id' with specific resource (subscription) and action (cancel/unsubscribe). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and that rows are deactivated not deleted, providing clear context for when to use. Lacks explicit alternatives or when-not scenarios, but sufficient for the simple 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, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the return verdict types (confirmed, approximately_correct, etc.), the inclusion of a pipeworx:// citation, and percent delta. It also notes the v1 limitation to company-financial claims via SEC EDGAR + XBRL, which is 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?

The description is concise (4 sentences) and front-loaded with example phrases and the core action. Every sentence serves a purpose: defining usage, specifying domain, listing return values, and highlighting efficiency. No superfluous 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 the single parameter, no output schema, and rich annotations, the description provides complete context. It explains what the tool does, what domain it covers, what it returns, and how it improves efficiency. There are no gaps in understanding for an AI 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 coverage is 100% for the single 'claim' parameter, which has a description. The tool description enhances this by providing concrete examples (e.g., 'Apple's FY2024 revenue was $400 billion') and specifying the domain (company-financial claims), adding semantic 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 tool's purpose: natural-language claim verification. It uses specific verbs ('validate', 'fact check', 'verify') and identifies the resource (claims). It distinguishes from siblings by noting it replaces multiple sequential calls for financial claims, setting it apart from general query tools like ask_pipeworx.

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 scopes the domain to company-financial claims. While it doesn't explicitly mention when not to use it or list alternatives, the use case is clearly defined.

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