Greynoise

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

The description discloses important behavioral traits beyond annotations, such as the free default model, the BYO key for Anthropic with direct payment, and the return structure per model and combined. It does not contradict any annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is two sentences long, front-loaded with the core action, and every sentence provides essential information without redundancy.

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

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

Despite no output schema, the description adequately explains the return structure (per-model and combined view) and covers the four parameters well. It is complete for the tool's complexity.

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

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

With 100% schema description coverage, the description adds meaningful context beyond the schema, including the default model for the 'models' parameter, the pass-through nature of '_apiKey', and the disambiguation purpose of 'context'.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for what they know about a business/brand/product/topic' and distinguishes this tool from siblings by focusing on scoring visibility (0-100) per model, specifically for AI-marketing audits and brand checks.

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

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

The description provides explicit usage contexts such as 'AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains the default model and the optional use of Anthropic with a BYO key. However, it does not explicitly state when not to use this tool versus alternatives, though its uniqueness among siblings reduces the need.

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. Description adds valuable behavioral context: routing to ~5,000 tools, filling arguments, returning structured answers with pipeworx:// citation URIs. No contradictions with annotations.

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

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

Description is well-structured with a clear hierarchy: directive, scope, usage guidance, examples, sibling differentiation. Slightly verbose but every sentence adds value. Front-loaded with most critical 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?

Completely covers all aspects: purpose, usage, alternatives, input format, examples, and output format (structured answer with citations). No output schema is provided, but description adequately describes the return value. Agent has all necessary information.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description enhances semantics by providing numerous examples of acceptable questions and clarifying that natural language is expected, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: answering factual questions about current/historical data from authoritative sources, with specific examples. It distinguishes itself from siblings by positioning as the default entry point and contrasting with alternatives like ask_pipeworx_grounded and deep_research.

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

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

Explicitly directs when to use this tool ('START HERE'), when to prefer web search, and when to step up to other tools (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part questions). Also provides specific question types and example queries.

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

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

Beyond the provided annotations (readOnlyHint, openWorldHint, etc.), the description adds significant behavioral context: it is an experimental routing improvement with source-preference ranking, results are compared against the stable router, and it is a full working router with no fallback. No contradiction with annotations.

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

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

The description is a single, information-dense paragraph that front-loads the key identity ('Beta version of ask_pipeworx') and then expands with specific behavioral differences and usage instructions. Every sentence adds value, with no wasted words.

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

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

Given the tool's nature as a beta variant of a well-known tool, the description provides enough context: what it does, how it differs, how to use it, and its relationship to the stable router. The lack of an output schema is mitigated by the mention of 'same response shape'.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description reinforces that the tool accepts the same arguments as ask_pipeworx, which adds marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, specifies it is an identical universal router with the same 5,008 tools and arguments, and highlights the unique source-preference ranking feature. This distinguishes it effectively from siblings like ask_pipeworx (stable) and ask_pipeworx_grounded.

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

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

The description explicitly states when to use it ('when you want the newest routing') and compares it to the stable router. It does not list explicit exclusions but implies alternative use of ask_pipeworx for stability. The guidance is clear though not exhaustive.

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

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

Description adds value beyond annotations by detailing the refusal mechanism (explicit refusal with reasons) and the extra LLM call cost. However, includes some unnecessary internal routing details that could be omitted.

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 lengthy with redundant details (exact refusal reasons, internal routing). While front-loaded with the key purpose, it could be more concise without losing clarity.

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

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

Given no output schema, the description thoroughly explains the return format on success and failure, including evidence, confidence, source, and refusal reasons. Covers all important aspects for a high-stakes tool.

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

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

Schema description coverage is 100%, with all aliases documented. The description reiterates that the parameter accepts natural language but does not add new semantic information beyond what the schema provides.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, specifying the verb (answer with grounding) and distinguishing from the sibling ask_pipeworx by noting the extra filtering step.

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

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

Explicitly states when to use (when answer will be quoted, cited, or acted on, and agent must not invent facts) and when to prefer ask_pipeworx for casual lookups, providing clear context and alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations. It covers fan-out patterns, response shapes, resolver contract (match confidence, alternatives), parent_event extractor, news fallback fields, safety checks (low-confidence, closed markets), wide-spread market warnings, and resolution-rule risk. Annotations already indicate read-only, idempotent, and non-destructive; the description adds critical context about behavior under various conditions.

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

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

The description is very long and detailed, covering many aspects. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loads the purpose. However, it is not concise; several sentences provide extensive detail that could be condensed. For an AI agent, the length may be acceptable, but it slightly detracts from quick comprehension.

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, no output schema), the description is remarkably complete. It covers input variations, classification, fan-out to data sources, response fields, resolver contract, parent_event extraction, news fallback, safety checks, wide-spread warnings, and resolution-rule risk. Almost every conceivable aspect is addressed, leaving no gaps for an agent to stumble.

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%, meaning each parameter already has a description. The tool description adds value by providing examples of market_input (slug, URL, question text), clarifying the depth parameter's effect ('quick = 2-3 evidence sources, thorough = full fan-out'), and explaining include_raw's impact on response size. This contextualization enriches the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and key action (pulling Pipeworx data). The description also details inputs (slug, URL, question text) and outputs, making it highly specific. While it doesn't explicitly differentiate from siblings like polymarket_edges, its unique function as a general research tool is evident.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context. However, it does not mention when NOT to use this tool or list alternative tools for comparison, which would improve the score. The sibling tools are provided in context but not referenced in the description.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive hints. Description adds rich behavioral details: data sourced from SEC EDGAR/XBRL for companies (handling off-calendar fiscal years), FAERS/FDA for drugs, results sorted by primary metric, citation URIs returned. No contradictions.

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

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

The description is well-structured and front-loaded with example phrases. Every sentence adds value, though slightly verbose with repetition of the preference statement. Good clarity without significant 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?

Given the tool's complexity (two entity types, multiple data sources, comparison logic), the description covers purpose, when to use, what data is returned, sorting behavior, and citation URIs. No output schema needed further details. Complete for an agent to decide 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 for both parameters. Description further explains type enum values and values parameter specifics (tickers/CIKs for companies, drug names) with max/min constraints and examples, adding clarity beyond schema.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with example queries ('compare X and Y', 'rank these companies'). It distinguishes from siblings by recommending over sequential single-pack 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 when to use: for comparing entities, with type-specific data sources. Guides preference over alternative approaches ('ALWAYS PREFER over sequential single-pack lookups'). Includes example usage patterns.

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

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

The description adds substantial context beyond annotations: account requirement, parallelism details, return structure (gaps, contradictions, hop field, citation URIs), timing expectations, and semantic excerpting. Annotations already declare readOnlyHint/openWorldHint/idempotentHint/destructiveHint, and the description reinforces and extends this without contradiction.

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

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

The description is lengthy but each sentence adds necessary context. It is front-loaded with the most critical information (account requirement and core functionality) and logically structured. Minor redundancy could be trimmed, 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?

Despite no output schema, the description fully explains the return format (findings packet, gaps[], contradictions[], hop field, citation_uri), timing, and edge cases like large records. It covers all needed details for the tool's complexity.

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

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

Both parameters are fully covered by the schema (100% coverage). The description adds meaningful detail: for 'depth', explains each enum value's behavior (number of facets, hops, contradictions scan); for 'question', confirms natural language and encourages broad/multi-part queries. This significantly helps agent usage.

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

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

The description clearly states the tool performs 'grounded multi-source research across Pipeworx's 1318 STRUCTURED data sources' using parallel decomposition, contrasting it with sibling ask_pipeworx. It uses specific verbs ('research', 'decomposes', 'routes') and specifies the resource ('structured data sources').

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

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

Explicitly advises when to use deep_research (broad/multi-part questions on structured data) versus ask_pipeworx (single lookup, breaking news). Also provides account requirements and alternative (ask_pipeworx for non-signed-in users). Guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results are ready to call directly without a second schema lookup, providing some extra context but not significantly expanding on 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 two well-structured sentences that front-load purpose and quickly convey key details. It is concise without sacrificing clarity, though slightly longer due to examples.

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 (6 parameters, no output schema), the description sufficiently explains the return format and provides usage context. It lists multiple domains and confirms that results include schemas, covering essential information.

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 explains that the query parameter accepts natural language and has aliases, but this is already covered in the schema. It mentions curated examples in results, which adds minimal value for parameter semantics.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains the output format, making it distinct from sibling tools that perform other searches or retrievals.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear usage context, although it lacks explicit when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: patents sunsetting (soft-fails), news via GDELT→GNews fallback, and details of returned fields (cik, recent_filings with URIs, fundamentals sorted, etc.). 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 example queries and then provides a structured list of return items. While it is somewhat lengthy, every sentence adds value and there is no redundant information. Could be slightly more compact, 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?

No output schema exists, so the description carries the full burden of explaining return values. It lists all major fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and includes details like sorting order and URI format. It also mentions limitations (patents sunset, news fallback). Almost complete, though specifics of the fundamentals objects could be more detailed.

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

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

Schema coverage is 100% (both parameters described). The description adds meaning beyond schema by specifying exact input formats ('AAPL' or '0000320193'), clarifying that names are not supported, and providing examples. Slight improvement over 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 with example queries ('Tell me about X', 'company profile for Microsoft') and defines it as 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes from sibling tools by explicitly preferring this over chaining single-pack 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 gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use (if user has only a name, use resolve_entity first) and what input formats are required (ticker or zero-padded CIK, not names).

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds minimal new behavioral context beyond confirming deletion, which is sufficiently covered by the annotations.

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

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

Two sentences containing only essential information: the action and usage context. 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 single-parameter, no-output-schema tool with rich annotations, the description covers purpose, usage, and pairs with sibling tools, making it fully sufficient.

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

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

Schema coverage is 100% with 'key' described as 'Memory key to delete'. The description does not add further meaning to the parameter, 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?

Explicitly states it deletes a previously stored memory by key, distinguishing it from sibling tools like 'remember' and 'recall' which store and retrieve.

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

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

Provides clear guidance on when to use (stale context, task done, clear sensitive data) and hints at alternatives (pair with remember and recall).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: fetches the page, extracts title/description/key links, emits markdown. 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 compact, front-loaded with action and outputs, no filler. Three sentences efficiently convey purpose, behavior, and use cases.

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

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

Output schema absent, but description explains return value as a text blob for site-root/llms.txt. Covers core transformation clearly. Missing error handling or URL validation notes, but acceptable for a straightforward 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?

Input schema has 100% coverage with descriptions for both parameters. Description adds process context but doesn't significantly enhance parameter understanding beyond schema defaults (e.g., max_links default of 25). Baseline 3 with high 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?

Description clearly states it generates an llms.txt file for a URL, specifying the target AI crawlers and the output format. Distinguishes itself from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

Provides explicit use cases: indexing client sites, drafting personal projects, auditing competitors. Lacks explicit when-not-to-use or alternative comparisons, but the sibling list helps agents differentiate.

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

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

The description adds significant context beyond the annotations: it specifies the need for an API key, details the return fields (noise, riot, classification, entity name, last-seen date, deep link), and explains the meaning of 'noise' and 'riot'. Annotations already indicate read-only, idempotent, non-destructive behavior, so the description complements them well without contradiction.

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

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

The description is a single, efficient sentence that states the purpose and lists what the tool returns. Every word is informative, and there is no redundancy. It is easy to parse and front-loaded with the primary action.

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

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

For a simple single-parameter tool with an output schema, the description explains the return fields and provides a deep link for SOC triage. It does not cover error cases (e.g., missing API key, invalid IP) but the schema and annotations partially address safety. Overall, it is sufficiently complete for its complexity.

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

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

There is only one parameter 'ip' with schema description 'IPv4 address'. The description reiterates that it classifies an IPv4 address but does not add new semantics about the parameter format, constraints, or examples beyond what the schema provides. Since schema coverage is 100%, baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Classify an IPv4 address using the GreyNoise Community dataset (BYO API key).' It specifies the resource (IPv4 address), the action (classify), and the data source. It also lists the specific return fields, providing full clarity. Among sibling tools, none directly overlap, so it is well-distinguished.

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 the tool (for IP classification) and mentions a prerequisite (BYO API key). However, it does not provide explicit guidance on when not to use it or compare it to alternative tools like 'ai_visibility_check'. The context lacks exclusions or usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return fields and default behavior (active subscriptions), providing useful context beyond annotations.

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

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

Two concise, front-loaded sentences. No wasted words; every sentence adds value.

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

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

Given no output schema, description lists return fields. Parameter and usage are fully addressed. Complete for a simple list 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 a description for 'include_inactive'. Description clarifies default behavior (active only), adding slight extra value beyond schema.

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

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

Clear verb ('List') and resource ('subscriptions') with scope ('caller's active'). Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Context is clear, though no exclusion of 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 don't cover rate limits or cost, but description adds rate-limited to 5 per identifier per day, free, doesn't count against quota, and mentions team reads digests daily. 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?

5 sentences, front-loaded with purpose, includes usage guidelines and constraints. Efficient but could be slightly shortened without losing value.

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

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

For a simple feedback tool with no output schema, description covers all needed aspects: when to use, how to format, behavioral constraints. Complete for agent decision-making.

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 3. Description doesn't add new parameter info beyond schema; however schema itself is detailed. No need for extra 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?

Description clearly states action (tell the Pipeworx team) and specific types of feedback (bug, feature, data_gap, praise). Distinguishes itself from siblings which do feedback or similar actions.

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: for wrong/stale data, missing tools, praise. Provides anti-pattern (don't paste end-user prompt) and additional context (rate limit, free, no quota).

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: self-aggregating from CF analytics-engine, no PII, just (pack, tool, count), and caching duration (5min-1h depending on window). 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 concisely structured: a single paragraph followed by a bulleted list of use cases. Every sentence adds value, and the main purpose is front-loaded. No fluff or redundancy.

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

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

Given the tool has only one optional parameter, no output schema, and detailed annotations, the description is complete. It explains what is returned, window choices, caching, and use cases. No missing information for correct agent invocation.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the window enum values: shorter windows surface what's hot right now, longer windows show steady-state demand. This goes beyond the raw enum list.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows (24h, 7d, 30d). It uses a specific verb ('returns') and resource ('top tools, top packs, total call volume'), and distinctly differentiates from siblings like discover_tools and search 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 explicitly lists three use cases (discovering hot data sources, confirming canonical tool, seeing use case alignment) and explains caching behavior. It provides clear context for when to use this tool, though it doesn't explicitly state when not to use it.

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

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

Annotations indicate read-only, non-destructive behavior. The description goes into depth about internal logic: monotonicity checks, Jaccard similarity (0.30 threshold), partition filters (placeholder slugs), and fill_check against live CLOB depth with realizable_edge_pp <= 0 as a no-trade signal. This far exceeds what annotations provide.

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

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

The description is front-loaded with the core purpose and then details modes and logic. It is longer than average but every sentence adds value given the tool's complexity. Could be slightly more concise by omitting some technical details, but overall well-structured.

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

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

Describes output fields (opportunities[], gap_pp, suggested_trade, etc.) for event mode and mentions fill_check outputs. However, it does not explicitly define the output shape for trending_scan (no args) or cross-event mode, leaving some ambiguity. Given no output schema, this is a minor gap.

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

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

Both parameters (event, topic) are described in the schema with full coverage. The description adds rich context: examples, recommendation for event mode, and details on how both modes work (e.g., partition_check in event mode, cross-event scanning with similarity threshold). This significantly enhances understanding beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between event and topic modes with specific examples, and contrasts with sibling tools like polymarket_fill_risk by describing when to use each.

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

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

Provides explicit guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. Includes examples of slugs and seed questions, and explains the differences between modes, including that cross-event catches patterns single-event misses.

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

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

The description extensively covers behavioral traits beyond annotations, including model details, caching (1h at KV level), output structure with diagnostics, and conditions for empty segments. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

The description is very long and densely packed with technical details, making it somewhat verbose. While the front-loading is effective, the wall of text structure reduces readability. A more structured format (e.g., bullet points for segments) would improve conciseness.

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

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

Given the complexity (9 parameters, no output schema, many siblings), the description is remarkably complete. It covers the response structure, diagnostics, caching, edge cases (Fed bets), and filter logic. Everything an agent needs to understand tool behavior is present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for several parameters, such as slippage_pp explaining Polymarket fee structure and min_partition_leg_kelly clarifying why min_kelly doesn't filter partitions. This adds meaningful 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with the explicit use case 'what should I bet on today'. It distinguishes itself from siblings by focusing on edge detection rather than pure arbitrage or tracking.

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

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

The description provides clear context for when to use (discovering opportunities without paging hundreds of markets) and details tradeable-edge knobs to filter for realizability. However, it does not explicitly state when not to use it or compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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=false. The description adds significant behavioral context: data source (daily snapshots), computed fields (trend, decay), LIMITS (60-day TTL, decay from daily closes not intraday). No contradiction.

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

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

The description is relatively long but well-structured with clear sections (purpose, args, response, limits). Each sentence adds value, though slightly verbose in places.

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

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

No output schema, so description fully explains response structure (tracked, expired, snapshot_dates) and limits. Very complete for a tool with 2 optional params.

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%; description adds default values, explains the response structure, and provides context for both parameters 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 provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?' It distinguishes from siblings like 'polymarket_edges' by focusing on time-series vs current edges.

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

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

The description gives good context on when to use (to differentiate fresh vs old edges) and hints at alternatives, but does not explicitly state when not to use or name sibling tools.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds detailed behavioral context: walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains basket-mode forced directional risk. No contradiction with annotations.

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

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

The description is well-organized: starts with purpose, then required parameters, then details each mode, and ends with usage guidance. While somewhat long, every sentence adds value. Could be slightly more concise 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?

Given no output schema, the description thoroughly explains return fields for both modes (top_of_book, vwap_fill_price, shares_filled, etc.) and addresses edge cases like forced directional risk and thin books. Covers all necessary context 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 extra meaning beyond schema: clarifies side defaults per mode, size_usd interpretation (max spend vs target proceeds), and the clamp range (10–1,000,000). This adds value, but the schema already does a good job describing 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket) and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explaining the risk of partial fills and uncapturable overround.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains when not to use (theoretical overround on thin books) and the dominant loss mode (directional risk from partial fills).

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 detailed behavior beyond annotations: explains safety fields (compatibility_warning, temporal_alignment), skipped cross-type/subtype counters, and when spreads are unreliable. Annotations already indicate read-only, idempotent, and non-destructive, and description adds rich 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?

Well-structured with clear sections: purpose, modes, response, safety fields. Front-loaded with main purpose. Slightly verbose but every sentence adds value.

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

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

Covers input modes, output structure (leg-by-leg prices, matched spread, safety fields), and edge cases (compatibility, temporal alignment). No output schema, but response is well-described. Could explicitly state JSON format.

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

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

Schema coverage is 100% with descriptions. Description adds value by listing the ten topic macros, providing example values for explicit parameters, and explaining how explicit overrides topic. Provides format hints (e.g., 'KXFED-26OCT').

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 explicitly states it computes cross-venue spread between Kalshi and Polymarket, and distinguishes two modes (topic shortcuts and explicit pairs). It clearly differentiates from siblings by its focus on cross-venue comparison, not intra-venue 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?

Provides clear guidance on when to use each mode (topic for pre-mapped macros, explicit tickers for custom pairs). Warns that real spreads are rare and mentions compatibility warnings. However, does not explicitly compare to alternative sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond annotations: scoping ('to your identifier'), and the pairing with remember/forget. 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 efficiently structured: a single core sentence followed by short contextual notes. Every sentence adds value, and there is no redundancy or filler.

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

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

Despite lacking an output schema, the description sufficiently covers the tool's behavior, scoping, and relationship to siblings. For a simple retrieval tool with one parameter, the description is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100% and already documents the key parameter's behavior. The description repeats the omit-to-list-all behavior but adds no further syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'retrieve' or 'list' and the resource 'saved values/keys'. It distinguishes from sibling tools by explicitly referencing 'remember' and 'forget', and provides concrete use case examples (target ticker, address, research notes).

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

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

The description gives clear context on when to use the tool ('look up context the agent stored earlier') and explains the effect of omitting the key argument. It does not explicitly list alternatives or when-not-to-use, but the sibling tools and the pairing with remember/forget provide 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 include readOnlyHint=true, but description introduces mark_read parameter that modifies state (flags events read). This is a clear contradiction. No further behavioral details (auth, rate limits) are provided, and the contradiction undermines transparency.

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

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

Four sentences, each with distinct purpose: purpose, return fields, filter options, usage advice. No redundant words, front-loaded with action verb 'Pull'. Highly 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 return structure, parameters, and use case. Lacks error handling, pagination details, and what happens with empty results. With no output schema, some ambiguity remains, but overall sufficient for a tool with simple parameters.

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% description coverage, so baseline is 3. Description adds meaning beyond schema by explaining the return structure (source, citation_uri, raw payload) and clarifying the effect of mark_read on subsequent calls. This additional context justifies a higher score.

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

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

The description clearly states the tool pulls fired events from subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and lists filtering options. This distinguishes it from sibling tools like subscribe/unsubscribe which manage subscriptions, not read alerts.

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 guidance on when to use (polls work fine) and an alternative (direct GET endpoint for scripts/dashboards). Does not explicitly exclude other scenarios but sufficiently implies use case for retrieving alerts via MCP.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: fallback logic, USPTO soft-fail until reactivated, return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). 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 one paragraph but efficient; front-loaded with example queries, then details sources, parameters, and return. Every sentence adds value, though a bit long. Could be slightly more concise but still well-structured.

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

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

Given no output schema, description fully explains return: structured changes[] grouped by source, total_changes count, citation URIs. Also covers fallbacks, limitations, and parameter details. Highly complete for a tool with 3 required parameters.

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

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

Schema description coverage is 100% with descriptions for all 3 required parameters. Description adds extra meaning: explains 'since' accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' or '1m', and notes 'value' can be ticker or zero-padded CIK. This goes beyond the schema.

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

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

Description clearly specifies the tool provides a change feed for a company in a recent window, listing sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly contrasts with sibling tool 'entity_profile'. The verb 'provides change feed' with resource 'company in last N days' is specific.

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

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

Description gives many example queries ('What's new with X', 'latest on Y') that signal when to use this tool, and explicitly states 'Use entity_profile instead when you want the static profile', providing clear usage boundaries. Also details fallback behavior (GDELT→GNews) and USPTO limitation.

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 write operation (readOnlyHint false), idempotent (idempotentHint true), not destructive. Description adds scoping by identifier, session persistence (24h for anonymous), which enriches understanding beyond annotations. No contradiction.

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

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

Four sentences, front-loaded with purpose, every sentence adds distinct information (scope, use case, persistence, pairing). No wasted words.

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

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

Covers essential behavioral aspects (scope, persistence, pairing) and use cases. No output schema, but return value is straightforward (none needed). Slightly could mention overwrite behavior, but idempotentHint implies safety.

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

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

Schema covers both parameters with 100% description coverage. Description adds value by providing example key formats (e.g., 'subject_property', 'target_ticker') and context about what values can contain, slightly enhancing parameter meaning.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, with concrete examples like 'a resolved ticker, a target address, a user preference', and distinguishes from sibling tools (recall, forget) by specifying it's for storage.

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

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

Explicitly advises use 'when you discover something worth carrying forward' and mentions pairing with recall and forget. Also explains persistence differences for authenticated vs anonymous users, but doesn't explicitly state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that each call cascades through endpoints internally, which is useful but not critical beyond annotations. No contradictions present.

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 structured with example queries first, then supported types with details. It is informative but slightly verbose; however, every sentence adds value. Front-loaded with common use cases, making it easy to scan.

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

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

Despite lacking an output schema, the description explicitly lists return fields for each type (e.g., ticker, CIK, company_name, citation URI for company). It also notes auto-disambiguation and internal cascading. For a lookup tool with two parameters, this is complete and leaves no ambiguity.

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

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

Schema coverage is 100%, with both parameters (type and value) well-described in the schema. The description adds examples and clarifies accepted input formats (e.g., ticker, CIK, or name for company), but this adds modest value over the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs like 'resolve' and lists example queries ('What's the ticker for...'), clearly stating it converts user-spoken names to official identifiers. It distinguishes itself by specifying support for 'company' and 'drug' types with specific outputs, setting it apart from siblings like 'entity_profile' or 'compare_entities'.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID' and states it replaces 2-3 manual lookups, providing clear context. However, it does not explicitly mention when not to use it or cite alternative tools, missing a slight opportunity for exclusion guidance.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already indicate safe, non-destructive behavior. The description adds value by detailing the process: probes each entity with ai_visibility_check, ranks by score, and returns a 'ranked list with score, confidence, signal density per entity.' It does not contradict annotations and provides useful behavioral context beyond them.

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

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

The description is two sentences long with no extraneous information. The first sentence states the core function and method; the second provides a use case and output summary. Every sentence adds value, and the structure is front-loaded for quick comprehension.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: 'ranked list with score, confidence, signal density per entity.' It also describes the probe method and the narrative treatment of the first entity. Combined with the annotations, the agent has all necessary information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. However, the description adds important context: 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the intended use of the entities array beyond the schema's description. The additional narrative enhances understanding without redundancy.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies that it probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. This differentiates it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison), 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 usage context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It clearly implies when to use this tool over alternatives. However, it does not explicitly state when not to use it or mention alternative tools like ai_visibility_check for single-entity checks, which would have earned a 5.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description's stated behavior. The description adds key details: it fans out across external services, returns summary fields, per-advisory detail, links, and alternative versions, plus warns of potential timeouts and graceful degradation.

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

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

The description is a single dense paragraph but front-loads the core purpose. Every sentence adds unique value, though it could be slightly more structured (e.g., bullet points) to improve scannability. Still, it is effective and not wasteful.

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

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

With no output schema, the description fully explains the return value structure: summary block fields, per-advisory details, links, alternative versions. It also covers partial failure and source behavior. For a tool with two simple parameters, this is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining that scoped packages are accepted, version defaults to latest, and that bundlephobia measurement may delay results. This enriches the schema without redundancy.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by specifying it aggregates multiple data sources (deps.dev, bundlephobia) in one call and is limited to the npm ecosystem.

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 to use when an agent asks safety, popularity, or size questions about an npm package. Notes that other ecosystems fall under deps.dev:version and warns about bundlephobia's first-measurement delay and partial failure behavior.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses truncation at 200K chars with flagging, embedding model (BGE-base-en), window size (500-char overlapping), and return contents (passages with offsets and similarity scores). No contradictions.

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

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

Front-loaded with purpose, then conditional usage, then technical details. Every sentence adds value. No redundant or filler content.

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

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

Given no output schema, description explains return type (top-N passages with offsets and scores). Covers constraints (200K chars, truncation), embedding method, and pairing with sibling. Complete for a semantic search 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. Description adds marginal value: clarifies max chars for 'text' and gives query examples. Does not add critical missing info beyond schema.

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

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

The description clearly states the verb ('search'), the resource ('a fetched record'), and the operation's scope ('semantic search INSIDE'). It distinguishes from sibling tool ask_pipeworx_grounded by explaining the complementary workflow.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt.' Provides a concrete alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description extensively covers behavioral traits beyond annotations: account requirements, type-specific parameters, delivery channels (feed always on, optional email/sms with limits and verification requirements), webhook details (signing secret, auto-disable after 10 failures). No contradictions with annotations.

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

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

The description is well-structured with clear sections: purpose, requirements, type options, delivery channels. Every sentence adds value, and the core action is front-loaded. Despite length, it is efficiently written.

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 (3 parameters, nested objects, multiple types, delivery options), the description is comprehensive. It explains prerequisites, return value, type-specific filters, delivery details, and limitations (SMS cap, webhook auto-disable). No output schema but sufficient.

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

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

The description adds significant meaning beyond the input schema by providing concrete examples for each type's params object and elaborating on delivery sub-parameters (e.g., SMS phone verification requirement, webhook HMAC signing). Schema coverage is 100%, but the description enriches it.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by specifically creating a new subscription.

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

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

The description specifies when to use (requires Pipeworx OAuth account) and provides detailed examples for each subscription type. However, it does not explicitly mention when not to use or contrast with alternative tools like recent_alerts or one-time queries.

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 safe, idempotent, non-destructive. The description adds that it returns category-bucketed examples with exact tool calls, drawn from live catalog, and that it covers multiple domains. No contradiction.

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

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

Description is front-loaded with purpose and examples, but somewhat lengthy. Every sentence adds value, though some redundancy exists. Structured with clear use cases.

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

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

Given no output schema and complexity of onboarding, the description thoroughly explains what is returned (categories, tool+argument shapes) and when to use it (first step). Also mentions meta-tools to learn.

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

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

Schema coverage is 100%, baseline 3. Description adds value by listing allowed values (finance, pharma, etc.) and clarifying that omitting topic gives full spread. This goes beyond the schema's minimal description.

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

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

The description clearly states it is the 'onboarding entry point' that returns example questions with tool+argument shapes. It distinguishes itself from sibling tools by being the first tool to use when unfamiliar with 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?

Explicitly says 'Use this FIRST' when you do not know what Pipeworx can do. Also describes optional topic parameter to focus. However, does not explicitly state when not to use it or compare to alternatives like ask_pipeworx beyond mentioning them.

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

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

The description adds valuable context beyond annotations: the row is deactivated (not deleted) aligning with destructiveHint=false, and ownership enforcement is disclosed. Annotations already indicate idempotent and non-destructive, and the description complements them 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?

Two sentences, front-loaded with the core action, then adding constraints and behavior. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraint, and behavioral effect thoroughly. Agent has everything needed to use correctly.

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

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

The single parameter 'id' has full schema coverage (100%). The description doesn't add meaning beyond the schema, but baseline is 3. The schema already states it's a UUID from subscribe.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the operation on a subscription.

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 ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior ('not deleted'), guiding when to use the tool and what to expect.

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

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

Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations, such as the two processing paths (structured SEC vs. grounded pipeline) and the return format (verdict, value, reasoning). It does not disclose potential limitations like latency or rate limits, but given annotation coverage, the added detail is sufficient.

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

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

The description is moderately long but efficiently packed with information. It front-loads trigger phrases and primary use, then details the two paths and return format. Every sentence earns its place, though slight trimming could improve conciseness without losing value.

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

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

Given the tool's complexity (fact-checking with dual paths), the description thoroughly covers what the tool does, when to use it, what it returns (verdict, value, citation), and how it handles different claim types. No output schema exists, but the description compensates by explaining return values. Annotations are present, making this complete 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 100% for both parameters. The description adds meaningful context beyond the schema, particularly for tolerance_pct: explaining that it overrides implied tolerance and suggesting values for hallucination detection. This significantly aids correct parameter usage.

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

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

The description clearly states the tool's purpose: verify factual claims against authoritative sources. It provides trigger phrases like 'fact check' and 'verify the claim that...', and explains the two distinct verification paths (SEC EDGAR for company financials, grounded pipeline for other claims). This makes it highly distinguishable from sibling tools like ask_pipeworx_grounded or deep_research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims and other factual claims, providing clear context. However, it does not explicitly exclude alternative tools or mention when not to use this tool, which would enhance guidance.

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