Boardgames

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

Discloses that the tool probes LLMs, default free model, optional paid Anthropic with BYO key, and return structure. Annotations already indicate readOnly, idempotent, openWorld, and non-destructive, so description adds value on payment and model selection. 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?

Four sentences, each serving a distinct purpose: core function, model options, return structure, use cases. Information is front-loaded and no redundant phrasing.

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 4 parameters, no output schema, but rich annotations, the description covers purpose, usage scenarios, and return structure (per-model results + combined view). It does not detail the 'signals' or 'raw_response' fields but provides enough for an agent to decide to invoke.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the default model, the role of `_apiKey` for Anthropic, and how `context` aids disambiguation. This enhances usability.

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

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

Description clearly states the tool's function: probing LLMs for visibility and scoring (0-100). It specifies the resource (business/brand/product/topic) and the action (probe and score). The description distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on AI visibility scoring rather than general scanning.

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

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

Explicitly provides contexts for use (AI-marketing audits, pre-launch brand checks, competitive monitoring). However, it does not mention when not to use this tool or compare with alternatives like 'deep_research' or 'entity_profile'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: it routes to a large tool corpus, returns citation URIs, works on 'every tier', and is a 'fast call'. These details go beyond annotations without contradicting them.

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

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

The description is long but front-loaded with a clear directive ('PREFER OVER WEB SEARCH'). Every section contributes: what it does, when to use, examples, when to step up. It is not redundant, though slightly verbose; the length is justified for a default entry point that must handle many use cases.

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

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

For a tool with no output schema, the description still conveys the response format ('structured answer with stable pipeworx:// citation URIs'). It covers use cases, alternatives, and limitations (e.g., breaking news handled internally). The description is complete enough for an agent to decide when to invoke this tool and what input to provide.

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 with a 'question' parameter and documented aliases. The description provides examples of valid questions but does not add new parameter semantics beyond the schema. Baseline of 3 is appropriate because schema handles parameter documentation.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings by framing itself as the 'default entry point' and contrasting with ask_pipeworx_grounded and deep_research.

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

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

Provides extensive when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data...' and explicit alternatives: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' Also lists trigger phrases and concrete examples, making selection unambiguous.

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

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

Annotations already cover safety (readOnly, idempotent). The description adds beta-specific context: candidate routing experiments, current inactive state, and that it fully works (not a fallback). This addresses potential confusion about tool reliability and behavior.

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

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

Four information-dense sentences with no redundancy. Each sentence earns its place: definition, current status, usage directive, and clarification of non-fallback nature.

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 relationship to ask_pipeworx and the lack of an output schema, the description fully explains beta status, behavior differences, and current equivalence. It references the stable version's response shape, providing sufficient context 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 covers 100% of parameters, all being aliases for the same 'question' string. The description adds no additional parameter meaning beyond what the schema provides, so baseline 3 applies.

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

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

Clearly identifies itself as the beta version of ask_pipeworx, a universal router with the same 5,529 tools and response shape. Distinguishes from the stable sibling by explicitly noting experimental routing improvements.

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 direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' Also explains the comparison logic with the stable router, giving clear context for when to choose this variant.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the refusal mechanism (with four specific refusal_reason values), the return shape including evidence quote, and the extra LLM call cost. This provides rich behavioral context that annotations alone don't cover.

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

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

The description is front-loaded with the core purpose, then explains routing, return contract, usage context, and cost trade-off. Each sentence adds distinct value with no filler, despite being longer than average.

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 that routes across thousands of tools and has complex refusal logic, the description explains the return payload, refusal reasons, use cases, and cost comparison. With no output schema, this fully compensates and is complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question.' The description doesn't add new parameter detail, but the schema fully covers semantics, so baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers using only tool results, clearly distinguishing it from the sibling ask_pipeworx and other tools. This provides a specific verb (answer), resource (Pipeworx tool routing), and scope (grounded extraction).

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 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with 'prefer ask_pipeworx for casual lookups,' giving clear when-to-use and when-not-to-use guidance with the alternative named.

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 extensive behavioral detail: resolution mechanics, fan-out patterns, response shapes, confidence levels, parent event extraction, news field fallback handling, safety short-circuits for low confidence/closed markets, spread warnings, and cancellation rule parsing. 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 long (several paragraphs) but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It could be more concise, but the level of detail is justified by the tool's complexity and the lack of an output schema.

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, no output schema, and rich annotations, the description covers all necessary aspects: input types, processing behavior, output fields (market, analysis, evidence, resolver contract, parent event, news details), error/safety cases (low confidence, closed markets, wide spreads, cancellation rules). This is highly complete for agent use.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra value by explaining the depth enum values ('quick = 2-3 evidence sources, thorough = full fan-out') and providing concrete input examples for the market parameter, going beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies concrete input types (slug, URL, question text) and expected output (evidence packet + comparison), effectively distinguishing it from siblings like ask_pipeworx which are more general.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly contrast with alternatives or state when not to use, but the examples and classification list give strong contextual guidance.

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

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

Annotations confirm read-only, idempotent, non-destructive behavior. Description adds rich behavioral context: company type pulls latest 10-K from SEC EDGAR/XBRL with correct off-calendar fiscal year handling; drug type pulls FAERS, FDA approvals, trial counts. Results sorted by primary metric, returns paired data with 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?

Description is moderately lengthy but well-structured: starts with example queries, then details purpose and per-type behavior. Every sentence adds value; could be slightly tighter 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?

No output schema, but description covers return format (paired data + citation URIs) and sorting. For a tool handling two entity types with distinct data sources, it provides sufficient completeness.

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

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

Schema has 100% coverage with basic descriptions. Tool description adds significant extra meaning: what data each type retrieves, sorting behavior, and that values are tickers/CIKs for companies or drug names. 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?

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with explicit example queries. It distinguishes from sibling tools like entity_profile by recommending against sequential single-entity lookups.

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

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

Explicitly defines when to use: for comparison, ranking, head-to-head queries. Advises preferring this over sequential lookups, implying alternatives. Also clarifies type parameter behavior for company vs drug.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses extensive behavioral traits: return format with verbatim evidence and citations, gaps[] for unanswered facets, contradictions[] for disagreeing findings, hop fields, semantic excerpting, and latency expectations (15-60s, up to 90s). It also clarifies that citations are always fetchable and that it never invents answers. This vastly exceeds the annotation baseline.

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 every sentence delivers critical information: account requirements, tool distinction, mechanism, use cases, exclusions, depth behaviors, return details, and performance expectations. It is front-loaded with the most actionable info (account requirement and alternative) and is structured logically. No filler or redundancy—each clause earns its place for a tool of this 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?

With only 2 parameters and no output schema, the description bears the full burden of explaining return values and edge cases, which it does thoroughly: findings packet composition, gaps[], contradictions[], hop and citation_uri fields, and behavior when topics aren't in the catalog. It covers expected latency and account tiers, leaving no meaningful gap in the agent's ability to predict invocation results.

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

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

While the schema already has 100% coverage (describing both 'question' and 'depth' with enum meanings), the description enriches both parameters significantly. It explains depth values in operational terms (quick=3 facets/single hop, standard=5 with gap recovery, thorough=8 with iterative chasing) and clarifies that question accepts broad/multi-part inputs. It also ties the thorough depth to a paid plan, adding practical semantics not 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?

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call, with a detailed explanation of how it decomposes questions into facets and routes them in parallel. It explicitly distinguishes itself from open-web search and other tools like ask_pipeworx, making its unique resource and scope unmistakable.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and directly names alternatives for specific cases ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also notes necessary prerequisites ('ACCOUNT REQUIRED') and the alternative for unsigned users, fully covering usage context.

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

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

Annotations indicate readOnlyHint, idempotentHint, non-destructive. Description adds that it returns top-N tools with full schemas ready to call, and no side effects. No contradiction.

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

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

Description is front-loaded with purpose, then usage guidance, return format, and a clear usage hint. Every sentence adds value; no redundancy.

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

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

Given the meta-tool function and multiple aliases, description covers when to use, what it returns (ready-to-call schemas), and a recommended call point. Without output schema, description adequately explains the output.

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

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

Schema covers 100% of parameters with descriptions and aliases. Description does not add significant semantics beyond examples already in schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool finds tools by describing data or task, with specific examples and a distinct meta-tool role. It differentiates from siblings by its discovery function.

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

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

Explicit guidance to 'call this FIRST' when needing to browse the tool set, with examples of when to use (e.g., SEC filings, FDA drugs). Clearly distinguishes from direct query tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral details: the patent source will sunset May 2025 and soft-fails, a GDELT→GNews fallback, and that only 'company' type is supported with ticker or CIK. 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 lengthy but every sentence adds value. It front-loads the core purpose and includes many examples. While slightly dense, it remains clear and well-organized. Minor improvements could include bullet points for readability.

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

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

Given the tool's complexity and lack of output schema, the description comprehensively lists returned data (cik, filings with URIs, fundamentals sorted by period, patents with sunset note, news fallback, LEI). It also mentions limitations (ticker/CIK only, patent sunset) that an agent needs to know.

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 clarifying that value can be ticker or zero-padded CIK and that names are not supported, and that type is limited to 'company'. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It provides multiple example queries and details the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), distinguishing it from chaining separate calls.

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

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

The description explicitly says to prefer this tool over chaining single-pack lookups for holistic views. It also notes that names are not supported, directing users to resolve_entity first if they only have a name, providing clear when-to-use 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about what gets destroyed (a stored memory by key) and appropriate use cases, which 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?

Three concise sentences: purpose, usage guidelines, and pairing suggestion. No redundant words, front-loaded with the core action.

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

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

Given the simple tool (one parameter, no output schema), the description covers all necessary context: what it does, when to use, and related tools. Annotations handle safety profile.

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 describes the 'key' parameter fully. Description mentions 'by key' but does not add new parameter details beyond schema coverage of 100%.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (delete) and resource (memory), and distinguishes from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also suggests pairing with 'remember' and 'recall', providing clear usage boundaries.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral context: fetches page, extracts title/description/links, emits standard format. No contradictions.

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

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

Single paragraph, front-loaded with purpose and action. Every sentence adds value, though could be slightly more concise.

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

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

No output schema, but description explains output format (single text blob) and use cases. Covers inputs, process, output, usage context; sibling tools are unrelated.

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

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

Schema covers both parameters (url, max_links) with descriptions. Description does not add new meaning beyond schema, but baseline 3 is justified given full coverage.

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

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

Description clearly states tool generates llms.txt file for any URL, with specific verb 'Generate' and resource 'llms.txt'. It explains the process and output, and distinguishes from sibling tools as none serve a similar purpose.

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

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

Describes three concrete use cases (getting client site indexed, drafting own llms.txt, auditing competitor). Provides context on when to use but does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns specific fields and is for reviewing active subscriptions, providing useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. No unnecessary words.

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

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

Given comprehensive annotations, full schema coverage, and no output schema, the description sufficiently covers purpose, return fields, and usage context for a simple list operation.

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

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

Schema coverage is 100% with inline description for the only parameter (include_inactive). The tool description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields. It distinguishes from siblings like subscribe and unsubscribe.

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

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

The description explicitly says to use for reviewing before adding more subscriptions or to find an id to cancel, providing clear context. It does not explicitly state when not to use, but the guidance 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 provide little (all false), so the description carries the burden. It discloses idempotency-like behavior via claim_token flow, rate limiting (5/day), cost (free, no quota impact), and that filing without an account still returns a token for later status checks. This is valuable non-obvious behavior that annotations do not capture.

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 adds necessary guidance: purpose, when to use, exclusion, identifier tips, claim_token process, rate limits, and cost. It is front-loaded with the core action and flows logically, though a few details could be condensed 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 feedback tool with no output schema, the description is remarkably complete. It covers scope, input expectations, the post-filing flow, rate limits, and cost. The claim_token explanation substitutes for missing output schema details. The nested context object and enum types are self-explanatory from the schema, and the description answers likely agent questions about side effects and follow-up.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful extra semantics beyond the schema by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and reinforcing that the message should be specific without pasting the end-user's prompt. This raises it above baseline.

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

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

The description states the exact purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist' — a specific verb and resource. It clearly distinguishes from siblings by emphasizing this is only for Pipeworx-associated tools, not external MCP servers, and by framing it as feedback rather than research or questioning. The scope is unambiguous.

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

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

Explicit when-to-use guidance is provided: use for bugs (wrong/stale data), feature/data gaps, or praise. It also gives a strong when-not-to-use: do not report issues for tools from other MCP servers, file them elsewhere. 'Not sure? Pipeworx tool names are the ones this connection lists' helps disambiguate. This is a model of usage 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?

Adds context beyond annotations: data source (CF analytics-engine), no PII, caching behavior. Consistent with readOnlyHint and idempotentHint.

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

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

Well-structured with front-loaded purpose and bullet-style use cases; some redundancy but overall efficient.

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

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

For a simple read-only tool with one parameter and no output schema, the description fully covers what is returned, data source, privacy, and caching.

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's parameter info exactly mirrors the schema's description, adding no new 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 it returns 'top tools, top packs, and total call volume' over a window, differentiating from siblings like discover_tools and ask_pipeworx.

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

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

Three explicit use cases are provided, though it does not mention when to use alternatives among siblings.

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

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

The description discloses behavioral traits beyond annotations: partition filter dropping placeholder slugs, semantic anchor with Jaccard similarity, fill check against live CLOB depth, and a warning not to trade when realizable_edge_pp ≤ 0. Annotations (readOnly, idempotent, openWorld) are consistent and the description adds rich context.

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

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

The description is lengthy and includes many technical details (e.g., Jaccard similarity, placeholder fraction). While front-loaded with the core purpose, it could be more concise. Some redundancy exists, such as repeating the partition check explanation.

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

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

Given the tool's complexity (two modes, multiple checks) and no output schema, the description explains the response structure (opportunities array with fields, partition_check object) and critical caveats (fill check, placeholder filtering). It provides sufficient context for an agent to use the tool correctly.

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

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

The input schema has 100% coverage with descriptions for both 'event' and 'topic' parameters. The tool description adds substantial meaning by explaining the two modes, providing example inputs, and detailing the internal logic (monotonicity checks, partition checks, fill check). This enriches the schema significantly.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It identifies the resource (Polymarket), the action (finding arbitrage), and the methodology. This distinguishes it from sibling tools like polymarket_edges, which focus on different aspects.

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: no args for trending scan, 'event' for specific market, 'topic' for cross-event scanning. It recommends 'event' for specific markets and directs to 'polymarket_fill_risk' for custom sizing. However, it lacks explicit when-not-to-use guidance, such as when a simple price check is needed.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: model details, edge calculation, Kelly fractions, slippage, caching (1h at KV level), Fed data limitations, and diagnostics for empty segments. It discloses all relevant 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?

The description is long (over 600 words) but well-structured: it starts with purpose, then details model families with sub-bullets, edge metrics, knobs, response structure, and caching. Given the tool's complexity (3 segments, 9 parameters, diagnostics), the length is justified and every sentence earns its place.

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

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

The description fully covers the tool's purpose, all input parameters (with usage context), output structure (by_segment with diagnostics), edge calculation, Kelly sizing, slippage assumptions, and limitations (e.g., Fed data unreliability). It is complete for an AI agent to understand invocation and interpretation.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds value by explaining the semantics of each knob (e.g., 'Tradeable-edge filter' for max_spread_pp and min_liquidity, why min_kelly doesn't filter partition arbs for min_partition_leg_kelly). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb ('scan') and resource ('Polymarket markets'). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and top markets.

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 it's built for 'what should I bet on today' and provides context on when to use it (agents discover opportunities without paging hundreds). It explains the three segments and tradeable-edge knobs, but doesn't explicitly state when not to use it or mention alternatives like polymarket_arbitrage.

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

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

The description adds significant behavioral context beyond the annotations: it explains that data comes from daily snapshots, the response includes time-series and trend classification, and decay calculations are based on daily closes not intraday. Annotations already indicate read-only, idempotent, and non-destructive behavior, which aligns with the description.

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

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

The description is front-loaded with the core question and well-structured into intro, response details, and limits. However, it is slightly verbose; it could be more concise without losing essential information.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and covers important details like limits and data sources. It leaves no ambiguity about the tool's output.

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

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

Schema coverage is 100%, so the baseline is 3. The description repeats the parameter names and defaults but does not add new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time using daily snapshots. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on temporal analysis rather than raw snapshot 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 implies when to use the tool (when needing edge persistence and decay info) and provides limits (60-day TTL). However, it does not explicitly state when not to use it or list alternative tools for other scenarios.

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

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

Description discloses detailed behavioral traits beyond annotations: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, etc., and for basket mode describes forced directional risk and thin_legs. Annotations are consistent (readOnlyHint=true, etc.).

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

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

Well-structured with sections for REQUIRES, SINGLE-MARKET, BASKET, and usage guidance. Front-loaded with core purpose. Slightly lengthy but every sentence adds necessary detail for a complex tool.

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

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

Comprehensive coverage of tool behavior, parameters, return values (despite no output schema), edge cases (thin books, partial fills, forced directional risk), and usage warnings. No gaps 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 coverage is 100%, but description adds significant meaning: explains size_usd as spend/target proceeds for single-market and settlement notional for basket, clarifies side defaults and auto-detection, and adds context for market and event parameters.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live order-book depth, distinguishing between single-market and basket modes. Differentiates from siblings like polymarket_arbitrage and polymarket_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?

Explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns of consequences like partial fills converting arb into directional risk.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: two modes, response fields (spread[], top_spreads_pp, safety fields), warning scenarios (non-equivalent bet shapes, no token overlap, temporal misalignment). No contradiction with annotations.

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

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

The description is detailed but well-structured with clear sections for modes, response, and safety fields. Front-loaded with purpose. Minor verbosity in safety explanations but all information earns its place.

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

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

Given no output schema, the description comprehensively explains the response structure, safety fields, and edge cases. Covers temporal alignment, compatibility warnings, and skipped comparisons. Sufficient for an AI agent to understand when and how to invoke the tool.

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

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

Schema descriptions already cover parameters (100% coverage). The description adds context beyond schema: explains that `topic` uses 10 pre-mapped macros, explicit params override topic, and gives examples in schema. This adds meaningful usage semantics.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains the response structure. This uniquely positions it among siblings (other polymarket tools are venue-specific).

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

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

Explicitly describes when to use `topic` vs explicit parameters. Warns that pre-mapped topics often return compatibility warnings, setting realistic expectations. Safety fields (compatibility_warning, temporal_alignment, skipped counters) guide when spreads are meaningful.

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 false. Description adds value by specifying scoping (anonymous IP, BYO key hash, account ID) and behavior on omitting key. No contradictions.

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

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

Three sentences, each serving a distinct purpose: core function, usage context with examples, and scoping/pairing with siblings. 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?

Tool is simple with one optional parameter and no output schema. Description covers retrieval use case, listing behavior, scoping, and pairing with remember/forget. Complete for agent decision-making.

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

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

Input schema covers the single optional parameter 'key' with full description (omit to list all keys). Description reinforces this but adds limited new semantic detail beyond schema. Baseline 3 justified.

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 retrieves a value saved via remember or lists all keys if omitted. Provides concrete examples (target ticker, address, research notes) and explicitly references sibling tools (remember, forget) to differentiate.

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

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

Description explains when to use (look up stored context without re-deriving) and gives use cases. Mentions scoping by identifier. While it doesn't explicitly state when not to use, it implies this is for retrieval only and pairs with remember/forget for save/delete.

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

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

The description contradicts the readOnlyHint annotation by stating that setting mark_read:true modifies the read status of events, which is a write operation. This is a direct contradiction.

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

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

The description is concise and front-loaded with the main purpose and key details. 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 5-parameter tool without output schema, the description covers all parameters, return format, and provides alternative access, making it complete.

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

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

The description adds meaning beyond the schema by explaining the effect of mark_read and unread_only filters. It also describes the return fields.

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

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

The description clearly states the tool's purpose: to pull fired events from a subscription feed, returning most recent alerts with specific fields. It distinguishes from siblings by mention of subscripition feed and alternative access method.

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

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

The description explains when to use the tool and mentions alternative access via GET endpoint. It does not explicitly say when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds valuable context: fans out to multiple APIs, GDELT→GNews fallback, USPTO soft-fail, and returns pipeworx:// citation URIs. No contradictions.

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

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

Front-loaded with examples and clear purpose, but slightly verbose. Every sentence provides necessary detail—data sources, fallback, parameter format, and return structure—without waste.

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

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

Despite no output schema, description states return structure: 'changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. Covers data sources, fallback behavior, and parameter format. For a complex multi-source tool, this is sufficient.

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

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

Schema coverage is 100%, so parameters are documented. Description adds extra context: 'since' accepts ISO date or relative shorthand, suggests '30d' or '1m' for typical monitoring. This enhances understanding beyond the schema.

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

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

The description starts with example queries like 'What's new with X', then clearly states 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It specifies data sources (SEC EDGAR, GDELT->GNews, USPTO) and explicitly contrasts with sibling tool entity_profile.

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

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

Provides explicit when-to-use via example queries, explains data source fallback behavior (GDELT preffered, GNews when rate-limited), and gives a clear redirect: 'Use entity_profile instead when you want the static profile...'.

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) with idempotency and non-destructiveness. The description adds significant behavioral context: scoping by identifier, persistence differences between authenticated users and anonymous sessions (24 hours), and the key-value nature. 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 five sentences, all informative. It starts with the main purpose, then when to use, then mechanism, then pairing. No redundant or unnecessary words. Very efficient.

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

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

For a simple key-value store tool with no output schema, the description covers purpose, usage, behavior, parameters, and pairing. It is fully self-contained and leaves no major gaps for an agent to interpret.

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 good descriptions for both parameters. The description adds value by providing concrete examples of keys (e.g., 'subject_property', 'target_ticker') and clarifying that value can be any text. This extra context aids the agent in selecting appropriate inputs.

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 'Save data' and identifies the resource as a key-value store for reuse across conversations/sessions. It distinguishes from sibling tools (recall, forget) by explicitly naming them. The purpose is specific and unambiguous.

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

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

The description provides explicit guidance on when to use: 'when you discover something worth carrying forward'. It also mentions pairing with recall and forget, giving context. It does not explicitly state when not to use, but the positive usage is clear enough for an agent.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description goes further by revealing internal cascade behavior, graceful degradation of LEI/FIGI enrichment, and explicit handling of unresolved identifiers. These are non-obvious behavioral traits that significantly help the agent anticipate outcomes.

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

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

The description is long but well-structured and front-loaded with user-intent examples. Every sentence adds substantive information about inputs, outputs, sources, or fallback behavior. There is no filler, and the structure (SUPPORTED TYPES) makes it easy to scan.

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

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

Given no output schema, the description compensates by explaining return identifiers, source provenance, unresolved fields, and degradation behavior. It covers both supported types with examples and fallback semantics, making the tool's behavior predictable and 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?

The schema already covers the type enum and value formats with examples (100% coverage). The description reinforces accepted inputs and adds meaningful context about what each type resolves to (cross-source identity spine vs RxCUI), aiding correct type selection. It adds some value but partially duplicates schema info.

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

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

The description opens with concrete user phrasing and a specific verb: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from siblings by naming exact output identifiers (CIK, LEI, FIGI, RxCUI) and states 'Use FIRST whenever you have a name but need an ID.' This clearly differentiates it from entity_profile or validate_claim.

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 a clear trigger: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces 2-3 manual lookups. However, it does not explicitly mention when not to use it or name alternative tools for other use cases, so it lacks the full when/when-not/alternatives structure.

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

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

The description adds behavioral traits beyond annotations: it probes with ai_visibility_check, treats the first entity as the 'subject' for narrative, and returns a ranked list with score, confidence, and signal density. It aligns with readOnlyHint and destructiveness annotations, adding useful context.

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

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

The description is concise at four sentences, front-loads the main purpose, and each sentence provides value. Minor redundancy could be trimmed, but overall efficient.

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

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

Given no output schema, the description adequately specifies returns (ranked list with score, confidence, signal density) and explains the tool's role. It could mention the entity count constraint from the schema, but still fairly complete for its complexity.

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

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

Schema coverage is 100%, but the description adds extra meaning by explaining that the first entity is treated as the 'subject' and that models can be omitted for just workers-ai. This enriches the schema's parameter descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side by probing each with ai_visibility_check, ranking results, and surfacing most/least recognized. It distinguishes itself from sibling tools ai_visibility_check (single entity) and compare_entities by specifying the composite behavior.

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

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

The description provides clear usage context: useful for competitive AI-marketing audits to compare brand awareness. However, it does not explicitly state when not to use it or mention alternatives like compare_entities, missing some exclusion guidance.

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

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

Annotations already mark read-only, idempotent, open-world. Description adds critical behavioral details: fans out to two external services, partial failures degrade gracefully (bundlephobia timeout 5-30s listed in sources_failed), returns specific fields. 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 relatively long but each sentence adds value. Front-loaded with purpose. Could be slightly more concise but not wasteful.

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

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

Given the tool's complexity (composite external calls, partial failures, specific return structure), the description provides complete context. No output schema but description details return fields. Annotations cover safety. Adequate for agent to understand and use correctly.

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

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

Schema coverage is 100% with good descriptions. Description adds extra context: scoped packages accepted for 'package', default behavior for 'version'. Adds value beyond schema without redundancy.

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

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

Description clearly states the composite purpose: check npm package for safety, popularity, size. Uses specific verbs and resources (deps.dev, bundlephobia). Distinguishes from siblings by focusing on package dependency analysis, while siblings are other research tools.

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

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

Explicitly gives query examples: 'is X safe / popular / small' and 'what does adding lodash cost me'. States ecosystem limitation and directs alternative ecosystems to deps.dev:version directly. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint false, and openWorldHint. The description adds significant behavioral details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation and flagging, and that every passage carries an offset for verification. 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 dense but well-structured as a single paragraph. It front-loads the purpose, provides use case guidance, explains benefits, and includes technical details. Every sentence adds unique value without redundancy.

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

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

Given no output schema, the description explains return values: top-N passages with character offsets and similarity scores. It covers limits (200K char cap, truncated and flagged) and explains the embedding/windowing approach. The description is thorough and leaves little ambiguity.

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

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

Schema description coverage is 100%, with descriptions for all three parameters. The description adds value by stating the 200K char cap for the 'text' parameter, providing example queries for 'query', and noting the default of 5 for 'limit'. This goes beyond the schema, meriting 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 verb 'search' and the resource 'a fetched record' (e.g., SEC 10-K). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing that it saves context by returning only relevant passages.

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 when the record is too big to cram into the prompt' and explains how it saves context and returns only relevant passages. It also mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use or recommend alternatives for smaller texts.

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 authentication needs (anonymous/BYO cannot persist), SMS cap (10/day), webhook auto-disable after 10 failures, and one-time delivery of webhook secret. Consistent with annotations (no contradiction).

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

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

Well-structured with clear sections (purpose, requirements, types, delivery), though slightly wordy. Each sentence adds value, but could be slightly more concise.

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

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

Covers all essential aspects: supported types with parameters, delivery options with constraints, auth requirements, return value, and important behavioral notes (caps, auto-disable). No output schema, but return value is mentioned.

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

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

Adds significant value beyond schema with examples for each type, SMS/email requirements, webhook signing details. Schema coverage is 100%, but description enriches understanding.

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

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

The description clearly states the action ('Create a proactive monitoring subscription to a live-data event stream') and the output ('Returns the new subscription id'), distinguishing it from sibling tools like 'unsubscribe' 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?

Provides clear context for when to use (proactive monitoring), requirements (Pipeworx OAuth account), supported types with examples, and delivery channels. Lacks explicit 'when not to use' but the context 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?

Annotations already declare readOnlyHint, openWorldHint, destructiveHint=false. The description adds behavioral context: returns example questions with tool+argument shapes, and can be called with no arguments or a topic. 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 longer but well-structured, front-loaded with common questions users might ask. Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the moderate complexity, schema coverage, and no output schema, the description adequately explains what the tool returns and when to use it. It covers context without needing explicit output structure.

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

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

Schema coverage is 100% (topic parameter described). The description adds extra meaning: 'Omit for a cross-category spread' and lists possible values with categories, which goes beyond the schema description.

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

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

The description clearly states the tool's purpose: an onboarding entry point that returns categorized example questions. It specifies the verb (returns) and resource (example questions). However, it does not explicitly distinguish itself from sibling tools beyond mentioning meta-tools.

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

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

The description explicitly states when to use: 'when you do not yet know what Pipeworx can do for you' and recommends alternative meta-tools (ask_pipeworx, entity_profile, etc.) for when the user already has a specific task.

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

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

Discloses key behavioral traits beyond annotations: ownership enforcement, deactivation (not deletion), and impact on historical events via recent_alerts. Aligns with annotations (readOnlyHint=false, destructiveHint=false).

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 efficient sentences covering action, constraint, and side effect. No filler, every sentence adds critical 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?

No output schema, but the description sufficiently explains the mutation effect and data retention policy. Complete for this simple tool with strong annotations.

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 description linking id to subscribe output. Description reinforces the id requirement and ownership context, adding value over schema alone.

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 verb 'cancel' and the resource 'subscription by id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by adding ownership enforcement and deactivation behavior.

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 indicates ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Doesn't explicitly contrast with alternatives, but no sibling tool unsubscribes, so context is clear.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds rich behavioral context: the routing logic, the precise meaning of could_not_verify vs unsupported (including the presence of verification_error and the explicit "must not be shown as one"), and the return value structure. It materially helps the agent interpret results correctly.

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 it is front-loaded with trigger phrases and organized into clear sections (scope, paths, return, important caveats). Every sentence adds functional value. It could be trimmed slightly, but the structure earns a high score.

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 only 2 parameters and no output schema, the description fully covers what the tool returns (verdict options, cited value, reasoning), handles edge cases (could_not_verify vs unsupported), and explains the underlying data sources. It is self-contained and complete for an agent to use correctly.

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

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

Schema coverage is 100% with both parameters already described. The description adds extra value by explaining tolerance_pct overrides the claim wording, suggests 1–2 for hallucination detection, and notes the default cap of 5. This goes beyond the schema definitions, improving practical usage.

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

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

The description explicitly states the tool verifies natural-language factual claims ("fact check", "verify the claim that…") and distinguishes two clear execution paths (SEC EDGAR for company-financial claims, grounded pipeline for all others). This is a specific verb+resource with clear scope, setting it apart from broader research tools like deep_research or ask_pipeworx_grounded.

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

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

It gives explicit when-to-use: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains the two internal paths and notes it replaces 4–6 sequential calls. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the highest bar.

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