Ipify

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

Description adds: default model (Workers AI free), need for API key to use Anthropic (with cost implication), returns per-model data. These go beyond annotation flags, which already indicate read-only/idempotent. 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: first states core action and output, second adds optional detail, third lists use cases. Concise and front-loaded.

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

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

Explains return structure (per-model and combined) and use cases. Lacks details on error handling or rate limits, but given safe annotations and simple parameter set, it's adequate.

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

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

With 100% schema coverage, the description's additional context (default model, payment note) is helpful but not essential. Schema already covers each parameter well.

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

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

Clearly states it probes LLMs and scores visibility per model, with default and optional models, and lists use cases. Distinguishes from sibling tools by focusing on multi-model AI visibility scoring.

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

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

Provides explicit use-case examples (AI-marketing audits, pre-launch brand checks, competitive monitoring), but does not compare to sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: that it routes to one of 5,564 tools and returns stable citation URIs. It doesn't discuss rate limits or auth needs, but given strong annotations, the added behavioral context is substantial.

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 front-loaded with key usage guidance, and every sentence adds value. It is slightly longer but warrants the length to cover when/why to use and alternatives. Could be slightly tighter, but 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 6 parameters (all aliases for one question field), no output schema, and complex routing to 5,564 tools, the description explains what the tool does, when to use it, and example queries. It doesn't detail the citation format or response structure, but the output is inherently varied by source. Explanation is sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds examples of questions, the natural language alias list, and explanation of how the tool interprets the parameter (routes to sources, fills arguments). This goes beyond the schema's basic description of 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 clearly states that the tool routes questions to the appropriate source among thousands, providing structured answers with citations. It specifies the verb 'ask' and resource 'Pipeworx', and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says to prefer this tool over web search, provides examples of when to use it (all factual queries), and tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions).

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-mutating, open-world behavior. The description adds significant behavioral context: it is a full working router (not a fallback), it is the 'experimental edge' for routing improvements, and it currently has no active candidate, so it behaves identically to ask_pipeworx. This goes beyond the 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 a single paragraph of five sentences, each adding essential information: first sentence defines the tool, second gives the routing purpose, third explains current state, fourth gives usage guidance, fifth clarifies it is a full router. No wasted words; front-loaded with the key identity ('Beta version').

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 high schema coverage (100%), the presence of clear annotations, and the lack of an output schema (so no obligation to document returns), the description provides complete context: what the tool does, its current state, how it relates to the stable version, and how to use it. The complexity is moderate (router with many aliases), and the description covers all 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%, with all 6 parameters being aliases for 'question' and described clearly in the schema. The description does not add per-parameter detail beyond what the schema provides, but since coverage is complete, a baseline of 3 is appropriate. The description earns a 4 because it adds useful high-level context about how the parameters work (accepts many aliases, natural language) and ties the parameter behavior to the tool's overall routing purpose.

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 is a beta version of ask_pipeworx, identifies it as an identical universal router with the same tools and behavior, and explains its experimental nature. It distinguishes itself from siblings by emphasizing it is the 'newest routing' candidate, while noting that currently it matches ask_pipeworx exactly. This provides a specific verb ('ask' plus 'beta'), resource ('5,564 tools'), and current status.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains the context of candidate routing improvements and directly states that no candidate is active right now (retired on 2026-07-26). It also clarifies what happens with results: they are compared against the stable router to decide what merges. This fully guides 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?

Adds significant behavioral context beyond annotations: describes extraction process (picks tool, fetches, extracts from tool result only), return structure with evidence and refusal reasons, and cost tradeoff (one extra LLM call). Does not contradict annotations; all are consistent.

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?

Approximately 6 sentences, front-loaded with purpose and key constraints, followed by usage guidance and return format. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully specifies the return format (success and failure cases). Combined with annotations covering safety, the description is complete for a complex tool with 6 parameters and nuanced 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 description coverage is 100% with all 6 parameters described as aliases for the question. Description does not add parameter-level detail beyond the schema, but the high coverage justifies baseline 3.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers only from tool results, with explicit return format and refusal reasons. It distinguishes from the sibling ask_pipeworx by noting the additional LLM call and evidence guarantee.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts, legal claims, medical lookups. Also advises preferring ask_pipeworx for casual lookups, providing clear decision criteria.

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

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

The description goes far beyond annotations, detailing resolution logic, classifier fan-out, response shapes, safety short-circuits, and resolution-rule risk. It explains low-confidence behavior, closed market handling, and tradeability notes, providing comprehensive behavioral transparency.

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

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

The description is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and bolded key terms, but it is lengthy. Every sentence adds value, but conciseness is slightly compromised by the exhaustive detail.

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

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

Despite no output schema, the description fully covers response shapes, edge cases, and safety mechanisms. It addresses complex scenarios like low-confidence matches, closed markets, and wide spreads, ensuring agents have complete context for 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?

With 100% schema coverage, baseline is 3. The description adds significant value by explaining that 'market' accepts slug/URL/question text, 'depth' controls evidence sources, and 'include_raw' affects payload size. Examples and detailed context make parameter usage clear.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It provides concrete examples and distinguishes itself from sibling tools like polymarket_edges by focusing on one-call research for betting decisions.

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 recommends use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also implies alternatives through the sibling tool list and the detailed fan-out scenarios.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich behavioral details: it specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, sorts results by primary metric, and includes citation URIs. No contradictions with annotations.

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

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

The description is well-structured with front-loaded query patterns and detailed behavior, but it is slightly verbose with repetitive emphasis on terms like 'largest/most/biggest'. Every sentence adds value, but minor trimming could improve conciseness.

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

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

The description explains return values (paired data + citation URIs) and sorting behavior, but it lacks explicit structure of the paired data and does not name the primary metric for each type. Given the absence of an output schema, these minor gaps reduce completeness slightly.

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 input schema has 100% coverage with descriptions, the tool description adds significant meaning beyond the schema. It explains what each 'type' value retrieves (10-K data vs. drug stats) and provides concrete examples for the 'values' parameter (e.g., tickers, drug names), enhancing 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?

The description uses specific verbs like 'compare', 'side-by-side comparison', and 'rank' to clearly define the tool's purpose. It explicitly distinguishes itself from sequential single-pack lookups by stating 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', which differentiates it from sibling tools like 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?

The description provides clear guidance on when to use the tool, including example queries and the recommendation to use it over sequential lookups. However, it does not explicitly state when not to use it (e.g., for single entity lookups), leaving a minor gap in usage exclusions.

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

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

Discloses behavioral traits beyond annotations: requires account, paid plan for 'thorough', decomposes questions, parallel execution, returns verbatim evidence with gaps[], contradictions[] for deeper depths, large records semantically excerpted not truncated, and expected latency 15-90s. Annotations already mark it as read-only and open-world, which the description reinforces. Minor deduction: does not explicitly state that access to the 5,564 tools implies no external web search.

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 critical prerequisites (account required, sign-in link). Every sentence adds distinct value: sign-in alternative, tool scope, output format, depth options, citation semantics, latency expectations. Slightly long (multiple clauses) but justified by complexity. Could split authentication note from main flow 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?

Thoroughly covers what the tool does, when to use it vs alternatives, behavioral details (parallel execution, gap recovery, contradictions, semantic excerpts), latency expectations, and output structure. No output schema exists, so the description must explain return format (findings packet, gaps[], contradictions[], citation_uri), which it does explicitly. The 1462 sources, 5,564 tools, and hop mechanics leave no significant ambiguity for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, providing clear enum descriptions for depth. The description adds rich semantic context: explains the research process, output structure (findings packet with hop, citation_uri, gaps[], contradictions[]), and how depth levels behave (quick=3 facets single hop, standard=3 with gap recovery, thorough=6 with iterative chasing). Adds nuance for depth that the schema's enum descriptions lack. Minor gap: the 'question' parameter's natural language nature is already covered by 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 uses a specific verb ('research') and resource ('Pipeworx's 1462 STRUCTURED data sources'). It clearly distinguishes itself from sibling tools like 'ask_pipeworx' (single lookup not multi-source research) and calls out when to use alternatives for news/breaking topics.

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: 'Best for broad/multi-part questions over structured data'. Provides explicit when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Names alternatives: 'use ask_pipeworx instead' for sign-in issues, and distinguishes from 'bet_research', 'compare_entities', etc.

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 valuable detail: it returns top-N tools with full input schemas and curated examples, ready to call directly. This goes beyond annotations by explaining the return format and immediate usability.

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 yet information-dense. It front-loads the core purpose, lists use cases, and details return format. Every sentence serves a purpose, and there is no wasted text.

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

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

The description adequately covers what the tool returns (names, descriptions, schemas, examples) and when to use it. Without an output schema, the description fills most gaps, though specific pagination or error behavior is omitted. For a simple discovery tool, this is sufficiently complete.

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

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

With 100% schema description coverage, the baseline is 3. The description adds minimal value: it mentions the query parameter is natural language and gives examples, but the schema already provides descriptions and aliases. No substantial enhancement beyond what schema offers.

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 tools by describing data/task, with a specific verb 'Find' and resource 'tools'. It distinguishes from siblings by listing many example domains and noting it's for browsing/discovery, which is unique among the sibling set.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells when to use it and implicitly when not to (for a single answer).

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 details fault-tolerant behavior (e.g., USPTO patents API soft-fails due to sunset), data sources used, and return fields, adding significant context beyond annotations which already declare the tool as read-only, idempotent, and 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?

Description is moderately long but well-structured: starts with usage examples, then preference statement, then details of what is returned and limitations. Every sentence adds value, though could be slightly tightened.

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

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

Given no output schema, the description thoroughly lists all return components (CIK, filings with URIs, fundamentals, patents, news, LEI) and caveats (patent API sunset). Combined with schema and annotations, the overall definition is very 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 description adds practical guidance: explains that type currently only accepts 'company', and value must be a ticker or zero-padded CIK (names not supported), which is helpful beyond the schema's property descriptions.

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

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

Description clearly states the tool provides a holistic profile of a US public company via one parallel call, with examples like 'Tell me about X'. It distinguishes from sibling tools such as resolve_entity by explicitly stating to use that when only a name is available.

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 recommends preferring this tool over chaining multiple single-source lookups for holistic views, and advises using resolve_entity first if only a name is provided, not a ticker or 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 and idempotentHint=true. Description reinforces destructive nature but adds little new behavioral context beyond 'clear sensitive data'.

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

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

Two concise sentences, front-loaded with purpose and efficient 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?

For a simple single-parameter delete tool, the description fully covers purpose, usage, and pairing, with 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 100% of parameters with a description for 'key'. Description adds no additional semantics beyond the schema, meeting 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?

Description clearly states the tool deletes a memory by key, with a specific verb (delete) and resource (memory). It is distinguished from siblings like 'remember' and 'recall'.

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 (stale context, task done, clear sensitive data) and pairs with related tools, providing clear context for selection.

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 process details (fetches page, extracts title/description/key links) and output format (single text blob). 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 two sentences plus a bulleted use case list. It is efficient and front-loaded with the core purpose. No extraneous information.

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

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

With 2 parameters and no output schema, the description covers the output (single text blob) and overall process. It lacks error handling or prerequisites, but for a straightforward generation tool, this is adequate.

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 fully documented in the schema. The description does not add additional parameter details beyond the schema, but it reinforces the overall purpose. 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 generates a production-ready llms.txt file for any URL. It specifies the target audience (AI crawlers) and the output format, distinguishing it from sibling tools which are mostly research or scanning tools. This is specific and unique.

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

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

The description explicitly lists three use cases (getting client site indexed, drafting for own project, auditing competitor). It does not state when not to use or mention alternatives, but given the unique function and read-only nature, this is sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds no behavioral details beyond the return value, which is acceptable given 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 extremely concise (5 words), front-loaded with the key information, and every word is necessary.

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 parameters and rich annotations, the description fully informs the agent about the tool's output. The presence of an output schema further reduces the need for detail.

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?

No parameters exist, and schema description coverage is 100%. The description does not need to add parameter info, aligning with the baseline score of 4 for zero-parameter tools.

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 returns the caller's IPv4 (gateway egress IP), clearly distinguishing it from sibling tool 'ipv6'.

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 usage when the agent needs the caller's public IPv4 address. It does not explicitly state when to use versus alternatives, but the sibling 'ipv6' provides a clear contrast.

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 behavioral context beyond annotations: it returns the caller's egress IP with IPv6 primary and IPv4 fallback. Annotations already indicate read-only, idempotent, open-world behavior, and description aligns 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?

Single sentence of 6 words with no redundancy. Front-loaded and efficient.

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

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

For a parameterless tool with an output schema, the description is sufficient. No additional context 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?

No parameters exist, so schema coverage is 100%. The description does not need to add parameter information. Baseline for zero parameters is 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?

Description clearly states it returns the caller's IPv6 address with IPv4 fallback. It implicitly distinguishes from the sibling 'ipv4' tool by mentioning fallback, but lacks explicit 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?

No guidance on when to use this tool versus alternatives like 'ipv4'. The context hints at purpose but does not explicitly state when to prefer one over the other.

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, so the safety profile is clear. The description adds that by default only active subscriptions are listed and includes parameter description, but no additional behavioral traits 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?

Two concise sentences: first states purpose and output fields, second gives 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?

For a simple list tool with one optional parameter and no output schema, the description specifies return fields and usage context. Annotations cover safety. Complete for the complexity level.

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 description of the single parameter. The description does not add further 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 'List the caller's active subscriptions' with specific verb and resource, and lists the returned fields. It differentiates from sibling tools 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 advises using this tool to review existing subscriptions before adding more or to find an id to cancel, providing practical context for when to use it.

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

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

The description discloses extensive behavioral details beyond annotations: filing returns a claim_token when no account is present, passing the token reads the status, rate-limiting to 5 per identifier per day, free usage not counting against quota, and that the team reads digests daily. While annotations indicate readOnlyHint=false, the description accurately characterizes it as a non-destructive feedback submission, adding significant operational context without contradiction.

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

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

The description is relatively long but every sentence earns its place: it covers purpose, use cases, exclusions, token workflow, rate limits, and quota. Information is front-loaded with the core purpose and progressively adds operational details. There is no fluff or redundancy; the length is justified by the tool's nuanced behavior.

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

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

The tool has no output schema, so the description correctly explains return behavior: 'Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed.' It also fully addresses context (which tools/packs), rate limits, and the distinction from other servers. For a feedback tool with this complexity, the description is complete enough for reliable 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 already 100% with detailed parameter descriptions, so baseline is 3. The description adds meaningful usage guidance beyond the schema: it instructs not to paste end-user prompts, describes the claim_token round-trip workflow, and clarifies the message format (1-2 sentences typical). This significantly enhances the agent's ability to compose correct inputs, exceeding the baseline.

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

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

The description states exactly what the tool does: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This is a specific verb+resource (send feedback to Pipeworx team) and clearly distinguishes from sibling tools like ask_pipeworx by focusing on reporting issues rather than querying. The boundary that it is ONLY for tools served by this Pipeworx connection further disambiguates it from other MCP servers.

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 criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion and alternative: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance with alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds that data is self-aggregating, derived from CF analytics-engine, no PII, and cached 5min-1h, providing meaningful 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?

The description is concise: two sentences plus a bullet list of use cases. Information is front-loaded with the return value, then use cases, then technical details. No redundant sentences.

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

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

The description covers purpose, use cases, data source, and caching. Without an output schema, it mentions return items (top tools, top packs, total call volume). Could be slightly more detailed about output shape, but sufficient for a simple 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?

The single parameter 'window' has full schema coverage (enum, description). The description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states clearly that it returns top tools, top packs, and total call volume over a specified window. It distinguishes itself from siblings like discover_tools by focusing on trending data and specific use cases.

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 listed (discovering hot data, confirming canonical tool, aligning use case). Cache behavior is noted. However, no explicit when-not-to-use or sibling comparisons are provided.

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 no destructiveHint. The description adds critical behavioral details: the fill check using live CLOB depth, the semantic anchor with Jaccard similarity threshold, partition filter for placeholder slugs, and the response structure. 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 thorough but verbose, including internal details like Jaccard thresholds and placeholder fraction percentages that may not be essential for selection. It is front-loaded with key information but could be more concise without losing guidance.

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

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

The description covers all necessary aspects: modes, parameters, internal logic, response format, and fill check. Without an output schema, it adequately describes return values. It provides complete context for an agent to understand usage and limitations.

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 both parameters with descriptions (100% coverage), so baseline is 3. The description adds significant context: for 'event' it explains the partition check and monotonicity checks; for 'topic' it explains cross-event scanning and similarity filtering. This extra meaning justifies a 4.

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

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

The description clearly states that the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes three modes: no-args trending scan, single-event mode via 'event' parameter, and cross-event mode via 'topic' parameter. This specificity differentiates it from sibling tools like 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?

Explicit guidance is provided for each parameter: 'event (recommended for a specific market)', 'topic (for cross-event scanning)', and default behavior without arguments. It also advises when not to trade (realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching (1h at KV level), model family details, edge calculations, slippage handling, and diagnostics for empty segments. This goes well beyond the annotations.

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

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

The description is well-structured with bolding and sectioning (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.) and front-loads the purpose. It is dense with information but could be slightly more concise; some parts repeat concepts (e.g., edge calculation).

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 (9 parameters, no output schema), the description is remarkably complete. It covers edge calculation, model families, response structure, diagnostic fields, caching, and tradeable-edge knobs. No critical information is missing 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?

With 100% schema coverage, the baseline is 3, but the description adds significant context beyond the schema. For example, it explains why slippage_pp defaults to 0.3 (zero fees but bid/ask depth), why min_partition_leg_kelly exists (since min_kelly doesn't filter partitions), and provides thresholds for min_liquidity and max_spread_pp.

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 to find opportunities where Pipeworx data disagrees with market price, explicitly positioning it as a 'what should I bet on today' tool. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on disagreement with internal 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 explains when to use the tool (discover opportunities) and provides detailed knobs and filters. It mentions that Fed bets are excluded from ranking with a rationale. However, it does not explicitly contrast with other sibling tools, such as when to use polymarket_arbitrage instead.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds rich behavioral context: it reads from snapshots, computes trends and decay, returns expired opportunities with lifespan, explains data gaps on cache-miss days, and details the signed nature of edge_pp_net. No contradiction with annotations.

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

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

The description is somewhat long but well-structured: first sentence states purpose, then details response fields with clear formatting, and ends with limitations. Every sentence adds value, though some could be tightened. The structure aids 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 no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their meanings. It covers data limitations (TTL, snapshot gaps) and provides enough context for an agent to understand the tool's behavior. No missing critical 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 coverage is 100%, but the description adds meaning: explains days as lookback with defaults and clamping, window as snapshot family with defaults, and describes how these affect the returned data (e.g., number of snapshots). It also details the response structure, which 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge longevity and shrinkage. It distinguishes from siblings like polymarket_edges by focusing on historical trend vs current snapshot.

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 this tool (to understand edge history and decay) and provides context about fresh vs old edges. It doesn't explicitly state when not to use or list alternatives, but the purpose is clear enough. Implicitly, polymarket_edges is the alternative for current data.

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 behavior. The description adds value by detailing the check against live order-book depth, ladder walking, and the specific outputs (top_of_book, vwap_fill_price, slippage_pp, etc.). It also discloses behavioral traits like forced directional risk and the dominant loss mode.

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 (about 150 words) but every sentence is purposeful. It uses bold caps for modes and clear separators, which aids readability. Minor improvement could be using bullet points for return fields, but the current structure is acceptably organized and front-loaded with the core purpose.

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

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

Given the complexity (two modes, multiple return values), the description is complete. It explains both modes, lists key return fields, and covers critical failure modes (thin legs, forced directional risk). No output schema exists, so the description must explain return values, which it does adequately. The warning about partial fills is crucial and well-provided.

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

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

Schema coverage is 100%, so parameters are already described. The description adds context beyond the schema: explains how side defaults differ in modes, clarifies size_usd interpretation for single-market vs basket, and details the differences between 'market' and 'event' parameters. This additional context enhances understanding but the schema already does most of the work.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly separates itself from sibling tools by advising to use it before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround on thin books is not capturable) and warns about the risk of partial basket fills converting arb into a directional position.

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

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

The description extensively details behavioral traits beyond annotations: compatibility_warning conditions, temporal_alignment, skipped cross types, and the nature of the spread calculation. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds significant transparency, especially regarding non-tradeable cases.

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 modes, then provides detailed safety fields and caveats. While lengthy, nearly every sentence adds value; minor redundancy in the safety field explanations could be tightened.

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

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

Given no output schema, the description covers response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal_alignment). It addresses complex edge cases like non-equivalent bet shapes and temporal mismatches, making it sufficiently complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the topic parameter's list and that explicit tickers override topic mapping. It also clarifies the interplay between parameters (exclusive vs override).

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 it computes cross-venue spreads between Kalshi and Polymarket, specifying two modes (topic shortcuts and explicit tickers) and response contents. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use topic mode vs explicit mode, and warns that real spreads are rarer than the shortcut list suggests via compatibility_warning. It does not explicitly state when not to use the tool, but provides clear context for decision-making.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds that the tool is scoped to an identifier and that omitting the key changes behavior to listing all keys. While no contradictions exist, the description does not disclose return format, error handling (e.g., missing key), or pagination for listing, which would enhance transparency.

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

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

Four sentences, front-loaded with the primary purpose and immediate usage. Every sentence adds unique value: primary action, usage context, scoping, and pairing with siblings. 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?

The description adequately covers retrieval and listing, but without an output schema, it should explain the return format (e.g., what the value looks like, how keys are listed) and error cases (key not found). The examples in the schema help, but the description itself is incomplete for a simple tool with no output schema.

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

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

The schema has 100% coverage for a single optional string parameter. The description adds critical meaning: omitting the key lists all keys, while providing it retrieves a specific value. This goes beyond the schema's property description ('Memory key to retrieve (omit to list all keys)') by framing it in the context of the tool's dual behavior.

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

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

The description clearly states the tool retrieves a value by key or lists all keys if omitted. 'Retrieve' and 'list' are specific verbs, and the resource ('value previously saved via remember' / 'saved keys') is unambiguous. This distinguishes it from its siblings 'remember' (save) and 'forget' (delete).

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 this tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It provides concrete examples (target ticker, address, research notes) and mentions scoping by identifier. It explicitly pairs with 'remember' and 'forget', though it does not provide 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds that mark_read flags events as read to affect subsequent calls, and confirms polling is safe, complementing the 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?

The description is a single paragraph of 4-5 sentences, front-loading the core purpose and adding details in a logical order. Every sentence is informative and concise.

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

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

With no output schema, the description covers key return fields (source, citation_uri, payload). It addresses all parameters, polling behavior, and provides an alternative access method, making it sufficient 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 has 100% coverage with descriptions, but the tool description adds examples (e.g., 'sec_8k' for type, ISO timestamp for since) and explains the effect of mark_read, enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves fired events from a subscription feed, specifies the key fields returned (source, citation_uri, payload), and distinguishes it from other tools by focusing on alerts feed. It 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 filtering options (type, since) and explains the mark_read parameter for read tracking. It also mentions polling suitability and an alternative HTTP endpoint for scripts/dashboards, giving good 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?

The description goes beyond annotations by detailing the parallel data sources (SEC EDGAR, GDELT/GNews, USPTO), fallback logic, potential soft-fail, and output structure (changes grouped by source, total_changes count, citation URIs). This provides rich behavioral context.

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

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

The description is front-loaded with example queries and structured to provide essential information efficiently. While it is somewhat verbose with multiple examples, 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?

Despite lacking an output schema, the description fully explains the return format. All parameters are documented, and the tool's behavior (sources, fallbacks, soft-fail) is thoroughly described. The reference to 'entity_profile' provides clear contextual distinction.

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

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

With 100% schema description coverage, the description enhances parameter understanding: it explains the 'since' parameter with ISO date and relative shorthand examples, 'value' with ticker or CIK, and 'type' as only accepting 'company'. This adds meaningful usage context.

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

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

The description clearly states the tool's purpose: providing a change feed for a company in recent days/weeks/months via a single parallel call. It includes multiple example queries and explicitly distinguishes from the 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?

The description provides explicit guidance on when to use this tool (for recent changes) and when to use 'entity_profile' instead. It also details fallback behavior between GDELT and GNews, and notes the USPTO soft-fail condition.

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

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

Annotations already indicate idempotent and non-destructive. Description adds valuable context: key-value scoped by identifier, persistent vs 24-hour retention based on authentication. 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 efficient sentences front-loading purpose, then usage, then storage details. No wasted words.

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

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

Covers purpose, usage, storage scope, and mentions related tools. No output schema, but return value is implicit (likely nothing or success indicator). Could mention overwrite behavior for same key, but idempotentHint implies safe.

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

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

Schema coverage is 100% with clear descriptions for key and value. Description adds usage examples but doesn't provide new meaning beyond what the schema already offers.

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 saves data for reuse across conversations/sessions, gives concrete examples (resolved ticker, target address, user preference), and names sibling tools (recall, forget) for 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?

Explicitly says when to use ('when you discover something worth carrying forward') and why ('so you don't have to look it up again'). Mentions pairing with recall and forget, but doesn't specify when not to use (e.g., storing sensitive info).

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, and non-destructive behavior, but the description goes far beyond them: IT explains source-labelled identifiers, explicit `unresolved` output, graceful degradation when GLEIF/OpenFIGI are unavailable, internal cascading lookups, and ISIN-to-LEI mapping. This is rich behavioral context.

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

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

The description is front-loaded with example queries and all content is relevant, with no wasted sentences. However, it is a single dense block of text with many parenthetical asides; better paragraph breaks and bullet-like structure would improve readability and scanability.

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 return contents (CIK, ticker, LEI, FIGI, RxCUI, unresolved identifiers) and behavioral edge cases (source labels, graceful degradation, internal cascading). It is sufficiently complete for the tool's complexity and the information a model would need.

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 helpful descriptions, but the tool description adds substantial meaning: accepted aliases for company values (ticker, CIK, ISIN, name), brand vs generic examples for drugs, and type-specific resolution behavior. This clearly elevates the baseline for schema-covered parameters.

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

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

The description opens with explicit query examples and states the core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from sibling tools by naming supported types and outputs (CIK, LEI, ticker, RxCUI) and by saying to use it 'FIRST whenever you have a name but need an ID.'

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID,' and it enumerates accepted input forms for both company and drug types. However, it does not name specific sibling alternatives or state when not to use this tool, so exclusion guidance is incomplete.

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 readOnlyHint etc. Description adds behavioral details: probes each entity with `ai_visibility_check`, ranks by score, and returns specific fields (score, confidence, signal density). 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?

Thorough yet concise: 3 sentences plus a parenthetical example. Every sentence adds unique value, no 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?

Given no output schema, description lists key return fields. Parameter count is 4 with 1 required, and annotations cover safety/lifecycle. Misses explicit limits (e.g., max 8 entities) but sufficient for agent decision.

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

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

Schema coverage is 100%. Description adds meaning: explains that first entity in `entities` is treated as 'subject' for narrative, and that omitting `models` defaults to 'workers-ai', saving token usage. This goes beyond schema descriptions.

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

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

The description clearly states the verb 'compare' and 'scan', the resource 'AI visibility across multiple entities', and contrasts with sibling `ai_visibility_check` by emphasizing side-by-side comparison and ranking.

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

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

Provides explicit use-case context ('competitive AI-marketing audits') and an example query. However, does not explicitly state when not to use or list alternatives beyond the sibling contrast.

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 valuable behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia may take 5-30s on first measurement, and sources_failed will list timeouts. Annotations already indicate readOnly, openWorld, idempotent, and 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?

Description is front-loaded with purpose and efficient, but slightly long (4 sentences). All sentences provide necessary information; no waste.

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

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

Given complexity (multi-source, no output schema), description covers scope, fallbacks, example prompts, and lists output fields. However, output format details are inferred; some agents might need more explicit structure.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds minimal extra info beyond schema (e.g., version defaults to latest). No additional constraints or formats explained.

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

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

Description explicitly states the tool is a composite check for evaluating npm packages, combining multiple data sources (deps.dev and bundlephobia). Clearly distinguishes from siblings by specifying scope (NPM only in v1) and directing other ecosystems to deps.dev:version.

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 triggers: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also mentions limitations and alternatives for other ecosystems.

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 internal mechanics: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' Also mentions output includes offsets for verification. No contradiction with annotations.

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

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

Efficient paragraph front-loaded with purpose, each sentence adding value (usage, technical details, pairing). No wasted words.

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

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

Covers inputs, constraints, output format (top-N passages with offsets and scores), and pairing advice. Despite no output schema, description is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with example queries and clarifies text size limit. Enhances understanding beyond schema.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article, long tool result). It distinguishes from siblings like ask_pipeworx_grounded by noting when the record is too large for the prompt.

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 the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear when-to/not-to-use guidance and alternative 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent. The description adds rich detail: subscription ID return, account limitations, type-specific parameter structures, delivery channel behaviors (webhook signing secret, failure handling), and always-on feed. 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 well-structured: main purpose first, then type enumeration, then delivery details. Almost every sentence adds value; minor wordiness (e.g., parenthetical explanations) could be tightened 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 the complexity (3 params, nested objects, no output schema), the description covers types, parameters, delivery options, constraints, and what is returned. It omits how to retrieve feed events (via recent_alerts or GET endpoint) but that is partially covered by sibling tools.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema. It provides concrete examples for each type's params, explains required vs optional fields in delivery, and clarifies constraints like phone verification and SMS cap.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from siblings (list_subscriptions, unsubscribe) by focusing on creation and enumerating supported types and delivery channels.

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

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

The description specifies prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel constraints (e.g., SMS 10/day cap, webhook auto-disable). It lacks explicit when-not-to-use guidance but provides sufficient context for appropriate selection.

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 safe behavior (readOnlyHint, idempotentHint, etc.). The description adds specific details about the return format: category-bucketed example questions with exact tool+argument shapes, drawn from the live catalog. It also explains the default behavior (full spread) and topic filtering. 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 comprehensive but somewhat verbose, including many common queries in the first sentence. It is front-loaded with the purpose and usage guidance. While it could be more terse, every sentence adds value for onboarding. Minor reduction possible.

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 optional parameter, no output schema), the description provides complete context: what it returns, how to call it, when to use it, and a full list of categories. No gaps remain for agent decision-making.

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

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

Schema coverage is 100% with a clear parameter description listing all allowed values. The description repeats this information and adds context about usage, but adds minimal semantic value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that this tool returns example questions about what Pipeworx can do, organized by category, and explicitly positions it as the onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_tools by stating its purpose as the first tool to use.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and contrasts with alternatives like ask_pipeworx, entity_profile, compare_entities. It also explains the effect of omitting vs providing the topic parameter.

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

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

Annotations already indicate idempotent( true ) and not destructive( false ). The description adds beyond annotations by clarifying ownership enforcement, that cancellation is a deactivation rather than deletion, and that historical events remain available via 'recent_alerts'. This provides meaningful behavioral context.

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

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

Two sentences with all essential information front-loaded. No superfluous words; every sentence adds value: first states core action, second adds constraints and side effects.

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), the description fully covers purpose, constraints, side effects, and even references a related sibling tool ('recent_alerts') for follow-up actions.

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 does not add any extra meaning beyond what the schema's property description ('Subscription id (uuid) returned by subscribe.') already provides. The description mentions 'by id' but that is already implied.

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 'Cancel a subscription by id.' It uses a specific verb ('cancel') and resource ('subscription'), and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation and soft-deletion 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 states ownership enforcement ('only cancel your own subscriptions') and explains that the row is deactivated, not deleted, with history still accessible via 'recent_alerts'. This provides clear context on when to use and what happens after, though it doesn't mention explicit alternatives for other users' 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?

Despite annotations already marking read-only/idempotent behavior, the description adds substantial detail: the SEC EDGAR/XBRL fast path, the grounded pipeline fallback, the full verdict list, and the critical warning that could_not_verify means the check did not happen and is not evidence. This is far 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?

The description is dense but every sentence earns its place. It opens with natural-language examples, then covers when to use, the two routing paths, return values, important caveats, and efficiency—all organized with clear highlighting for critical warnings.

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

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

Given no output schema, the description thoroughly explains return values (verdict, actual value, citation, reasoning) and edge-case semantics (could_not_verify, unsupported). This makes it self-contained for an agent to invoke and interpret results 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 schema already provides detailed descriptions for both parameters (100% coverage), and the tool description adds extra context about how the claim is routed (financial vs. other) and the exact percent-delta math used for tolerance_pct. This adds value beyond the schema without repeating it.

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

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

The description clearly states what the tool does: natural-language claim verification against authoritative sources, with example phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling Q&A tools by describing the specific verdict output and the two execution paths.

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 it ('Use whenever the agent needs to check whether something a user said is factually correct') and explains the routing for financial vs. other claims. However, it does not name alternative tools or give explicit when-not-to-use scenarios, so it lacks a full 5.

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