Tides

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by detailing the output structure (per-model score, confidence, signals, raw_response, combined view) and the external API call and billing implications for Anthropic.

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 that efficiently conveys key information: purpose, parameters, usage scenarios, and output. It is well-structured and front-loaded with the main action, 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?

With 4 parameters and no output schema, the description is fairly complete: it explains all parameters, the default behavior, and the structure of the response. It does not mention any limits or edge cases, but it is adequate for a straightforward probing 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%, baseline 3. The description adds meaning beyond schema descriptions: it explains the entity parameter's scope, that models defaults to workers-ai, _apiKey is only needed for Anthropic, and context disambiguates entities. This adds significant value.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility, specifying default model and optional Anthropic key. It's specific but does not explicitly differentiate from sibling tools like scan_competitor_ai_presence or deep_research.

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

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

The description provides context for when to use the tool, e.g., AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to include the _apiKey parameter, but does not discuss when not to use it or mention 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context: it fills arguments automatically, returns citation URIs, works on every tier, and is a fast single call. It also clarifies that it routes to live news for breaking news, which is beyond the annotations.

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

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

The description is longer than typical but every sentence earns its place: usage guidance, examples, alternatives, and behavioral traits. It is front-loaded with 'PREFER OVER WEB SEARCH' and structured logically, though it could be tightened slightly 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 read-only query tool with strong annotations and a simple one-required-parameter schema, the description is comprehensive. It covers the return format (structured answer with citations), scope (real-world entities, events, numbers), performance (one fast call, all tiers), and fallback tools. No output schema exists, so this description carries the full explanatory burden and meets it well.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for 'question'. The description adds no extra parameter semantics beyond reaffirming the natural-language question input, but the schema already provides examples and alias explanations, so a baseline 3 is appropriate.

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

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

The description clearly states the tool answers factual questions by routing to thousands of sources and returning structured answers with citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its unique role 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?

Provides explicit guidance: 'PREFER OVER WEB SEARCH' for specific domains, lists trigger phrases, and gives examples. It also states when to step up to ask_pipeworx_grounded or deep_research, covering both usage and alternatives.

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

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

The description goes beyond the annotations by disclosing that this is a live experimental router, that no candidate is currently active (retired 2026-07-26), that it currently matches ask_pipeworx exactly, and that it falls back to nothing — it's a full working router. It even clarifies the experimental edge and comparison purpose, which is rich behavioral context beyond the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The description is a single paragraph of three sentences that front-loads the key identity (beta of ask_pipeworx) and packs the essential details: same router/tools/arguments/response shape, candidate routing status, current equivalence, and usage guidance. No wasted words; 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?

For a router tool with no output schema and a single question parameter, the description is complete: it covers what it does, how it relates to the stable sibling, current state, and fallback behavior. With 100% schema coverage and rich annotations, nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with clear aliases for the question parameter. The description adds little beyond the schema, but it does confirm that arguments are identical to ask_pipeworx, which is useful for an agent deciding between siblings. Since the schema fully documents the parameters, a baseline of 3 applies, with the sibling-identity note pushing it 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 identifies this as the beta version of ask_pipeworx with the same universal router (5,439 tools, same arguments, same response shape). It explicitly distinguishes it from the stable ask_pipeworx sibling by stating it has candidate routing improvements enabled live when under test, and notes it currently matches ask_pipeworx exactly. This is a specific verb+resource+scope with clear sibling differentiation.

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 it exactly like ask_pipeworx when you want the newest routing, and that results are compared against the stable router to decide what merges. This provides clear when-to-use context and an implicit alternative (the stable ask_pipeworx), with no ambiguity about its experimental edge.

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?

Even though annotations already declare readOnly and idempotent hints, the description adds critical behavioral context: it returns {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and explicit refusals with specific reasons (not_in_source, no_tool_match, etc.). It also discloses the 'USING ONLY what the tool result contains' policy and the extra LLM call cost. No contradiction with annotations.

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

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

Every sentence earns its place: mechanism, return format, refusal reasons, use cases, and cost tradeoff. It front-loads the core purpose and then structures details logically. Despite length, there is zero filler, making it appropriately sized for a high-stakes grounded QA 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?

The description is remarkably complete for a tool with no output schema. It fully specifies the success return object with fields, the refusal response structure with all possible refusal_reason values, the anti-hallucination guarantee, when to use, and the cost/alternative guidance. This covers all necessary context for an agent to invoke it correctly.

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

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

Schema description coverage is 100% with all six parameters documented as aliases for the single 'question' param. The description does not add any new parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate. The tool's internal 'fills arguments' behavior is mentioned but not tied to the input 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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes like ask_pipeworx, fetches data, and extracts answers only from the tool result. This distinguishes it from sibling ask_pipeworx by emphasizing the grounded extraction and refusal 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 specifies when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups). Also names the alternative and gives a clear preference: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: low-confidence short-circuits, closed market handling, wide spread warnings, cancellation rule parsing, and 24h move warnings. This far exceeds annotation coverage.

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 (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) but is quite verbose (11 paragraphs). Some details, like exhaustive fan-out examples, could be shortened or moved to documentation. A more concise version would maintain clarity while reducing length.

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 return values: result.market details, analysis with model probability and edge, evidence keys, resolver contract with match confidence and alternatives, parent event extraction, news fields with fallback info, safety short-circuits, and cancellation rule. All edge cases are covered.

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 context beyond schema: depth choices ('quick' vs 'thorough'), behavior of include_raw (summarized vs full payloads), and examples for market input. This enhances 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' and lists specific use cases like 'should I bet on X'. It distinguishes from sibling tools such as polymarket_arbitrage and polymarket_edges by focusing on research rather than arbitrage or edge tracking.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also provides guidance on inspecting the resolver contract for match confidence. However, it does not explicitly state when not to use this tool versus alternatives, though the purpose is clearly scoped.

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 rich behavioral context beyond annotations (readOnlyHint, idempotentHint): details what data is pulled for each type (SEC EDGAR financials for company, FAERS/drug data for drug), notes correct handling of off-calendar fiscal years, and mentions citation URIs. This fully informs the agent of expected 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?

Single paragraph efficiently packs trigger phrases, purpose, type-specific details, and efficiency claim. Every sentence adds value with no fluff. Front-loaded with key triggers and 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?

Description covers all essential aspects: purpose, usage, entity types, data sources, constraints, response format (paired data + citations). Without output schema, the description sufficiently explains return structure. Complete for a comparative lookup 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 already covers both parameters with descriptions (100% coverage). Description adds context: explains that type='company' pulls specific financial metrics and type='drug' pulls adverse events, FDA approvals, trials. It also clarifies values format (tickers/CIKs vs drug names) and constraints (2-5 items). This adds significant 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 explicitly states 'side-by-side comparison of 2–5 companies or drugs' and lists trigger phrases like 'compare X and Y' or 'rank these companies'. This clearly defines the tool's unique function and distinguishes it from siblings such as entity_profile for 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?

Description includes explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also explains when to use (comparing entities) and implies efficiency benefit. Missing explicit when-not-to-use or alternatives for non-comparison tasks, 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?

Beyond the readOnlyHint annotation, the description discloses the output structure (findings packet with evidence, confidence, source, citation, gaps[]), limitations (empty gaps[] for topics outside the structured catalog), depth-dependent behaviors (contradictions[] scan, hop counts), semantic excerpting, and latency ranges. It also explicitly assures 'never invented' evidence, adding trust.

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 each sentence adds distinct operational or decision-relevant info (account, data sources, output format, use cases, alternatives, depth behavior, latency). It could be slightly trimmed without losing core value, but it is well-structured and front-loaded with prerequisites.

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 specifies the return structure, limitation handling, and operational expectations (latency, account tiers). It also covers sibling differentiation, failure modes, and depth semantics, making it complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with detailed enum descriptions, so the baseline is 3. The description adds extra meaning by noting that depth:'thorough' requires a paid plan, and explains how each depth mode affects research behavior (gap recovery, chasing leads), enriching the schema's 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 a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources... in ONE call.' It distinguishes itself from open-web search and sibling tools like ask_pipeworx, and provides concrete example use cases. The scope and output are explicit.

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: 'Best for broad/multi-part questions over structured data' and explicitly names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx.' It also covers account prerequisites and a fallback if not signed in.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that each result includes full input schemas with curated examples and is ready to call directly, which provides useful behavioral context beyond the annotations.

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

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

The description is front-loaded with the core purpose and includes a list of example domains, which is useful but slightly verbose. Overall well-structured without fluff.

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

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

Despite lacking an output schema, the description thoroughly explains what the tool returns (names, descriptions, full schemas) and confirms results are callable directly, making it complete for a search/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 description coverage is 100%, so the schema already documents all parameters. The description does not add significant meaning beyond that, though it clarifies that the main parameter is a natural language query.

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 'Find tools by describing the data or task' and enumerates specific domains (SEC filings, FDA drugs, etc.), making the purpose explicit and distinguishing it from sibling tools which focus on specific data retrieval or 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?

It explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing strong contextual guidance on when to use this tool versus 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 cover readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: parallel fan-out across sources, specific return fields, and soft-fail for patents. It doesn't mention rate limits or latency, but overall it complements annotations well.

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 preference statement, then output details. It is thorough but slightly verbose; every sentence adds value, though it could be slightly trimmed. Good front-loading.

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 (multi-source, parallel) and lack of output schema, the description comprehensively lists all returned fields (cik, filings with URIs, fundamentals, patents with caveat, news, LEI) and constraints (US public companies only, names not supported). It is complete and informative.

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 reinforces parameter details with examples (e.g., 'AAPL', '0000320193') and cross-reference to resolve_entity, but the schema already includes 'Names not supported.' Thus the description adds marginal value beyond the schema.

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

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

The description clearly states the tool's purpose: providing a holistic profile of a US public company from multiple sources in one call. It uses specific verbs like 'full cross-source profile' and 'fans out,' and distinguishes from sibling tools like resolve_entity and compare_entities.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view') and when not to use it ('names not supported — use resolve_entity first'). It also gives clear input requirements (ticker or zero-padded CIK).

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

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

Annotations already declare destructiveHint=true, so the description adds minimal new behavioral insight. It reinforces the destructive nature and mentions 'clear sensitive data,' providing slight context but no new 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 efficient sentences that front-load the purpose and immediately follow with usage guidance. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema, annotations cover key traits), the description is complete. It covers purpose, usage, and sibling relations.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds no additional meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and specifies the resource. It distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing them, indicating its unique role.

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, task is done, clear sensitive data') and mentions pairing with 'remember' and 'recall', which implies 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it fetches the page, extracts title/description/key links, emits standard markdown, and outputs a single text blob. 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?

Two sentences cover purpose, process, output format, and use cases. No redundant words. Every sentence is essential and 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 only 2 parameters, no output schema, and comprehensive annotations, the description fully explains input, output, and all relevant behaviors. Nothing is missing for correct tool invocation.

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

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

Schema coverage is 100% with both parameters described. The description adds value by explaining url as 'Full URL...' with examples, and max_links includes default/max values (25, 50). This enriches the schema definitions 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 explicitly states the action ('Generate'), the resource ('llms.txt file'), and the target ('any URL'). It clearly distinguishes from siblings by focusing on a unique function (llms.txt generation) not present in other tools like ai_visibility_check or scan_competitor_ai_presence.

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 concrete use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This guides the agent on when and why to use this tool, implicitly excluding other AI visibility tasks.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds context on the default active-only listing and the fields returned, which are beyond the annotations. However, it does not mention pagination or rate limits, but for a simple listing tool this is adequate.

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 two concise sentences: the first states the purpose and output, the second provides usage guidance. Every sentence adds value, and the structure is front-loaded with the core functionality.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete. It covers the purpose, output fields (compensating for missing output schema), and provides explicit usage context, meeting all informational 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 coverage is 100% and the parameter include_inactive is already described in the schema. The description does not add further semantic detail beyond what the schema provides, so it meets the baseline for parameter semantics.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, distinguishing it from sibling tools like subscribe and unsubscribe. It also enumerates the returned fields, making the tool's purpose unambiguous.

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

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

The description explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel. While it provides clear context, it does not mention when not to use it or alternative tools for other scenarios, but the guidance is sufficient for typical 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?

Beyond empty annotations, the description discloses rate limiting (5/day per identifier), that it is free and doesn't count against quota, and that the team reads digests daily with roadmap impact. It also instructs users not to paste the end-user's prompt, which is an important behavioral constraint.

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 but well-organized: purpose, use cases, exclusion, content guidance, and processing details. Every sentence contributes essential information without redundancy or fluff.

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

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

For a feedback tool with no output schema, the description covers the complete usage cycle: what triggers it, how to frame the message, scope limitations, and expected outcome (team reads digest, affects roadmap). Nothing significant is missing.

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 already well documented. The description adds extra value by advising users to describe issues in terms of Pipeworx tools/packs and to avoid pasting end-user prompts, which goes beyond the schema's field 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: to tell the Pipeworx team about broken, missing, or desired functionality. It specifies the types of feedback (bug, feature, data_gap, praise) and distinguishes this tool from siblings like ask_pipeworx or discover_tools, which are research-oriented.

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

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

Explicit when-to-use guidance is provided for each feedback type. The description also explains when NOT to use the tool (for tools from different MCP servers) and directs users to file with that server instead, offering a clear exclusion criterion.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by revealing the data source ('CF analytics-engine'), privacy stance ('no PII'), and caching behavior (5min-1h). These details go 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 concise and well-structured: immediate purpose sentence, bullet-list use cases, then implementation details. Every sentence provides unique value with no redundancy.

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

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

Given the tool has only one optional parameter and no output schema, the description covers all essential aspects: what it does, when to use it, how it works (self-aggregating, cached), and privacy considerations. No gaps remain.

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

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

Schema coverage is 100% for the single parameter. The description adds meaningful context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps agents choose between enum values.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over configurable windows. It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume') and distinguishes itself from sibling tools like discover_tools by focusing on trending data derived from other AI agents' activity.

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 explicit use cases: discovering hot data sources, confirming popular tools, and checking alignment with agent needs. While it doesn't explicitly state when not to use it or name alternatives, the provided contexts are clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: partition checks, semantic anchor with Jaccard similarity, partition filter, fill check with realizable edge thresholds, and when not to 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?

The description is fairly long but front-loaded with purpose and usage. Every sentence adds value, though some internal details (e.g., semantic anchor specifics) could be more concise. Still well-structured 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?

Given the tool's complexity and no output schema, the description thoroughly explains the return format, including fields like opportunities[], partition_check, and fill check logic. It also covers edge cases like skipped_low_similarity and placeholder filtering.

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

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

Both parameters have descriptions in the input schema (100% coverage). The description adds significant meaning beyond the schema: explains what event slugs look like, that full URLs are accepted, and that topic is a seed question. It also clarifies the default behavior when no args are passed.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three calling modes (no args, event, topic) with specific verbs and scope, differentiating from siblings.

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

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

The description explicitly says when to use each mode: call with no args for trending scan, pass 'event' for a specific market, or 'topic' for cross-event scanning. It recommends event mode for specific markets and provides examples, offering 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 indicate read-only, idempotent, open-world behavior. The description adds rich behavioral details: caching (1h at KV level), diagnostic fields to explain empty segments, edge computation with slippage, and model families. 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 dense and informative but excessively long, covering technical details like model formulas and caching. It front-loads purpose but could be more concise. Every sentence adds value, but structure is somewhat sprawling.

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 complex tool with 9 parameters and no output schema, the description comprehensively explains the response structure (by_segment, diagnostics), edge computation, filters, and caching. It leaves no ambiguity about what the tool returns or how it behaves.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The tool description provides overarching context for the 'knobs' but does not significantly enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the use case 'what should I bet on today' and distinguishes from siblings by focusing on edge detection from Pipeworx 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 provides context for when to use the tool (discovering betting opportunities without paging hundreds of markets) but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker. Implied usage is clear but lacks explicit 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds behavioral details: snapshots written on cache-miss causing gaps, decay computed from daily closes (not intraday), and history bounded by 60-day TTL. 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 relatively long but well-structured: problem statement, args, response structure, and limits. Every sentence provides useful information. Could be slightly more concise, but effective front-loading.

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

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

Despite no output schema, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) and covers all behavioral nuances. With only 2 optional parameters and full schema coverage, the description is complete and leaves no major gaps.

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

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

Schema coverage is 100% with both parameters already documented in the schema. The description adds context: default values, clamp on days (2-30), and explains window as snapshot family. This adds value beyond the schema.

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

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

The description clearly states it answers 'how long has this edge existed and is it shrinking?' and focuses on edge persistence and decay telemetry. It distinguishes from sibling tool 'polymarket_edges' by emphasizing historical persistence 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 explicitly frames when to use it: to assess if a wide edge is fresh or stale. It contrasts a fresh wide edge with a 3-week-old one. It also discusses limits like 60-day snapshot TTL and dataset gaps. No explicit naming of alternative tools, but implicit contrast with polymarket_edges.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: walks the ladder, returns verdict (clean|degraded|cannot_fill), identifies thin_legs and forced_directional_risk. 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?

Reasonably structured with sections (REQUIRES, SINGLE-MARKET, BASKET) and bullet-like output lists. Every sentence adds value though slightly verbose for a tool description; could be tightened around the repeated 'returns' enumeration.

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 exhaustively lists return fields for both modes, including edge cases (thin_legs, forced_directional_risk). Covers parameter defaults, clamp ranges, and practical rationale for using 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 coverage is 100% with descriptions for all 4 parameters. Description adds further nuance: explains side defaults per mode, size_usd interpretation for buys vs sells, and basket-specific settlement notional concept.

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 checks realizable-vs-theoretical edge against live order-book depth, defines two distinct modes (single-market and basket), and lists specific outputs. Distinguishes itself from sibling tools 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 when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why partial basket fills convert arb to unhedged directional position, providing clear context for avoidance.

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. Description adds substantial behavioral detail: compatibility_warning conditions (matched_pairs, skipped_cross_type), temporal_alignment field, and skipped_cross counters. 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 long but front-loaded with a clear summary. Each section (modes, response, safety) is structured with bold labels. Could be slightly trimmed but every sentence adds value.

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

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

Given the complexity of the tool (cross-venue spread, multiple modes, safety warnings), the description covers all important aspects: modes, response fields, compatibility_warning conditions, temporal_alignment, skipped counters. No output schema but response structure is described.

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

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

All 3 parameters are described in the input schema (100% coverage). The description adds value by explaining the two modes and interaction between topic and explicit tickers. It provides the list of topic shortcuts and examples.

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 tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on two specific venues and including safety warnings. The description explains two modes and response 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?

Provides explicit when-to-use guidance: compare venues for same question. Warns that most pre-mapped topics return compatibility_warning, so users know limitations. Also explains when not to use (bet shapes not equivalent, temporal misalignment) and gives alternatives implicitly.

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

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

Annotations already indicate readOnly and idempotent; description adds scoping behavior and return behavior (value vs list). Does not contradict 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 plus a scoping/pairing sentence, all essential and front-loaded. No redundancy.

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

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

Covers usage, parameter semantics, behavioral traits, and integration with sibling tools. Sufficient for a simple read-only 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 explains the effect of omitting the key (list all) vs providing it (retrieve specific), adding meaning beyond the schema's 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 retrieves a value by key or lists all keys, with concrete examples and connection to 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?

Explicitly says when to use (look up stored context), how to use (with or without key), and pairing with remember/forget. Also mentions scoping.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds behavior: mark_read flags events read so next call shows newer ones, explains return payload structure, and notes feed availability. 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 covering purpose, return info, filtering, and alternatives. No fluff; every sentence adds value. Front-loaded with main 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 5 optional parameters, no output schema, and rich annotations, description fully explains return data, parameter effects, and use cases. No missing aspects.

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 cover all 5 parameters (100%). Description adds context beyond schema, like mark_read effect and polling suitability, but schema already provides clear parameter explanations.

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 pulls fired events from the subscription feed, lists return fields (source, citation_uri, raw payload), and supports filtering by type and timestamp. Differentiates from siblings like list_subscriptions by focusing on event retrieval.

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

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

States that polls work fine and provides an alternative HTTP endpoint for scripts/dashboards, guiding when to use the tool vs direct access. Could be more explicit about when to avoid the tool, but the alternative 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 safety and idempotency. The description adds details about fan-out to multiple sources, fallback behaviors, and API sunset, which goes beyond annotations. Could include more on error handling.

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?

Some redundancy in query examples, but front-loaded and well-structured with technical details later. Could be slightly shorter but still 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?

No output schema, so description must explain return values. States 'changes[] grouped by source + total_changes count + citation URIs', which is adequate given complexity. Not exhaustive but sufficient.

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

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

Schema coverage is 100% with descriptions. The description adds context: 'since' examples and typical use ('30d' or '1m'), 'value' can be ticker or CIK, and 'type' is only 'company'. Adds meaning 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 this tool provides a change feed for a company over a time window, with multiple example queries. It distinguishes from sibling 'entity_profile' by explicitly stating when to use that instead.

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 usage examples and when-not-to-use guidance: 'Use entity_profile instead when you want the static profile...' This helps the agent decide between 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?

Adds key behavioral details beyond annotations: key-value pairs scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. No contradictions with annotations (idempotent, non-destructive).

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

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

Four sentences, front-loaded with core purpose. Every sentence earns its place - no redundancy, logical flow from purpose to usage to behavioral details to companion tools.

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

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

Complete for a storage tool: explains persistence, scoping, and pairing with recall/forget. No output schema needed for a write operation; any gaps are addressed in companion tool descriptions.

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

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

Schema already describes key and value well (100% coverage). Description adds value by illustrating valid keys (e.g., 'subject_property') and noting value can be any text, helping an agent select appropriate 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?

States 'Save data the agent will need to reuse later' - clear verb and resource. Provides specific examples of what to store (resolved ticker, target address, etc.) and distinguishes from siblings recall 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?

Explicitly says 'Use when you discover something worth carrying forward' and provides when-not-to-use context by referencing the complementary tools recall and forget as 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, idempotentHint=true, etc. The description adds that the tool cascades through several lookup endpoints internally and replaces 2-3 manual lookups, enriching behavioral context beyond the annotations.

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

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

The description is a single paragraph but well-structured with examples, supported types, and return information. Every sentence adds value; no redundancy or 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?

Although no output schema, the description thoroughly explains return values (ticker, CIK, RxCUI, citation URIs) for both types. It covers usage, supported entities, and internal processing, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description extensively explains both parameters: 'type' with enum values and their mapping, 'value' with examples and accepted formats for each type. This adds significant meaning 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 resolves names to canonical identifiers, with specific examples like 'What's the ticker for…' and listing supported types (company, drug). It does not explicitly differentiate from sibling tools like entity_profile, but the purpose is unambiguous.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It details supported types and what they return, but lacks explicit when-not-to-use instructions or comparisons to alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds process details (probes via ai_visibility_check, ranks by score) and output structure, which goes beyond annotations without contradiction.

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

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

Two sentences, front-loaded with core functionality, no filler. Every sentence earns its place.

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

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

Given no output schema, the description adequately describes the return format (ranked list with score, confidence, signal density). It omits details about the models and _apiKey parameters, but those are covered in the schema.

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

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

Schema description coverage is 100%, but the description adds value by explaining that the first entity is treated as the subject and the rest as competitors. This semantic nuance is 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 it compares AI visibility across multiple entities side-by-side and ranks them, distinguishing it from sibling ai_visibility_check which is for single entities. The verb 'compare' and resource 'AI presence' are 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?

The description gives a concrete use case (competitive AI-marketing audits) and implies the alternative of using ai_visibility_check for single-entity checks. It does not explicitly list when not to use, but the context is clear.

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

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

The description adds significant behavioral context beyond annotations, such as partial failures, bundlephobia first measurement delay (5-30s), graceful degradation with sources_failed, and that it returns a summary block, details, links, and alternatives. 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 fairly concise given the amount of information. It is front-loaded with the main purpose and then provides necessary details. A slight trim could be made, but it's 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 comprehensively explains what the tool returns (summary block, per-advisory detail, links, alternative versions) and handles edge cases (scoped packages, fallback behavior). No output schema exists, so the description fully explains the return, leaving no gaps.

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

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

Schema description coverage is 100% for both parameters, so baseline is 3. The description mentions scoped packages for 'package' and default version for 'version', which are already in the schema. It adds marginal extra 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 tool's composite purpose: a one-call check for adding an npm package, covering license, advisories, version history, and bundle info. It distinguishes from siblings by specifying the npm ecosystem and directing other ecosystems to a different 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 explicitly tells when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also notes the limitation to npm and provides an alternative for other ecosystems, giving clear guidance.

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

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

Annotations already provide safety hints, but the description adds substantial behavioral context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and return format (offsets and similarity scores). This goes well beyond what annotations convey.

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

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

Three sentences efficiently convey purpose, usage, technical details, and pairing advice. No filler; every sentence earns its place. 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?

Despite no output schema, the description explains the return value (top-N passages with offsets and scores). It also covers technical constraints (embedding, window size, char limit) and the intended workflow. For a tool of this 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 baseline is 3. The description adds value by providing concrete examples of what 'text' can be (SEC 10-K, article) and illustrative queries. This adds semantic context beyond the schema's type definitions.

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

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

The description clearly identifies the tool as performing 'Semantic search INSIDE a fetched record', specifying the verb, resource, and scope. It contrasts with sibling tool 'ask_pipeworx_grounded', establishing a distinct purpose.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also pairs it with 'ask_pipeworx_grounded' for a recommended workflow. No explicit when-not-to-use, but the context is sufficiently 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 show idempotentHint=true and destructiveHint=false, but description adds crucial behavioral details: returns subscription id, OAuth requirement, delivery channel limitations (sms cap, webhook signing and auto-disable). 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 but front-loaded with main purpose. Covers many details without excessive length. Could use more structured breaks, but still 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 and 3 parameters with nested objects, the description is remarkably complete: covers all types, delivery options, requirements, and limitations. Returns value 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?

Schema coverage is 100%, so baseline 3. Description adds value beyond schema by explaining type-specific parameters (e.g., item codes for sec_8k, topics for polymarket_edge) and details on delivery webhook signing and auto-disable.

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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' The verb 'create' and resource 'subscription' are specific. It distinguishes from siblings like list_subscriptions, unsubscribe, recent_alerts.

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

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

Provides explicit context: requires Pipeworx OAuth account, anonymous/BYO cannot persist. Lists supported types with examples (sec_8k, polymarket_edge, fred_series) and delivery options with constraints. Does not explicitly say when not to use, but the guidance 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 provide readOnly, openWorld, idempotent, and non-destructive hints. Description adds value by explaining it returns categorized examples with exact tool calls, drawn from a live catalog. Does not contradict 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 front-loads key questions and efficiently covers purpose, return content, and usage. Every sentence adds value, though slight redundancy in listing categories.

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?

Even without an output schema, the description fully explains what the tool returns: category-bucketed examples with tool+argument shapes. This is sufficient for a discovery tool with annotations indicating safe, read-only behavior.

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 the optional topic parameter with 100% coverage. Description adds context by listing values and how omitting gives full spread, enhancing usage guidance beyond 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?

The description clearly states it's an onboarding entry point for new users to learn what Pipeworx can do. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it returns category-bucketed example questions with tool+argument shapes.

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

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

Explicitly says 'Use this FIRST' and explains when to use it (when new to Pipeworx) and when to focus on a topic. Also implies not for answering questions directly, contrasting with meta-tools.

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

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

Discloses that the row is deactivated, not deleted, and historical events remain available via 'recent_alerts'. This goes beyond annotations (which already indicate nondestructive, idempotent mutation). 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 with no filler. First sentence gives main action, second adds behavioral nuance. 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?

For a simple single-parameter, idempotent, nondestructive cancellation, the description covers purpose, ownership constraint, side effects (deactivation), and links to related queries. No output schema needed.

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 parameter fully with description 'Subscription id (uuid) returned by subscribe.' The tool description echoes this without adding new meaning; baseline 3 for 100% 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?

Clearly states 'Cancel a subscription by id' — specific verb 'cancel', resource 'subscription', and method 'by id'. Distinct from siblings 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'), giving clear usage context. Does not mention alternatives but implies when not to use (e.g., others' subscriptions).

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining the internal routing (structured vs grounded pipeline), the verdict types, and the efficiency claim of replacing 4-6 calls. 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 moderately long but well-structured, with examples and clear separation of the two pipelines. It front-loads the purpose and uses concise examples. Every sentence adds value, though it 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?

Given the complexity of claim verification (two pipelines, verdict types, efficiency gains), the description is remarkably complete. It covers input, process, output (verdict categories, evidence with citation, reasoning), and replaces multiple sequential calls. No output schema, but the description sufficiently details return values.

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

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

Schema coverage is 100%. The description adds meaning beyond schema by explaining how 'tolerance_pct' overrides implied tolerance and is used for hallucination detection. It provides helpful usage guidance for the parameter.

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

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

The description uses specific verbs ('validate', 'verify', 'check') with a clear resource ('claim') and provides concrete examples like 'is it true that...' and 'fact check'. It distinguishes this tool from siblings like 'deep_research' or 'ask_pipeworx_grounded' by focusing on claim verification against authoritative sources.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It gives context on the types of claims and the two pipelines. However, it does not explicitly say when not to use or compare to alternatives, though the sibling list shows many different tools.

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