New Jersey MVC

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by disclosing default model (free Workers AI), BYO key for Anthropic with cost implications, and return format. No contradictions. This goes beyond annotations, warranting a 4.

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

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

The description is three sentences, front-loaded with purpose, and contains no fluff. 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?

For a tool with 4 parameters, no output schema, and rich annotations, the description covers purpose, default behavior, alternative model setup, and return structure. Minor omission: 'confidence' and 'signals' are not clarified, but overall it is sufficiently 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%, so baseline is 3. The description adds meaning by explaining default model behavior, conditionality of _apiKey, and the disambiguation purpose of the context parameter. This extra context justifies a 4.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility. It specifies the verb ('probe'), resource ('LLMs'), and output (0-100 score). Though it doesn't explicitly differentiate from siblings, the unique combination of features (multi-model probing, visibility scoring) distinguishes it effectively.

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 lists concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not explicitly state when not to use or compare to sibling tools. It provides strong contextual guidance, earning a 4.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: it routes to 5,581 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the annotations without contradicting them. It doesn't mention potential latency or error behaviors, but for a read-only tool this 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 longer than average but every sentence earns its place: it front-loads the priority guidance, gives domain examples, names alternatives, and explains the routing mechanism. While it could be tightened, the structure is logical and scannable, with clear paragraphs and strong emphasis on key tokens like 'START HERE'. It feels intentionally comprehensive rather than verbose.

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

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

For a tool of this complexity (a gateway to thousands of sources), the description is remarkably complete. It explains the tool's role, its scope, alternatives for different use cases, output format (structured answer with citations), and provides concrete examples. Since there is no output schema, the description covers return expectations explicitly. It also integrates well with the sibling tool context, leaving no obvious gaps.

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

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

The input schema covers 100% of parameters, including six aliases for the single required 'question' parameter, so the description isn't needed for basic semantics. However, the description does provide examples of well-formed questions and clarifies that it accepts natural language, which adds some value beyond the schema. This matches the baseline of 3 for 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?

The description is exceptionally specific: it identifies the tool as a router for authoritative structured data across 5,581 sources, lists concrete domains (SEC, FDA, FRED, etc.), and provides clear examples. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its role unmistakable.

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

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

The description provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions'), when-not-to-use ('for a hallucination-resistant single answer with verbatim evidence + confidence use ask_pipeworx_grounded; for a broad/multi-part question ... use deep_research'), and even covers breaking-news edge cases. It also outlines the tool's routing behavior, making it easy for an agent to decide between this 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?

While annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds critical context about experimental candidate routing that may be active live, its current inactive state, and the comparison process. This goes beyond annotations to disclose mutable behavior and experimental nature.

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

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

The description is informative yet not bloated, with a logical flow: beta status, current state, usage guidance, and reassurance. Each sentence earns its place, though it could be slightly tightened 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 complex universal router with 5,581 tools, the description adequately covers its role, current routing status, comparison to stable, and usage. It does not need to detail return values as it states identical response shape to ask_pipeworx, and all essential context is provided.

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

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

Schema coverage is 100% with all parameters (including aliases) documented. The description adds no new parameter-specific semantics beyond stating 'same arguments as ask_pipeworx', which is sufficient but not additional value; baseline 3 is appropriate.

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

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

The description clearly states it is a beta universal router for 5,581 tools with identical arguments and response shape as ask_pipeworx. It distinguishes itself from the stable ask_pipeworx and grounded variant by highlighting experimental routing improvements, making its 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?

It explicitly instructs to use it like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to inform merges. It also clarifies it's a full working router with no fallback, setting clear expectations and differentiation from 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses refusal behavior with exact refusal_reason enum values, success return shape including evidence verbatim quote, and the cost of one extra LLM call. No contradiction with annotations.

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

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

The five sentences each carry meaningful content: purpose, routing mechanism, return contract, usage guidance, and cost/alternative. The '5,581 across 1463 sources' detail is slightly extraneous but not harmful; overall the description is dense and front-loaded.

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

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

Since there is no output schema, the description fully specifies both success and refusal return types with refusal reasons, which is essential for an agent to handle failures. It also covers usage context, cost tradeoff, and how it relates to ask_pipeworx, making it complete for a grounded QA tool.

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

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

Schema coverage is 100% with all six parameters described as aliases for the natural-language question. The description adds that the question gets routed to other tools but provides no parameter syntax or formatting details beyond what the schema already documents; 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?

Description explicitly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: routes across 5,581 tools/sources, fetches data, then extracts only from tool result. It differentiates from sibling ask_pipeworx by noting same routing but grounded, evidence-based answering.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains. It also names the alternative: 'prefer ask_pipeworx for casual lookups' and flags the extra LLM cost tradeoff.

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 extensive behavioral context beyond annotations: resolver contract, fan-out logic, response shapes, safety short-circuits, tradeability notes, resolution-rule risk. All consistent with annotations (readOnly, idempotent, non-destructive). No contradictions.

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

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

Description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). Every sentence adds value. Minor deduction for verbosity; still mostly 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 lack of output schema, description comprehensively explains response shapes, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and fallback behavior. Covers all critical aspects an agent needs.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds significant extra meaning: depth enum default, market parameter types with examples, include_raw rationale. This exceeds schema-only knowledge.

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

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

Description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies exact input types (slug, URL, question text), what it returns (evidence packet + market-vs-model comparison), and lists classifier categories. This is highly specific and distinguishes from siblings.

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

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

Explicit use cases given: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Also covers blocking conditions like low-confidence match and closed markets. Missing explicit differentiation from sibling tools like polymarket_edges, but still strong guidance.

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

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

The annotations already indicate safety (readOnly, idempotent, non-destructive) and open-world, but the description adds rich behavioral detail: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and 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?

The description is somewhat lengthy but front-loaded with concrete examples. Every sentence adds useful information, but it could be slightly more streamlined. The structure is logical: examples, behavior, data sources, sorting, output format.

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 low parameter count, no output schema, and simple input types, the description is complete. It explains what data is returned (paired data + URIs), for both entity types, and addresses edge cases (off-calendar fiscal years). It leaves no significant gaps for an agent to infer.

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

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

Schema coverage is 100% and both parameters are described. The description adds meaning beyond the schema by explaining the input format for values (tickers/CIKs for company, drug names for drug) and the sorting behavior that relates to the query intent. This adds value 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: side-by-side comparison of 2–5 companies or drugs. It provides explicit example queries and distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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

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

The description explicitly instructs to prefer this tool over sequential single-entity lookups and specifies the range of entities (2–5). It implies context (comparing entities) but does not explicitly list when not to use it or alternative tools, though the preference statement is strong.

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

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

The description goes far beyond the read-only and idempotent annotations by disclosing that it returns gaps[] for unanswered facets, contradictions[] for disagreement, timing expectations (15-90s), citation_uri availability only when fetchable, and semantic excerpting. It also notes the account requirement and that thorough requires a paid plan. 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?

Despite its length, the description is front-loaded with the critical account requirement and organized logically: purpose, scope, alternatives, depth explanation, behavioral details. Every sentence carries essential information for selecting and invoking the tool—no filler.

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

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

Given the tool's complexity (3 depth levels, parallel routing, citations, gaps, contradictions, timing, excerpts) and the absence of an output schema, the description covers all necessary dimensions for an agent to correctly decide and use the tool. It fully compensates for missing output schema details.

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

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

The input schema already documents both parameters fully (100% coverage), but the description adds significant depth-semantics: it explains what each depth value does (quick=3 facets single-hop, standard=3 with gap-recovery, thorough=6 with iterative hop) and clarifies the 'question' parameter accepts broad/multi-part queries. This adds 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?

The description clearly states it performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from ask_pipeworx ('NOT open-web search') and from sibling tools like ask_pipeworx_grounded, making its purpose unmistakable.

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

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

It provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples, and explicitly says to use ask_pipeworx for single lookups or breaking news. It also explains depth levels and their trade-offs, including the account requirement and which depth is paid.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavior details: returns top-N tools with schemas and examples, ready to call directly without second lookup. 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 informative with a clear structure: purpose, usage, return format, and guidance. While slightly wordy, every sentence adds value. Efficient but not ultra-concise.

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

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

With no output schema, the description explains what is returned (names, descriptions, schemas, examples) and that results are ready to call. Covers complexity well for a tool-discovery 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 parameter descriptions. The description reiterates aliases and provides examples but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description starts with 'Find tools by describing the data or task,' clearly stating the verb (find/discover) and resource (tools). It distinguishes from siblings like search_within and bet_research by focusing on tool discovery.

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available.' It implies not to use for getting a single answer, guiding the agent to use other tools instead.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds context: fans out across multiple sources, patents sunset May 2025 (soft-fails), news fallback (GDELT→GNews), and no name support. No contradiction with annotations.

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

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

Single dense paragraph with all key information, front-loaded with purpose and usage. Could benefit from structured formatting (e.g., bullet points) for readability, but remains 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 tool complexity (multiple data sources, no output schema), description covers all essential aspects: what it returns, how it works, limitations (no names, patent soft-fail), and fallback mechanisms. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, and description adds meaning: type parameter notes 'Only "company" supported today; person/place coming soon.' Value parameter clarifies ticker or zero-padded CIK and reiterates names not supported.

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

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

Description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific outputs (CIK, filings, fundamentals, patents, news, LEI) and provides example queries, distinguishing it from siblings like resolve_entity.

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

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

Explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes when not to use: for names, use resolve_entity first. Clear guidance on alternatives.

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

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

Annotations declare destructiveHint=true, and the description confirms by saying 'Delete'. It adds context about 'sensitive data' and 'stale context' beyond the annotation, but does not provide extensive additional behavioral details.

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, no wasted words. First sentence states the action, second provides usage guidance. Perfectly front-loaded and concise.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and parameter semantics adequately. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description adds the phrase 'by key' but does not significantly enhance meaning beyond the schema.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It explicitly pairs with 'remember' and 'recall', distinguishing it from sibling tools.

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

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

Provides explicit scenarios: when context is stale, task is done, or clearing sensitive data. Mentions pairing with 'remember' and 'recall', offering guidance on alternatives.

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

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

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds context beyond annotations by detailing the process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown). It does not mention potential failure modes, but adds useful behavioral detail.

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 consists of three sentences that front-load the main purpose and audience, followed by a process summary and use cases. Every sentence is purposeful with no redundant information, achieving optimal 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?

The description covers the output format (single text blob ready for site-root/llms.txt) and the general workflow. It lacks error handling details (e.g., invalid URLs) but given the simplicity of the tool and no output schema, it provides sufficient completeness for typical use.

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

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

The input schema has 100% coverage, describing both 'url' and 'max_links'. The description does not add additional meaning beyond the schema, such as formatting constraints or default behavior, meeting the baseline for high schema coverage without extra value.

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

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

The description clearly specifies the verb 'Generate' and the resource 'a production-ready llms.txt file for any URL', with a clear purpose of enabling AI crawlers to index the site. It distinguishes itself from sibling tools like 'ai_visibility_check' by focusing specifically on file generation rather than broader visibility 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?

The description explicitly lists three use cases: getting a client's site indexed, drafting for a personal project, and auditing a competitor. While it does not include explicit 'when not to use' statements, the sibling context implies alternatives for different tasks, providing sufficient guidance for appropriate usage.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. Description adds that it returns specific fields and can include inactive subscriptions, but does not disclose additional behavioral traits beyond annotations.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

For a simple list tool with one optional parameter and rich annotations, the description covers purpose, return fields, and usage context. Lacks mention of pagination or ordering, but acceptable given low complexity.

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

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

Schema description coverage is 100%, with the single optional parameter 'include_inactive' well-described in the schema. The description does not add extra meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

Clearly states the verb 'List' and the resource 'subscriptions'. Specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). Differentiates from sibling tools like subscribe and unsubscribe by focusing on listing.

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

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

Provides explicit guidance on when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. Does not mention alternatives, but context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by specifying the exact count of facilities (1,167) and listing returned fields. No contradictions. Does not mention rate limits, but annotations cover the essential 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?

Single, well-structured paragraph. Front-loaded with purpose, then data returned, examples, coverage, and exclusions. Every sentence serves a distinct informative purpose; 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?

With 7 optional parameters and no output schema, the description provides sufficient context via examples and scope. It clarifies the exact coverage (1,167 facilities) and what is excluded. Could mention pagination or default limit, but the input schema covers the limit parameter.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter-level detail beyond the schema, though it provides example queries that illustrate parameter use. No additional depth is needed given the schema's thoroughness.

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

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

Description clearly states the tool finds licensed NJ vehicle inspection/emission-repair facilities, lists returned fields, and gives example queries. It explicitly distinguishes from sibling tools by stating what it does not cover (driver license, ID card, registration renewals).

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

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

Provides clear context on when to use (finding inspection facilities) and what to exclude (other MVC services). Offers example queries. Does not explicitly compare to the sibling 'nj_mvc_vehicle_inspections', but the exclusion statement serves as functional 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?

Description adds significant context beyond annotations: data source size, return structure (pass/fail rates, emissions vs safety), and overall fail rate. No contradiction with annotations.

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

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

Single paragraph, front-loaded with purpose and examples. Dense but not verbose. Could be slightly more concise, but effective.

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

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

Given 9 parameters, no output schema, but high schema coverage and annotations, the description sufficiently covers data source, output types, and example usage. Complete enough for agent to understand tool's capabilities.

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%; description provides overarching context but does not add meaning to individual parameters beyond what is in 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?

Verb 'measure' and resource 'inspection results' are clear. Example queries further clarify. Distinguishes from sibling tool 'nj_mvc_inspection_facilities'.

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 example questions demonstrating use cases, but does not explicitly state when not to use or mention alternatives. Context is clear enough for appropriate invocation.

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

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

Annotations only state generic hints (readOnly=false, etc.), but the description adds substantial behavioral context: the claim_token workflow for later retrieval, rate limiting to 5 per identifier per day, free usage not counting against quotas, and the team's digest-reading cadence. This goes well beyond the annotations and fully discloses side effects and constraints.

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

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

The description is long but dense with essential information. Every sentence adds a distinct fact: purpose, use cases, exclusions, claim_token flow, rate limit, and roadmap impact. It is front-loaded with the core purpose and structured logically, with no filler 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?

For a tool with 4 params (one nested) and no output schema, the description covers all key consumer concerns: what the tool does, when to use it, scope boundaries, how to track a submission via claim_token, rate limits, and reliability expectations. It is fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by explaining the claim_token parameter in context (how to file and later retrieve via pipeworx_feedback({claim_token:...})) and by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, which enriches the message 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly stating the verb, resource, and purpose. It distinguishes itself from sibling tools by explicitly enumerating feedback types (bug, feature/data_gap, praise) and contrasting with tools like ask_pipeworx that serve different intents.

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

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

Provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and a clear when-not-to-use exclusion for tools from other MCP servers, with guidance to file with that server instead. Also clarifies how to identify Pipeworx tools, giving strong decision support.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable context: caching (5min-1h), data source (CF analytics-engine, no PII), and self-aggregating signal. No contradictions.

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

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

The description is a single paragraph with clear structure: purpose, returns, use cases (bulleted), and data source/caching info. It is front-loaded with the main output. Slightly verbose but efficient overall.

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

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

The description explains what is returned (top tools, packs, total call volume) but does not detail the output structure (e.g., is it a list with counts? nested?). Given no output schema, this is a minor gap for an agent to fully understand the payload.

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

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

Schema coverage is 100%, and the description adds nuance beyond the enum: it repeats valid values, identifies the default (24h), and explains the behavioral difference between short and long windows (hot vs. steady-state).

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's purpose: returning trending tools, packs, and call volume on Pipeworx. It distinguishes itself from sibling tools like discover_tools and suggest_questions by focusing on current aggregate usage data.

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

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

The description lists three specific use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains the trade-off between short and long windows. It lacks explicit when-not-to-use or direct sibling comparisons but provides sufficient context.

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

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

Annotations indicate readOnly, openWorld, idempotent, and not destructive. Description adds extensive behavioral context: algorithms (monotonicity violations, partition checks), semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check with CLOB depth, including when realizable_edge_pp <= 0 means do not trade. No contradictions.

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

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

Description is detailed and well-structured into sections, front-loading purpose and then detailing modes. While lengthy, every part adds value and is not redundant. Slightly verbose but appropriate for complexity.

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

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

Given no output schema, the description is exceptionally thorough. Covers all modes, algorithms, edge cases (semantic anchor, partition filter), fill check, and references sibling tool. Nothing missing for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, but description adds significant meaning beyond schema: explains what event slug and topic are with examples, notes full URLs accepted, and provides behavioral context for each parameter. This goes well beyond the baseline.

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

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

The description explicitly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three modes (no-args, event, topic) and explains each, differentiating from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode for specific markets and explains cross-event mode catches patterns single-event misses. Also advises when not to trade via fill check and references polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, idempotentHint, etc., and the description adds significant behavioral details: 'Cached 1h at the KV level keyed on all knobs,' structure of response (by_segment, diagnostics), filter skips to explain empty segments, and limitations like Fed bets note. 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 long but well-structured with sections for segments, response fields, and knobs. However, it is verbose with excessive detail (specific α values, placeholder filter rules) that could be streamlined. Still front-loaded with purpose.

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

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

Given the complexity (9 params, no output schema), the description is highly complete. It explains response segments, diagnostic counters, caching behavior, and handles edge cases like Fed bets. No output schema, so description compensates fully.

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, e.g., explaining 'Tradeable-edge knobs' like min_liquidity and max_spread_pp, and providing advice on slippage_pp defaults. This elevates the score to 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb, resource, and unique aspect (disagreement with Pipeworx data), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides clear context but does not mention when not to use this tool or explicitly name alternatives, though the sibling tools imply complementary roles.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds critical behavioral details: history depth bounded by 60-day TTL, decay computed from daily closes (not intraday), and snapshots written on cache-miss causing possible gaps. No contradiction with annotations.

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

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

The description is well-structured, starting with purpose, then response details, then limits. It is slightly verbose but each sentence adds information. Front-loading of purpose is effective.

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

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

Given the tool has 2 optional parameters and no output schema, the description provides complete context: details the response arrays (tracked, expired, snapshot_dates) with fields, explains limits, and covers edge cases like gaps. Annotations handle safety and idempotency.

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

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

Schema coverage is 100%, and the description adds value by explaining the meaning of each parameter: days as lookback (default 14, clamp 2-30) and window as snapshot family (default '1wk'). It also describes the response format, compensating for the lack of an output 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: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical trends rather than current edges.

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

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

The description gives clear context for using the tool, emphasizing analysis of historical edge persistence vs. current state. It implies when to use this tool over alternatives (e.g., fresh vs. aged edges) and mentions limits like 60-day TTL and daily closing data. However, it does not explicitly state when NOT to use it.

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

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

Annotations already confirm this is a read-only, idempotent, non-destructive check. The description adds substantial behavioral context beyond annotations: it 'walks the ladder' and returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict). For basket mode, it explains return values like capture_ratio, profit_usd, thin_legs, 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-structured with clear sections for single-market and basket modes, using capitalization for key terms. Every sentence earns its place—no filler. It is appropriately sized given the complexity of two distinct modes and multiple return values.

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, lack of output schema, and need to explain two distinct modes, the description is complete. It explains return values for both modes, warns about risks (thin books, unhedged positions), and specifies prerequisites. No gaps identified.

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

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

Schema description coverage is 100% for all 4 parameters. The description adds significant meaning beyond the schema by explaining default values (size_usd default 1000, side default by mode), clarifying that size_usd is interpreted differently in single-market vs basket mode, and providing usage examples in the description text.

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 a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket). It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the risks of partial basket fills converting arb into unhedged directional positions and notes required parameters (market or event, side, size_usd).

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 (read-only, idempotent), the description details critical behaviors: compatibility warnings for shape mismatches, temporal alignment checks, skipped counters for metric-type mismatches, and the note that real spreads are rarer than topic shortcuts imply.

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

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

The description is comprehensive but verbose; it front-loads purpose but then includes extensive technical detail. While all information is useful, conciseness could be improved by condensing safety field explanations.

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

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

Given no output schema, the description adequately explains the response structure (leg prices, spread array, safety fields). It covers edge cases like temporal misalignment and shape mismatches, making the tool usable without an output schema.

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

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

Schema coverage is 100% with parameter descriptions. The description adds operational context: enum values for topic, the override logic for tickers, and how topic auto-maps to both venues. This adds meaning beyond the schema.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, and distinguishes it from sibling tools like polymarket_arbitrage (single venue focus). It specifies two usage modes and the return structure.

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

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

The description explains when to use each mode (topic vs explicit tickers) and warns that pre-mapped topics often return warnings. However, it doesn't explicitly compare to alternatives like polymarket_arbitrage or when not to use this tool.

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

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

Adds scoping detail ('scoped to your identifier') beyond annotations. Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description complements 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?

Two well-structured sentences, front-loaded with core function, no unnecessary words.

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

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

Covers usage, scoping, and pairing with remember/forget. No output schema, but return values are implied. Adequate for a simple read 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?

Description restates schema behavior (omit key to list all). Schema coverage is 100%, so baseline 3 applies; description adds minimal extra 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?

Description clearly states 'retrieve a value' or 'list all saved keys', specifying verb and resource. Distinguishes from sibling tools 'remember' and 'forget'.

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

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

Describes when to use (look up context stored earlier) with examples. Lacks explicit exclusions or alternative tools, but context implies it's for reading only.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds crucial behavioral detail: mark_read flag affects next call, and returns specific fields. No contradictions.

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

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

Three sentences, each adding distinct value. Front-loaded with core purpose, then details, then alternative access. 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 read tool with no output schema, description explains return fields (source, citation_uri, payload) and mentions polling behavior and alternative HTTP endpoint. Covers all necessary context.

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

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

Schema coverage is 100%, but description reinforces parameter meanings (e.g., filter by type, since, mark_read behavior, limit range). Adds value beyond schema by tying parameters to behavior.

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

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

Clearly states it 'Pull fired events from your subscription feed' and returns recent alerts with specific fields. Distinguishes itself from sibling tools like subscribe and list_subscriptions by focusing on retrieving fired events.

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

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

Provides context on when to use ('Polls work fine') and an alternative method ('same feed at GET registry.pipeworx.io/alerts.json'). Could be slightly improved by explicitly contrasting with sibling read tools, but overall guidance is clear.

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

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

The description adds significant behavioral context beyond annotations, detailing that it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains source preferences, soft-failures, and return format with grouped changes and citation URIs.

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

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

The description is dense but every sentence adds value. It front-loads with common query patterns, then efficiently explains sources and nuances with no redundant or irrelevant text.

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

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

Given the tool's complexity (multiple sources, fallback logic, date parsing) and absence of an output schema, the description covers behavior comprehensively: source roles, error handling, return structure, and even a cross-reference to a sibling tool.

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

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

Although schema coverage is 100%, the description enriches parameter understanding by giving examples of valid inputs for 'since' (ISO date vs relative) and 'value' (ticker or CIK), and recommends a default window of '30d' or '1m'.

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

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

The description clearly states the tool's purpose as a change feed for a company over a recent window, using explicit trigger phrases like 'What's new with X' and 'latest on Y'. It also distinguishes itself from the sibling 'entity_profile' tool.

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

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

The description provides explicit when-to-use guidance by listing common query patterns and explicitly says 'Use entity_profile instead when you want the static profile', offering a clear alternative.

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 idempotent and non-destructive behavior. Description adds scoping details (by identifier, 24-hour anonymous persistence) and clarifies no destructive side effects. Does not contradict annotations. Could mention overwrite behavior but implied by idempotent.

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

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

Three sentences, no fluff. Front-loaded with core purpose, followed by usage guidance, then persistence details. Every sentence adds distinct 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 storage tool with no output schema, the description covers purpose, when to use, parameter semantics, persistence behavior, and relationship to sibling tools. No gaps exist given the complexity.

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

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

Schema has 100% coverage with examples for both parameters. Description adds meaning beyond schema by explaining the key-value structure, scoping, and that value is any text. Provides usage context 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?

Describes a specific verb-resource action ('Save data') with clear intent ('reuse later'). Distinguishes from siblings recall and forget, and explains the domain (cross-session persistence).

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

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

Explicitly states when to use ('when you discover something worth carrying forward'), what not to do (implicitly avoid redundant lookups), and provides pairing guidance with recall and forget. Also explains persistence differences for authenticated vs anonymous sessions.

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

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

Goes well beyond annotations: describes internal cascading lookups, graceful degradation of LEI/FIGI enrichment, explicit `unresolved` handling, source labeling of identifiers, and ISIN-to-LEI mapping for non-US issuers. This provides substantial behavioral context beyond the readOnly/idempotent hints.

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

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

The description is long but well-structured, starting with user utterances and moving to supported types and details. Every sentence adds value, though some parts are dense and could be tightened. It earns its length given tool complexity.

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

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

For a complex tool with no output schema, the description is remarkably complete. It specifies inputs, outputs for each type, source attribution, unresolved behavior, graceful degradation, and a concrete example. This gives an agent sufficient context to invoke the tool correctly.

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

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

Schema coverage is 100%, with both parameters already described with examples (ticker, CIK, drug names). Description adds some context like ISIN-to-LEI mapping and return contents, but these are more about behavior than parameter semantics. Baseline of 3 is appropriate; description does not significantly enrich parameter understanding beyond schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples like ticker, CIK, LEI, RxCUI. It distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID' and by enumerating supported types and outputs.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use context. It does not explicitly mention when not to use or name alternative tools, but the guidance is strong and implied.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds internal behavior (calls ai_visibility_check per entity, ranks results) and return fields (score, confidence, signal density). This context is valuable 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 well-structured sentences: first states action and ranking, second adds use case and return format. No fluff, front-loaded with key information.

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

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

Without an output schema, the description compensates by listing return fields. It covers purpose, input semantics, behavior, and results. Minor detail: ranking algorithm is not described, but sufficient for typical usage.

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

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

Schema covers all 4 parameters. The description adds semantic value for 'entities' (first entry treated as subject, rest as competitors) and for 'context' (shared context per probe). This goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) by focusing on side-by-side comparison.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and implies it should be used when comparing multiple entities. It does not explicitly exclude single-entity scenarios, but the context makes the intended usage clear.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed lists timeouts. 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 a single paragraph but packs extensive detail efficiently. Front-loaded with purpose and usage. Could be slightly clearer with bullet points but remains concise given the information density.

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

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

Despite no output schema, description enumerates return components: summary block, per-advisory detail, links, and recent alternative versions. Also covers limitations (npm only, bundlephobia delay) and error handling, making it 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 coverage is 100% with descriptions. Description adds value by noting that scoped packages are accepted for 'package' and that 'version' defaults to latest published when omitted. Enhances schema 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?

Description clearly states the tool as a composite check for npm packages aggregating license, advisories, version history from deps.dev and bundle size from bundlephobia. It directly addresses agent queries about safety, popularity, and size, distinguishing itself from sibling tools that are unrelated.

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

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

Explicitly states when to use: 'whenever an agent asks is X safe / popular / small' and 'what does adding lodash cost me'. Also specifies exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K character limit with truncation flag, and offset for verification. No contradiction with annotations.

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

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

The description is concise (about 5 sentences), front-loaded with the core action, and efficiently uses each sentence to add value. No unnecessary details or repetition.

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

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

Given no output schema, the description adequately explains the return value (passages with character offsets and similarity scores) and the tool's internal mechanics (embedding model, windowing, truncation). It is sufficient for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already defines parameters. The description enhances semantics by adding context: 'text' is described as 'the document text' with an explicit max size, and 'query' is illustrated with example phrases, aiding agent understanding.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the action ('search'), the target ('INSIDE a fetched record'), and distinguishing it from siblings like ask_pipeworx_grounded. The verb 'search' and resource 'record' are well-defined.

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: when the record is too large for the prompt, saving context and returning only relevant passages. It also mentions a sibling tool (ask_pipeworx_grounded) and explains how they pair, providing clear alternatives.

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

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

Annotations indicate a write operation (readOnlyHint=false) and idempotency. Description adds authentication requirements, delivery channel specifics (SMS cap, webhook signing), and auto-disable after failures, enhancing 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?

Well-structured: purpose first, then requirements, types with examples, delivery details. Every sentence adds value, and the description is appropriately sized for the complexity.

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

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

Covers purpose, return value, authentication, type-specific parameters, delivery channels, and constraints. With no output schema, this provides sufficient context for the agent to use correctly.

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

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

Schema coverage is 100%, and description adds concrete examples for each type (e.g., sec_8k with items) and detailed delivery channel semantics (email pattern, SMS verification, webhook HMAC).

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the subscription ID. It distinguishes from sibling tools like list_subscriptions (list) and unsubscribe (remove).

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 on required OAuth account, supported types with examples, and delivery options with constraints. Lacks explicit mention of when not to use or direct comparison to siblings, but context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral detail: it returns category-bucketed example questions with tool+argument shapes, and that the result is drawn from a live catalog. This goes beyond what annotations provide.

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

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

The description is well-structured with example queries first, then purpose, then return details, then usage modes. It is slightly verbose but earns its length by covering multiple scenarios concisely.

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 adequately describes the return type (categorized example questions with tool+argument shapes) and covers both invocation modes. It is complete for an onboarding tool, though it could mention pagination or limits if applicable.

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

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

Schema coverage is 100% and the schema already describes the parameter well (optional topic with focus areas). The description adds example values but does not introduce new semantic meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose as an onboarding entry point for the 'what can I ask' use case, listing natural language queries that trigger it. It distinguishes from sibling tools like ask_pipeworx and discover_tools by positioning itself as the first step for learning what Pipeworx can do.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without the topic parameter. It does not explicitly state when not to use it, but the context of being for initial onboarding strongly implies alternatives are for later use.

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

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

Discloses that rows are deactivated (not deleted) and historical events remain available, adding context beyond annotations (readOnlyHint=false, destructiveHint=false). 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?

Two sentences, no extraneous information. The most important details (what, ownership, effect) are front-loaded.

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

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

For a simple one-param tool with no output schema, the description covers purpose, constraints, and side effects completely.

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

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

The single parameter 'id' is fully described in the schema (100% coverage). The description adds 'returned by subscribe' which is minimal extra value, meeting baseline 3.

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

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

The description specifies the action (Cancel) and resource (subscription by id), clearly distinguishing it from sibling tools like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions') and explains the deactivation behavior, guiding when to use and referencing recent_alerts for history.

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 provides extensive behavioral context beyond the read-only/idempotent annotations. It explains the meaning of could_not_verify (check did not happen, not evidence) and unsupported (no source covers it), and details the two-path execution (structured vs. grounded). This is exactly the kind of context that prevents misuse.

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

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

The description is front-loaded with natural-language triggers and gets to the point with 'natural-language claim verification.' While longer than ideal, every sentence adds necessary detail (verdict meanings, error handling, pipeline routing). No redundant 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?

With no output schema, the description fully explains return values (verdict, actual value, citation, reasoning) and error cases (could_not_verify, unsupported). It also covers routing, tolerance behavior, and the efficiency advantage. Given the tool's complexity, the description is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add some nuance about tolerance_pct (e.g., 'set 1–2 for hallucination detection'), but this mostly restates what the schema already provides. The claim parameter is clearly illustrated with examples, but the schema already covers it well.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes specific trigger phrases ("Is it true that…", "fact check") and distinguishes itself from siblings by focusing on confirming/refuting factual claims. The verb is specific and the resource (claims) is clear.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic (SEC EDGAR for company-financial claims, grounded pipeline for others) and notes it replaces 4–6 sequential calls, implying efficiency. However, it does not explicitly state when not to use it or compare to sibling tools like ask_pipeworx_grounded.

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