Insee

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

Annotations indicate read-only, idempotent, non-destructive. The description adds that Anthropic probing requires a BYO key and direct payment, which is beyond annotations. 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 well-structured sentences: purpose, key parameters, use cases. No wasted words, front-loaded with main action.

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

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

No output schema, but the description details return format (per-model {score, confidence, signals, raw_response} + combined view). Covers essential 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 coverage is 100%, so baseline 3. The description adds value by explaining the default model and BYO key mechanism, but does not significantly expand 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 uses specific verbs ('probe', 'score') and identifies the resource (LLMs, business/brand/product/topic). It distinguishes from sibling tools by focusing on multi-model visibility scoring, not single answers or comparisons.

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 use cases (AI-marketing audits, pre-launch checks, competitive monitoring). It does not explicitly state when not to use or alternatives, but the context is clear.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent, and the description adds important behavioral detail beyond those hints: it routes across 5,798 tools, fills arguments automatically, and returns structured answers with stable citation URIs. This clarifies the orchestration nature of the tool without contradicting annotations.

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

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

The description is dense and front-loaded: it opens with the key preference and scope, provides examples, and ends with routing alternatives. It is longer than average, but for a tool with six aliases and many sibling alternatives, the length is generally justified. There is minor redundancy between the opening preference and the later 'even if web search could also answer it' clause.

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

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

For a complex routing tool with six alias parameters and no output schema, the description comprehensively covers when to use it, what it returns, citation behavior, example inputs, and when to prefer alternatives. No significant contextual gap remains.

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 each parameter is already documented as a natural-language alias for 'question.' The description adds useful example queries and trigger phrases, but it does not add material parameter-level meaning beyond what the schema already provides.

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

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

The description clearly defines the tool as a question-routing layer for factual, current, or historical data, explicitly distinguishing it from web search and naming alternative sibling tools. It states a specific verb ('routes'), resource ('the right one of 5,798 tools'), and outcome ('returns the structured answer with stable pipeworx:// citation URIs'). This makes the tool's purpose immediately actionable.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH,' lists broad data categories, provides trigger phrases like 'what is' and 'look up,' and supplies concrete example queries. It also names alternatives with clear conditions: use ask_pipeworx_grounded for exact verbatim citations, deep_research for broad/multi-part questions, and notes that ask_pipeworx already handles breaking-news routing.

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

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

Beyond the read-only and idempotent annotations, the description discloses that routing changes live while a candidate is under test, that no candidate is active right now, and that there is no fallback—it is a full working router. This prevents the common beta-tool assumption that it would delegate to the stable version.

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 tool's identity and scope, and each sentence carries useful information: current candidate state, usage guidance, relationship to ask_pipeworx, and no-fallback behavior. The exact retirement date and tool count are slightly more detail than strictly necessary, so it is not perfectly minimal.

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

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

For a complex universal router with no output schema, the description provides the essential operating model: same arguments and response shape as ask_pipeworx, live candidate behavior, and exact current equivalence. It still relies on the agent knowing ask_pipeworx's response shape, since no output details are given—a minor gap.

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

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

Schema description coverage is 100%, with every parameter documented as an alias for 'question' and question itself fully described. The tool description adds no additional parameter semantics, but the schema alone is sufficient here.

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 identifies the tool as a beta version of ask_pipeworx and a 'universal router' over the same 5,798 tools, with the same arguments and response shape. It clearly distinguishes it from the stable sibling by explaining the live candidate routing improvements and the experimental edge.

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

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

It explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It also states that with no candidate active, the tool currently matches ask_pipeworx exactly, removing ambiguity about current behavior.

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

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

The description goes well beyond the annotations, disclosing the exact success return shape, refusal reasons, evidence as verbatim quote, and the added cost of one LLM call. It also makes clear the tool will refuse rather than hallucinate when data doesn't directly answer, which is critical behavioral context for an agent. No contradiction with the readOnly, openWorld, idempotent, or non-destructive annotations.

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

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

The description is dense but every sentence earns its place: mode, mechanism, return contract, refusal contract, use cases, and cost-based alternative routing. The key differentiator is front-loaded, and the guidance for when to prefer the sibling comes at the end without burying the primary 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?

The tool is complex enough to warrant the detailed behavior disclosure, and the description fully covers the return contract, failure modes, usage boundaries, and relationship to ask_pipeworx. Despite the absence of an output schema, the agent is well-equipped to invoke the tool and interpret its response correctly.

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

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

Schema description coverage is 100%, so the schema already documents the single meaningful parameter and its aliases. The description adds no parameter-level detail of its own, but none is needed since the schema is complete. 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 names a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and clearly contrasts it with ask_pipeworx while describing the mechanism: route, fill arguments, fetch, then extract only from the tool result. This makes its purpose and differentiation from siblings immediately obvious.

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

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

It explicitly states when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete examples. It also provides an exclusion: prefer ask_pipeworx for casual lookups because this costs an extra LLM call. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idlempotentHint=true, destructiveHint=false. The description vastly expands with detailed behavioral traits: resolver contract (market_match_confidence, alternatives, suggestions), parent_event extractor, news fields with fallback logic, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread warnings, and resolution-rule risk parsing. This comprehensive disclosure far exceeds the annotation baseline.

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

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

The description is very long (multiple paragraphs) and could be more concise. However, it is front-loaded with the core purpose and uses section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) for structure. Some details are repeated (e.g., low_confidence_match explained twice). While informative, it could be trimmed without losing clarity.

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

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

Given the complexity (classifiers, fan-out, response shapes, safety mechanisms, and edge cases), the description is remarkably complete. It covers input variants, output structure, error states (low confidence, closed markets, wide spreads), and even resolution-rule risk. Without an output schema, the verbal descriptions of response shapes are sufficiently detailed for an agent to understand what to expect.

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

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

Schema coverage is 100% for all three parameters. The description adds significant value beyond the schema: it clarifies the 'market' parameter accepts slugs, URLs, or question text; explains the 'depth' enum (quick vs thorough) with default; and elaborates on 'include_raw' with purpose and size trade-offs. This goes beyond the schema's basic descriptions.

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

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

The description immediately states the verb 'Research' and the resource 'a Polymarket bet'. It distinguishes this tool from siblings like polymarket_arbitrage and polymarket_edges by detailing its unique capability: pulling Pipeworx data in one call with market resolution, classification, and fan-out across categories.

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 use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides concrete examples across multiple categories (BTC, Fed, Hormuz, etc.). While it does not explicitly state when not to use, the sibling tools provide alternatives, and the usage context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds valuable behavioral details: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting by primary metric. 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 front-loaded with trigger phrases and efficiently conveys purpose and usage. While slightly longer, every sentence adds value (examples, data sources, advantages). No redundancy or filler.

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

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

Despite lacking an output schema, the description explains the return format (paired data + citation URIs), sorting behavior, and the benefit of replacing multiple lookups. It provides sufficient context for an AI agent to understand input, behavior, and output expectations.

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 beyond the schema by explaining how 'values' should be formatted (tickers/CIKs for company, names for drug) and that max is 5 items. It also clarifies the data returned per type, enhancing semantic understanding.

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

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

The description provides multiple example queries ('compare X and Y', 'X vs Y', 'which is bigger') and clearly states it performs side-by-side comparisons of 2-5 entities. It explicitly distinguishes from sequential single-pack lookups and sibling tools like entity_profile, making the purpose unambiguous.

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

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

The description explicitly states WHEN to use ('always prefer over sequential single-pack lookups when comparing entities') and provides alternative behavior for type='company' vs 'drug'. It gives clear usage context and implicitly excludes single-entity queries, guiding 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 only cover readOnly/openWorld/idempotent/non-destructive hints. The description adds substantial behavioral context: it never invents gaps[], returns contradictions[] for standard/thorough, includes a hop field and fetchable citation_uri only when source emits one, semantically excerpts large records, and gives latency expectations. This far exceeds what annotations provide.

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

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

The description is long but every chunk earns its place: auth gating, purpose, usage comparison, depth semantics, output format, citation guarantees, and latency. It is well front-loaded with the most critical constraints. It is slightly verbose and could tighten the depth/second-hop wording, but it remains structured and readable.

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

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

For a complex tool with no output schema, the description fully compensates: it explains the findings packet, gaps[], contradictions[], hop/citation_uri behavior, excerpting strategy, auth requirements, paid tier, and expected latency. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, but the description meaningfully expands on both parameters: it explains the depth enum values in terms of facets, hops, gap-recovery, and contradictions, and clarifies that the question can be broad or multi-part. This adds actionable semantics beyond the bare 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?

States a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call. Clearly distinguishes itself from open-web search and from ask_pipeworx for single lookups, and names its niche as broad/multi-part questions.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and directly says 'For a single lookup use ask_pipeworx.' It also gates usage on account sign-in and routes unsigned-in users to ask_pipeworx instead. No ambiguity remains about selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by stating that the tool returns top-N relevant tools with schemas and examples, and that each result is ready to call directly. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the main purpose. It includes multiple sentences but each adds value: purpose, use cases, return behavior, and guidance. It could be slightly more concise, but the structure supports 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 what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' Combined with the exhaustive parameter documentation in the schema, the agent has complete information to use the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add substantial meaning beyond the schema; it provides example queries but the schema already describes parameters as natural language descriptions. The description's examples are supplementary but not necessary.

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

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

The description clearly states 'Find tools by describing the data or task' and specifies the tool's purpose of browsing, searching, and discovering tools. It lists numerous example domains (SEC filings, financials, etc.) and explains that it returns top-N tools with schemas ready to call, distinguishing it from other tools.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also enumerates specific use cases (e.g., 'Use when you need to browse...') but does not explicitly state when not to use it or mention alternatives.

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

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

The description richly discloses behavior well beyond annotations: it lists the exact fan-out sources, specifies what each return section contains, explains that missing sections mean real 'no data' via sources_used/sources_failed, and documents the private-company resolved:false failure mode. This is exceptional transparency for a tool with no output schema.

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

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

The description is long but front-loaded with examples and the core purpose. The large source/return-list sentence is dense and necessary given no output schema, but there is minor redundancy—particularly the note that type and value are interchangeable, which repeats schema information.

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

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

Given there is no output schema, this description compensates thoroughly: it enumerates all major return fields, gives the source list, clarifies empty-result semantics, explains the name-resolution behavior, and covers the private-company edge case. An agent has what it needs to call the tool correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving concrete examples ('AAPL', '0000320193', 'Moderna'), confirming ticker/CIK/name are all valid, and explaining name resolution via SEC EDGAR. Still, much of this is already stated in the param descriptions, so it does not warrant a 5.

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 gives a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call,' reinforced by concrete user-phrase examples. It also distinguishes this tool from chaining single-purpose SEC/XBRL/news lookups, so an agent can tell it apart from narrower alternatives.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a clear when-to-use rule with an alternative approach named. It also clarifies the acceptable input types and the special private-company handling, so no inference is needed.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms destructive action but adds no additional behavioral context (e.g., no mention of undo, permissions, or impact).

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 sentence is the core action. Efficiently conveys purpose, usage, and pairing. No superfluous content.

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

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

Given simple 1-param tool with no output schema and clear annotations, description covers purpose, usage, and pairing. Adequate 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% with description for 'key' parameter. Description adds no extra meaning beyond schema's 'Memory key to delete'. Baseline 3 is appropriate.

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

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

Description clearly states verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from sibling tools 'remember' and 'recall' by specifying deletion action.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also advises pairing with remember and recall, providing clear context for tool 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral details: it fetches the page, extracts title/description/links, and outputs markdown. No contradictions.

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

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

Description is concise and front-loaded with purpose, method, and output format. Every sentence is meaningful, though slightly verbose.

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

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

Given no output schema, the description explains output format. It covers end-to-end process and use cases, making it complete for a tool with clear annotations and parameters.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minimal extra beyond schema, like examples and default/max for max_links, but does not significantly enhance understanding.

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

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

Description clearly states it generates a production-ready llms.txt for any URL for AI crawlers. It specifies the verb, resource, and output format, and distinguishes itself from related sibling tools like ai_visibility_check.

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

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

Description lists concrete use cases: getting client sites indexed, drafting llms.txt, auditing competitors. It provides context for when to use, though it does not explicitly mention when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds value by listing the returned data fields (legal name, NAF/APE code, address, etc.) without contradicting annotations.

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

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

Two sentences, no wasted words. First sentence states purpose and resource, second gives usage guidance and parameter format. Front-loaded with the action.

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

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

For a simple lookup tool with high schema and annotation coverage, the description is complete. It lists the fields returned, compensating for lack of output schema. Minor omission of error conditions but acceptable.

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% with descriptions for both parameters, including example values. The description adds context by specifying 'SIREN (legal unit) or SIRET (establishment)', which provides slightly more semantic meaning than the schema alone.

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

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

The description clearly states it looks up French companies/establishments in the official SIRENE registry, with specific verb 'Look up' and resource. It distinguishes from web search by explicitly saying 'PREFER OVER WEB SEARCH', and the sibling tools include other lookup tools making this differentiation valuable.

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 over web search for specific queries like 'who is French company X' and lists attributes it can provide. It implies when to use and gives identifier format guidance, but does not contrast with sibling tools like entity_profile or resolve_entity.

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, idempotentHint, and destructiveHint. Description adds return field details and clarifies scope (caller's active subscriptions). No contradictions.

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

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

Two sentences: first states action and return fields, second gives usage guidance. No redundant information, 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?

Description is complete for a simple list tool with one optional parameter. Annotations cover behavioral traits, description covers return values and usage context.

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

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

Schema covers 100% of parameters with description for include_inactive. Description does not add further parameter meaning; 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 specifies the verb 'List' and resource 'subscriptions', scoped to 'caller's active'. It lists return fields, clearly distinguishing 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?

Explicit guidance to use for reviewing monitoring before adding more or finding an id to cancel. While it doesn't name specific sibling tools, the context implies them.

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

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

The annotations are all false and provide no safety signals, but the description compensates by disclosing behavioral traits: rate-limited to 5 per day, free, doesn't count against tool-call quota, team reads digests daily, and filing without an account returns a claim_token. There is 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 multi-sentence but every clause earns its place: scope restriction, use cases, claim_token workflow, rate limit, cost, and response handling. It is front-loaded with purpose and compresses complex operational details into a compact, scannable form.

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

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

Even without an output schema, the description fully conveys the feedback loop: what happens after filing (claim_token, daily review, roadmap impact) and how to follow up. It also addresses the cross-server edge case, making the description complete for a tool with this level of complexity.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful guidance for `message` (1-2 sentences typical, don't paste the end-user prompt) and `claim_token` (pass with no other arguments), but the schema already documents `type` and `context` thoroughly. This extra enrichment warrants one point above baseline.

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

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

The description opens with a specific verb ('Tell the Pipeworx team') and explicitly enumerates the types of feedback accepted (broken, missing, needs to exist). It clearly distinguishes this tool from all sibling research/visibility tools by positioning it as the dedicated feedback channel for Pipeworx.

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

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

It explicitly specifies when to use the tool (bug, feature/data_gap, praise) and when not to use it (if the tool is from a different MCP server, file elsewhere instead). It also explains the claim_token follow-up workflow, giving the agent clear decision paths for both filing and retrieving feedback status.

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

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

The description adds valuable information beyond the annotations, such as caching behavior (5min-1h depending on window), data source (CF analytics-engine), and the fact that no PII is included. The annotations already indicate readOnly and idempotent, so this complements well.

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

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

The description is front-loaded with a hook ('What other AI agents are calling on Pipeworx right now') and efficiently covers purpose, return values, and use cases. It is slightly verbose but every sentence contributes useful 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?

Despite no output schema, the description mentions the three return components (top tools, top packs, total call volume) and explains caching and data source. This is sufficient for a simple read-only tool, though explicitly stating the return structure would improve completeness.

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

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

The input schema already has a full description for the 'window' parameter, making the schema coverage 100%. The tool description adds context about caching behavior tied to window choice, which adds value beyond the schema's documentation.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)'. It also lists specific use cases. However, it does not explicitly differentiate from sibling tools like 'discover_tools', which could have a similar purpose.

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

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

The description provides three use cases (discovering hot data sources, confirming popular tool, aligning use case) and explains the data derivation and caching. While it gives clear context for when to use, it lacks explicit 'when not to use' or direct comparison to alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds substantial behavioral context: explains monotonicity checks, partition filter with placeholder slugs, semantic anchor (Jaccard similarity), fill check with depth analysis. 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 lengthy but every sentence adds value for a complex tool. It front-loads the purpose, then explains modes, then technical details. Could be slightly more concise but effective for the complexity.

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

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

Given the tool's complexity, no output schema, and rich input, the description is thorough. It covers all input modes, response structure (opportunities, partition_check, fill check), and conditions for no trade. Also references polymarket_fill_risk for custom sizing. Complete for agent invocation.

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

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

Schema description coverage is 100% with both parameters described. The description goes far beyond by explaining the two modes, providing example slugs, detailing how cross-event mode works, and linking to fill check. This adds significant value beyond the schema alone.

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

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

Describes tool as finding arbitrage opportunities via monotonicity violations and partition-sum checks. Verb 'Find', resource 'Polymarket', and method clearly stated. Distinguishes from siblings like polymarket_edges and polymarket_fill_risk by being the arbitrage detection tool.

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

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

Explicit guidance on when to call with no args (trending_scan), when to use 'event' (specific market), and when to use 'topic' (cross-event). Recommends 'event' mode for specific markets. Also warns when not to trade (realizable_edge_pp <= 0). No alternatives to other tools needed due to distinct purpose.

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 elaborates extensively beyond annotations, detailing model families, edge calculation, caching (1h KV-level), diagnostics for empty results, and warnings about Fed bets and edge already priced in. Annotations (readOnlyHint, idempotentHint) are consistent; no contradiction.

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

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

The description is very comprehensive but verbose, containing substantial detail that could be truncated. It is front-loaded with the primary purpose, but the length may reduce quick skimmability for an agent.

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 fully specifies the response structure (by_segment, fed_candidates, _diagnostics) and opportunity fields (edge_pp_net, kelly_fraction, etc.). It covers all user concerns for correct invocation and interpretation.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reiterates and slightly expands on parameters (e.g., slippage_pp rationale), but adds marginal value beyond the schema. Baseline 3 is appropriate.

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

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

Description explicitly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker. The verb-resource pairing is clear and specific.

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

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

Targeted use case ('what should I bet on today') is clearly stated, and tradeable-edge knobs (min_liquidity, max_spread_pp) provide filtering guidance. While no explicit when-not-to-use is given, the description offers ample context for appropriate invocation.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint are true, and destructiveHint is false. The description adds behavioral context: snapshots are written on cache-miss, gaps mean no scan that day, history depth is bounded by 60-day TTL, and decay numbers come from daily closes. This adds value 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 lengthy but packed with useful information. It is front-loaded with the main purpose. While every sentence serves a purpose, it could be slightly more concise. Overall, it is well-structured 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?

Given the lack of output schema, the description thoroughly explains the return structure (tracked[], expired[], snapshot_dates[]) and covers limits and interpretation. It provides defaults and constraints for the two optional parameters, making it fairly 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%, so the description does not need to add much. It explains 'days' as lookback with default 14 and clamp 2-30, and 'window' as snapshot family with default '1wk'. This adds marginal context beyond the schema, justifying a baseline score of 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: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about how long an edge has existed and whether it is shrinking. The tool is clearly distinguished from its sibling 'polymarket_edges' by focusing on time-series analysis.

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

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

The description provides context on when to use the tool by contrasting a fresh wide edge with a 3-week-old one. It explains the snapshot family and limits. However, it does not explicitly state when not to use this tool or mention alternative tools beyond implicit differentiation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds context: returns verdict (clean|degraded|cannot_fill), thin_legs, forced_directional_risk, and explains risk of partial fills. No contradiction.

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

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

Description is lengthy but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence adds value given tool complexity. Slightly verbose but justified.

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

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

No output schema, but description fully explains return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). Covers both modes completely.

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

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

Schema coverage 100%, but description adds meaning beyond schema: default values (side default buy_yes, size_usd default 1000), clamping (10–1,000,000), interpretation of size_usd for buys vs sells, basket mode default side auto from partition sum.

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

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

Clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. Explicitly distinguishes two modes (single-market, basket) and states when to use it relative to siblings (polymarket_arbitrage, polymarket_edges).

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also provides exclusions: warns about partial basket fills converting arb into unhedged 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds substantial non-annotated behavior: pairing_unverified is set whenever pairs are returned, null temporal_alignment means 'could not compute' rather than aligned, unknown legs are never paired, and fees are gross rather than net tradeable edge. No contradiction exists between the annotations and the description.

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

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

The description is long and dense, but it is well-structured with clear thematic sections: purpose, modes, response, safety fields, compatibility codes, skipped counts, and fee disclosure. Every sentence adds meaningful safety or usage information, and the core purpose is front-loaded. It is not pithy, but the tool's complexity and absence of an output schema make the thoroughness appropriate.

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 effectively documents the response shape, including leg-by-leg prices, matched spread entries, top_spreads_pp, compatibility codes, temporal alignment status, skipped-leg counters, and the standing fee caveat. An agent has enough information to select the tool, invoke it correctly in either mode, and interpret safety-critical results.

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

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

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds useful semantic context beyond the schema, such as that both modes run the identical token-overlap matcher and that explicit ticker/slug fields override the topic-mapped side. This justifies slightly above 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 opening sentence states a precise object and scope: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It then names the two modes and the response contents, clearly differentiating this from polymorphic polymarket-only sibling tools. This is more than a tautology or vague paraphrase of the title.

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 concrete mode-selection guidance: topic shortcuts for pre-mapped macros versus explicit kalshi_event_ticker and polymarket_event_slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning and that pre-mapped is not tradeable. It does not explicitly name sibling alternatives or state when not to use the tool, but the context is clear enough.

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

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

Annotations already declare the tool as read-only (readOnlyHint=true), non-destructive, and idempotent. The description adds valuable behavioral context: scoping 'to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual behavior (retrieve by key vs list all). No contradictions with annotations. The description enhances transparency 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 exceptionally concise: three sentences covering purpose, use cases, and scope. Every sentence is essential and information-dense with no repetition or fluff. Front-loaded with the core action, it is highly efficient.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description provides sufficient context: retrieval mode, listing mode, scoping, and pairing with remember/forget. It could mention what happens if the key doesn't exist, but for most use cases the description is complete enough for correct invocation.

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

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

Schema coverage is 100% with the 'key' parameter well-described in the schema. The description reinforces that omitting the key lists all keys, but this is already in the schema description ('omit to list all keys'). Since the description adds little beyond the schema, and baseline is 3 for high coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if no key is provided. It uses specific verbs like 'Retrieve' and 'list' and identifies the resource as 'value' or 'keys'. It distinguishes from siblings 'remember' and 'forget' by pairing them, making the purpose unambiguous.

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

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

The description explicitly tells when to use the tool: 'to look up context the agent stored earlier' and provides concrete examples like 'target ticker, an address, prior research notes'. It also frames usage as an alternative to re-deriving context. While it doesn't explicitly state when not to use it, the pairing with 'remember' and 'forget' gives implicit usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: mark_read behavior, return fields (source, citation_uri, payload), and polling suitability. 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?

Three sentences, front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

Given no output schema, the description explains return fields, filtering, mark_read, polling, and alternative access. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning: example value for type ('sec_8k'), ISO timestamp format for since, and explanation of mark_read's effect. This goes beyond the schema descriptions.

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

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

The description clearly states the verb 'pull' and resource 'fired events from your subscription feed'. While it doesn't explicitly differentiate from siblings, the purpose is specific and unambiguous.

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

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

The description mentions that polling works fine and provides an alternative endpoint for scripts/dashboards, but lacks explicit guidance on when not to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds valuable behavioral traits: parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return format. No contradictions.

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

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

Description is comprehensive yet front-loaded with core purpose and examples. Every sentence adds value—covers data sources, fallbacks, parameter hints, and sibling differentiation. No redundancy.

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

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

Given the tool's complexity (multi-source, fallbacks, soft-fail, relative dates) and no output schema, the description fully prepares the agent. Provides return structure, citation URIs, and links to sibling tool. Missing nothing essential.

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

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

Schema description coverage is 100%. Description enhances semantics by explaining 'since' format with examples (ISO date and relative shorthand like '30d'), and clarifying 'value' can be ticker or CIK. Adds context 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 provides a 'change feed for a company in the last N days/weeks/months' with specific verb ('change feed') and resource ('company'). It distinguishes from sibling 'entity_profile' by contrasting dynamic vs static 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?

Explicitly lists example use cases ('what's new with X', 'latest on Y') and directs to alternative 'entity_profile' for static profiles. Does not exhaustively describe when not to use, but the context is clear.

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

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

The description adds context beyond annotations: it explains scoping by identifier, persistence differences between authenticated and anonymous sessions (24 hours), and that it stores key-value pairs. 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 concise (3 sentences) and front-loaded: the first sentence gives the core purpose, and subsequent sentences add necessary details with 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 the tool's simplicity (2 required string params, no output schema), the description is nearly complete. However, it does not explicitly state what happens when a key already exists (overwrite? error?), though idempotentHint=true implies overwrite. Minor gap.

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

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

The schema already provides descriptions for both parameters (100% coverage). The description adds practical context about what kinds of values to store (e.g., resolved ticker, target address) but does not add significant technical constraints beyond the schema.

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

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

The description clearly states the verb 'save' and the resource 'data the agent will need to reuse later', and distinguishes itself from siblings 'recall' and 'forget' by explicitly mentioning pairing with them.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and mentions alternatives ('Pair with recall to retrieve later, forget to delete').

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

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

Annotations already mark this as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral detail: it cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI are unavailable, returns explicit `unresolved` results, and returns `figi_candidates` when names are ambiguous. 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 long, but dense and purposeful. Purpose and trigger are front-loaded, followed by detailed type-specific behavior and a critical input caveat. Some phrasing, such as the opening quoted examples, is slightly repetitive but still useful for recognizing user intent.

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

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

For a complex tool with no output schema, the description covers return content (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), source labelling, unresolved and ambiguous cases, accepted input forms, and failure degradation. An agent has enough information to invoke it correctly and interpret its results.

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

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

While the input schema already covers both parameters, the description adds high-value semantics: pass only the entity name, use the issuer exactly as printed for bonds, avoid trailing security-class words, accept ticker/CIK/ISIN/name for companies, and accept brand or generic names for drugs. This goes far beyond the schema descriptions.

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

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

The description begins with concrete user-phrase examples and clearly states the tool's function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also positions it relative to downstream tools ('Use FIRST whenever you have a name but need an ID'), making its purpose and differentiation clear.

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

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

The description gives a clear trigger condition ('Use FIRST whenever you have a name but need an ID') and spells out accepted input forms per entity type. It does not explicitly name an alternative tool to use instead in other cases, but the context is strong enough to guide 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 indicate read-only, idempotent, and non-destructive behavior. Description adds that it probes via ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity, providing useful behavioral context beyond annotations.

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

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

Description is two sentences: first states the main purpose, second provides usage context and return format. No unnecessary words; front-loaded with key information.

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

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

With no output schema, the description adequately states return structure (ranked list with score, confidence, signal density). It references sibling tool ai_visibility_check for underlying method. Lacks error handling or rate limit info but is sufficient for agent selection.

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

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

Input schema has 100% description coverage. Description adds that the first entity is treated as the subject and the rest as competitors, clarifying the array semantics beyond the schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities, specifying it probes each with ai_visibility_check and ranks results. This differentiates it from sibling tools like single-entity ai_visibility_check or generic compare_entities.

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

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

Provides context for competitive AI-marketing audits and notes the first entity is the subject. While it suggests when to use, it does not explicitly exclude alternatives or state when not to use.

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

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

Description adds significant behavioral context beyond annotations: mentions partial failures, timing on bundlephobia first measurement (5-30s), and graceful degradation with sources_failed list. 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?

Well-structured with purpose first, then usage, then behavioral notes. Could be slightly more concise, but every sentence adds value.

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

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

Covers all aspects: composite nature, data sources, return structure (summary, advisories, links, versions), ecosystem limitation, and failure behavior. No output schema, so description adequately explains expected output.

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

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

Schema coverage is 100%, so description adds marginal semantics. Clarifies that scoped packages are accepted and version defaults to latest, but these are already in the schema descriptions.

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

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

Clearly states the tool is a composite check for adding an npm package, combining license, advisories, version history, and bundle size from multiple sources. Distinguishes from siblings by specifying the NPM ecosystem and the fan-out nature.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also notes non-NPM ecosystems are handled by a different tool (deps.dev:version).

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging, and the return format (passages with offsets and scores). 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?

Three well-structured sentences: first states purpose, second gives usage scenario, third provides technical details. No redundant information, highly efficient.

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

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

Despite no output schema, the description fully explains what the tool returns (passages with offsets and scores) and includes technical specifics (model, window, cap). It also ties into sibling tool workflow, making it fully self-contained for an agent.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds some context (limit default 5, query examples) but does not significantly enhance meaning beyond what the schema already provides. 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 'Semantic search INSIDE a fetched record' with specific examples like SEC 10-K, and distinguishes from sibling tools by explaining when to use it versus ask_pipeworx_grounded. The verb 'search' and resource 'text inside a record' are precise.

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 mentions pairing with ask_pipeworx_grounded as an alternative. This provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: it mentions the OAuth requirement, phone verification, SMS caps, and webhook signing/auto-disable. Annotations already indicate readOnlyHint=false, so this is consistent and adds value.

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 a clear front-loaded purpose statement followed by organized details on types and delivery. Every sentence provides essential information without redundancy.

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

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

Given the tool's complexity (multiple types, nested parameters, delivery channels, prerequisites), the description is thorough. It covers requirements, constraints, and examples. No output schema exists, but the return value is mentioned.

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

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

Schema coverage is 100%, but the description enhances understanding with concrete examples for each type (e.g., sec_8k items, polymarket_edge topic) and clarifies delivery behavior (email template, SMS verification, webhook HMAC). This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the return value ('Returns the new subscription id'), and the tool is clearly differentiated from siblings like list_subscriptions 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 provides extensive context on when to use this tool, including requirements (Pipeworx OAuth account), supported types, and delivery channels. While it does not explicitly compare to siblings, the prerequisites and constraints are well-explained.

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, open-world. Description adds that the tool returns category-bucketed example questions with tool+argument shapes, and can be filtered by topic. No contradictions.

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

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

The description is detailed but well-structured, front-loading the core purpose and listing supported topics. Could be slightly shortened without losing clarity, but remains effective.

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

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

Given the single optional parameter and no output schema, the description fully covers when to use, what it returns, and how to customize the output. It is self-contained and leaves no ambiguity.

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

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

Schema coverage is 100% for the single parameter 'topic'. Description adds concrete examples ('finance', 'pharma', 'betting') and explains the effect of omitting vs providing the argument, adding value beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for 'What can I ask Pipeworx?' and lists alternative phrasings. It distinguishes from siblings like ask_pipeworx by explicitly positioning it as the first tool to use when unknown.

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 instruction: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains when to pass the optional topic argument. Lacks explicit when-not scenarios but context is very clear.

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

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

Discloses that the operation is a deactivation, not deletion, and that historical events remain accessible via 'recent_alerts'. Annotations already indicate non-destructive (destructiveHint=false) and idempotent (idempotentHint=true); the description adds concrete 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 concise sentences: first states the action and required parameter, second provides critical behavioral details. 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 one-parameter tool with no output schema, the description fully covers purpose, required parameter, ownership constraint, and the non-destructive nature, connecting to related tools like 'recent_alerts'.

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 mentions 'by id', but does not add semantic value beyond what the schema's 'id' description already provides ('Subscription id (uuid) returned by subscribe'). Baseline 3 applies.

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

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

Description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' (creation) and 'list_subscriptions' (listing) by specifying ownership enforcement and deactivation semantics.

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

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

Provides guidance on ownership restriction ('only cancel your own subscriptions') and the effect of deactivation, implying it should be used when the user wants to stop receiving alerts but retain history. Lacks explicit comparison to alternatives like 'unsubscribe' vs 'delete'.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description goes well beyond by disclosing crucial behavioral semantics: the distinction between could_not_verify (verification error, not evidence) and unsupported (no source coverage), the verdict taxonomy, and the fact that it replaces 4–6 sequential calls. This prevents misinterpretation of results and is genuinely useful for callers.

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: trigger phrases, usage guidance, routing logic, return values, and critical caveats. It front-loads the most important info and uses clear formatting, making it scannable despite its length.

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

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

Given there is no output schema, the description must convey return semantics, and it does thoroughly: verdicts, evidence citation, reasoning, and the very important warning about could_not_verify. It also explains how the tool handles different claim types, making it fully actionable for a complex verification task.

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 solid parameter descriptions, so the baseline is 3. The description adds meaningful context: tolerance_pct overrides the claimed wording, its default and cap behavior, and examples of valid claims. This goes beyond schema descriptions, especially for tolerance semantics.

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

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

The description opens with concrete natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…'), then states the core function: natural-language claim verification against authoritative sources. It explicitly distinguishes the structured SEC EDGAR/XBRL fast path from the grounded pipeline for any other claim, clearly separating this tool from siblings.

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

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

It gives an explicit directive: 'Use whenever the agent needs to check whether something a user said is factually correct,' and explains the two routing paths based on claim type. It doesn't name sibling tools as alternatives or say when to prefer deep_research, but the description strongly implies this is the single entry point for claim verification.

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