Estat Japan

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive hints. The description adds transparency beyond that by noting the cost implication for Anthropic calls ('you pay Anthropic directly') and the return structure (per-model score, confidence, etc.). 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 three sentences, front-loaded with the main action, then succinctly covering optional API key, return format, and use cases. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description clearly states the return format (per-model score, confidence, signals, raw_response plus combined view). It also covers all parameters and their purposes, making the tool fully understandable for invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model, the purpose of context parameter ('helps disambiguate'), and the cost implication of _apiKey.

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: probing LLMs for knowledge about a business/brand/product/topic and returning a visibility score. It also lists use cases (AI-marketing audits, pre-launch checks) which distinguish it from sibling tools like deep_research or bet_research.

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

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

The description explains when to use the tool (e.g., AI-marketing audits) and how to optionally use the Anthropic model with a BYO key. However, it does not explicitly state when not to use it or compare it to sibling tools, missing some guidance on alternatives.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the tool delegates to other tools, fills arguments automatically, and returns structured data with stable citation URIs. This behavior would not be inferable from the schema or annotations, and nothing contradicts the annotations.

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

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

The description is long but densely informative: a front-loaded preference directive, a clear scope list, concrete examples, and an exclusion all earn their place. No filler or redundancy is present, and the structure leads with the most important instruction.

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 still explains the return format (structured answers with pipeworx:// citation URIs) and the internal routing behavior. It covers scope, trigger phrases, examples, and a key exclusion. The phrase 'START HERE for most questions' also guides the agent toward this tool over close siblings.

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%, and the question parameter plus its five aliases are fully documented in the schema. The description adds usage examples but not additional parameter-level semantics, so the baseline of 3 applies.

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

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

The description states a specific function: it routes a natural-language question to one of 5,798 tools across 1,517 verified sources and returns a structured answer with stable pipeworx:// citations. It also positions the tool as the default starting point ('START HERE for most questions') and explicitly steers away from user-specific data, which differentiates it from siblings like remember/recall.

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

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

It gives explicit when-to-use guidance: questions about current/historical authoritative data, factual queries, and even cases where web search could answer. It also gives when-not-to-use guidance for personalized or user-specific data and names the alternative tools (remember/recall). Concrete trigger phrases and examples further remove ambiguity.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description builds on this by revealing the experimental nature: candidate routing improvements are enabled live when under test, and no candidate is active right now so behavior currently matches ask_pipeworx. It also clarifies fallback semantics ('Falls back to nothing — this IS a full working router'), removing ambiguity about reliability. 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 four dense sentences with no filler, front-loading the key fact that this is a beta variant of ask_pipeworx. The specific current status and fallback behavior each add necessary context. Every sentence earns its place.

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

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

For a single-required-parameter tool with no output schema, the description provides the essential invocation context: identical to ask_pipeworx, same response shape, and current experimental status. It even covers the failure mode ('Falls back to nothing') and the evaluation purpose. An agent has enough to call it correctly.

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

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

The schema already provides descriptions for all parameters, but they are merely aliases for 'question' (e.g., 'Alias for question.'), so coverage is high but shallow. The description adds no detail about the question parameter, only 'same arguments' as ask_pipeworx. Given the 100% schema coverage baseline, this is adequate but not enhanced.

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 this as a beta version of ask_pipeworx with the same universal-routing scope, explicitly restating identical 5,798 tools, arguments, and response shape. It distinguishes itself from the sibling stable ask_pipeworx by describing it as the experimental edge with candidate routing improvements. This gives an agent a precise picture of what the tool does and how it differs.

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 states 'Use it exactly like ask_pipeworx when you want the newest routing,' giving a clear condition for selection. It also contrasts results with the stable router to decide what merges, implying the stable tool is for non-experimental use. It does not explicitly spell out when-not-to-use or mention the grounded sibling, so it is clear but not exhaustive.

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?

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral detail: it guarantees evidence as a verbatim quote, defines refusal modes and their exact reasons, and discloses the extra LLM call cost. No contradiction with annotations exists.

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

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

Every sentence earns its place: purpose, routing behavior, output/refusal structure, usage guidance, and cost tradeoff. The most important differentiator, hallucination resistance, is front-loaded, and the cost comparison is placed at the end as a decision aid. Despite density, it remains scannable.

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 covers the return contract with success and refusal shapes. It also covers use cases, exclusions, cost behavior, and routing semantics, which is complete for a tool with a single required natural-language parameter and strong annotations.

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

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

Schema coverage is 100% and the schema already documents all six alias parameters (q, text, input, query, prompt, question). The description does not need to add parameter details and does not meaningfully go beyond the schema. Baseline 3 is appropriate because the schema carries the full semantic burden.

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 and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from ask_pipeworx by describing the same routing plus a stricter extraction step, and explicitly names the sibling 'ask_pipeworx' as the alternative. An agent can tell exactly what this tool does and how it differs.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also gives a clear when-not-to-use rule with a cost comparison: 'prefer ask_pipeworx for casual lookups.' This is explicit routing against a sibling tool, not merely implied context.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate non-destructive behavior. The description adds far beyond: it details resolution confidence, fan-out logic, cancellation rule parsing, blocking conditions (low confidence, closed markets), wide-spread warnings, and response structure. 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 lengthy but well-structured with clear sections and front-loaded with core purpose. Every sentence provides useful detail, though some verbosity could be trimmed without losing key information. The structure facilitates quick scanning for key facts.

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 data sources, conditional fan-out, resolver logic, safety mechanisms), the description is remarkably complete. It covers response shapes, edge cases (live vs. closed markets, cancellation rules, 429 retries), and even references audit findings. No output schema exists, but the description adequately explains return values.

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

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

The input schema has 100% description coverage, but the description adds critical context for each parameter: market can be slug/URL/question text with examples; depth enum with default explained; include_raw detailed with size consequences. This goes well beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and explicitly distinguishes the tool's scope from siblings by focusing on Polymarket bet research, with specific use cases like 'should I bet on X'.

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

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

The description provides explicit use cases ('Use for should I bet on X...') and extensive guidance on inspecting results (e.g., market_match_confidence, parent_event). It does not explicitly state when not to use the tool or list alternatives, but the context is clear enough for an agent to decide when to invoke. Slightly more explicit exclusionary guidance could push this to a 5.

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, but the description adds rich behavioral context: it explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

Description is reasonably concise given the amount of useful information. Front-loads trigger phrases, then provides technical details. Every sentence adds value, but it could be slightly tighter. Still well-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?

With only 2 parameters, no output schema, and good annotations, the description fully covers what the tool does: data pulled, sorting, citation URIs, and the fact it replaces many sequential lookups. No gaps remain for the agent to use it correctly.

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

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

Schema coverage is 100%, but description adds significant meaning beyond short schema descriptions. It explains that type='company' pulls latest 10-K financials and type='drug' pulls adverse-event counts, approval counts, and clinical trials. It also clarifies values: for companies, tickers/CIKs; for drugs, drug names. This greatly aids parameter selection.

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 performs side-by-side comparison of 2-5 companies or drugs, with trigger phrases like 'compare X and Y', 'X vs Y', and 'head to head'. It distinguishes from siblings by noting it replaces 8-15 sequential single-entity lookups, making the purpose clear and unique.

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

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

Description includes strong guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides examples of when to use (e.g., 'which is bigger', 'rank these companies'). While it doesn't explicitly state when not to use, the guidance is sufficient for correct selection among siblings.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and open-world, so the bar is lower, but the description still adds substantial behavioral context: account requirements, paid depth tier, parallel decomposition, gap recovery, contradictions[] scanning, semantic excerpting, stable fetchable citations, and expected latency. No contradiction with the annotations exists.

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 it is dense with high-value information and is front-loaded with the most operationally important constraint: account requirement and the fallback tool. Every clause adds either a capability, a limitation, a routing rule, or expected output behavior. Slightly sprawling, but the structure and information-to-noise ratio are strong.

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

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

Given the tool has no output schema, the description carries the full burden of explaining what the agent will receive: a findings packet with verbatim evidence, confidence, source, fetched_at, citations, explicit gaps[], contradictions[], and the 'hop' field. It also covers cost/tier, timing, and failure semantics. This is a complete operational picture for a complex tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it maps 'quick/standard/thorough' to hop counts, whether a gap-recovery/contradiction pass runs, and the paid requirement for 'thorough'. It also clarifies that 'question' is meant to be broad/multi-part because decomposition is the point. This goes beyond the bare schema definitions.

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

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

The description states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in one call. It explicitly differentiates itself from siblings by saying 'this is NOT open-web search' and by directing single-lookup users to ask_pipeworx. The decomposition + parallel routing behavior makes the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and explicit when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'). It also names the alternative for unauthenticated users ('If you are not signed in, use ask_pipeworx instead'). This is exceptionally clear 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' No contradictions with annotations, and this extra detail enhances transparency.

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

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

The description is moderately sized and front-loaded with core purpose. It lists multiple domains which adds length but aids clarity. A bit verbose but no redundancies; each sentence adds value. Could be slightly more concise, but overall well-structured.

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

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

Despite no output schema, the description thoroughly explains what the tool returns (names, descriptions, schemas with examples, ready to call). It also covers when to use it. For a discovery tool with this complexity, the description is complete and leaves no key questions unanswered.

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 each parameter is already documented. The description mentions that the tool accepts aliases for query, but this adds no new meaning beyond what the schema provides. Thus, baseline score of 3 is appropriate as description does not significantly enhance parameter 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 the verb 'Find tools' and specifies the resource as 'by describing the data or task.' It distinguishes from siblings by positioning itself as a meta-tool for discovering other tools, which is unique among the sibling list that includes search and data retrieval tools.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context on when to use and even suggests it as a starting point, setting it apart from tools that answer specific queries.

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

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

Goes far beyond the safe read-only annotations: it discloses the full source fan-out, return sections, sources_used/sources_failed semantics, patents soft-failing after the USPTO API sunset, expected-empty FDA results for non-biologics companies, and the GDELT→GNews fallback. 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?

Long but dense and front-loaded: it opens with user phrasing, immediately gives the core directive, then organizes output sections in a scannable semicolon-separated list. Every sentence carries operational value; nothing reads as filler.

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

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

With no output schema, the description appropriately serves as the return contract by enumerating every section and its failure semantics. Combined with the fully described parameters and annotations, an agent has everything needed to invoke this tool correctly and interpret its response.

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 already fully documents both parameters at 100% coverage, including ticker/CIK/name examples, zero-padded CIK, and mutual interchangeability of type values. The description mostly repeats these details and adds only private-company behavior, which is more output semantics than parameter semantics, so baseline 3 is appropriate.

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

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

The description states a clear verb+resource: it builds a full cross-source profile of a US public company in one parallel call, with strong query examples. It differentiates from single-pack SEC/XBRL/news lookups, though it does not name sibling tools like deep_research or compare_entities directly.

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 'ALWAYS PREFER' this over chaining single-pack lookups when the user wants a holistic view, which is strong routing guidance. It also sets expectations for private companies (resolved:false with notes) and clarifies that both type values behave identically.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data and stale context, enhancing understanding of when deletion is appropriate, though no additional behavioral traits beyond annotations are added.

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

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

The description is two sentences, front-loaded with verb and resource, and contains no extraneous information. Every sentence earns its place.

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

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

For a simple deletion tool with one parameter and no output schema, the description is complete. It covers purpose, usage, and pairing with related tools, making it fully adequate 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%, and the description mentions 'by key', which aligns with the schema's 'key' parameter. However, the description does not add significant semantic value beyond what the schema already provides.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key', distinguishing it from siblings like remember and recall.

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

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

It explicitly provides three use cases: stale context, completed task, or clearing sensitive data. It also pairs with remember and recall, giving clear context on when to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds actionable context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown 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?

The description is concise: two sentences capturing purpose, process, and output. Every sentence adds value and is front-loaded with the 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?

With 2 parameters, no output schema, and good annotations, the description explains the output format ('single text blob ready to drop at site-root/llms.txt') and process. Could be considered complete for this simple tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description repeats the purpose of url and references max_links implicitly ('Maximum number of link entries'). No additional semantic value beyond the schema.

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

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

The description clearly states it generates an llms.txt file for a given URL, with specific verb ('generate'), resource ('llms.txt'), and scope ('for any URL'). It distinguishes from sibling tools like ai_visibility_check by focusing on the llms.txt generation task.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing...'). While it lacks explicit alternatives or 'when not to use', the context is clear enough for an agent to decide.

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 communicate read-only, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds only mild context ('stats table', optional filters) and does not contradict the annotations; rate limits or pagination behavior are not disclosed, but the schema covers pagination parameters.

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 one efficient sentence with the core action front-loaded and the optional behavior at the end. Every word earns its place with no fluff or repetition.

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

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

With a rich input schema, examples, an output schema, and safety annotations, the description is mostly complete for invoking the tool correctly. The only notable gap is the lack of explicit routing away from search/get_metadata siblings, but the required stats_data_id and examples make invocation unambiguous.

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 coverage is 100%, so parameters are already documented with meanings and examples. The description adds no extra parameter detail beyond 'dimension codes', which the filter property description already explains.

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 verb and resource ('Fetch observations from a stats table') and mentions optional dimension-code filtering, so an agent understands the core operation. It does not explicitly distinguish itself from siblings like search_stats or get_metadata, which prevents a 5.

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 no when-to-use or when-not-to-use guidance and never references alternative tools. 'Optionally filter by dimension codes' is about invocation, not tool selection, so an agent is left to infer when get_data is preferred over search_stats or get_metadata.

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 read-only, idempotent, and non-destructive; the description adds useful behavioral context by stating it returns dimension definitions and code lists and that it requires _apiKey. This goes beyond what annotations alone communicate without contradicting them.

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

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

Three short sentences deliver the core purpose, the returned content's use, and the authentication requirement with no filler. The most important information is front-loaded, making it easy for an agent to parse quickly.

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 two-parameter metadata lookup tool with a present output schema and safety annotations, the description covers the essential missing context: what the tool returns, why it is useful (get_data filter construction), and the _apiKey requirement. No critical invocation information is absent.

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%: both lang and stats_data_id have descriptions in the schema, so the baseline is 3. The description adds contextual framing around stats_data_id (identifies a specific table) and its relationship to get_data, but it does not add substantial parameter-level detail 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 states a specific verb ('Fetch'), a clear resource ('dimension definitions and code lists for a specific e-Stat statistics table'), and distinguishes this metadata tool from data-retrieval tools like get_data. The mention of 'statsDataId' and its downstream use for get_data makes the tool's role unambiguous.

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

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

The description clearly positions this tool as a prerequisite step for constructing filters for get_data, giving the agent a concrete use context. It does not explicitly state when not to use it or name alternative metadata/catalog tools, but the context is clear enough for 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?

The description reveals important behavior beyond annotations: the endpoint is slow, can exceed its 35s budget, and returns a specific timeout response shape. It also notes the _apiKey requirement, providing operational context annotations do not cover.

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

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

Three sentences with no filler: purpose, key behavioral caveat, and auth requirement. The most important operational warning is front-loaded in the second sentence, and every sentence adds distinct value.

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

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

Given the rich schema, output schema, and annotations, the description covers the essential context: purpose, alternative tool, failure behavior, and authentication. Nothing critical is missing for an agent to call this 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 description coverage is 100%, so the input schema already explains all eight parameters. The description adds little semantic detail beyond labeling the query as a free-text filter, which is already present in the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb ('Browse') and resource ('e-Stat high-level data catalog'), and clarifies the scope as dataset/table groupings with an optional free-text filter. It also distinguishes itself from search_stats, making the tool's purpose unambiguous.

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

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

It explicitly states that search_stats answers 'which Japanese statistics table covers X' faster, giving the agent a clear alternative for lookups while positioning this tool for browsing. It also warns about the timeout risk, which directly informs 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds which fields are returned, and the optional `include_inactive` parameter behavior, supplementing the schema. 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 two sentences with zero wasted words. The first sentence defines purpose and output; the second provides usage context. Perfectly concise and front-loaded.

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

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

Given the tool's simplicity (single optional parameter, no output schema needed), the description covers purpose, return values, and usage. No missing behavioral traits for a list tool.

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

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

Schema coverage is 100%, so the schema already documents the single parameter. The description does not add additional meaning beyond the schema's parameter description, meeting the baseline 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 action ('List'), the resource ('the caller's active subscriptions'), and specifies the returned fields. It implicitly distinguishes from siblings like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

The description explicitly advises when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides practical use cases, though it does not mention when not to use it or alternatives.

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

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

Beyond the sparse annotations (all false hints), the description discloses operational constraints: rate limiting ('Rate-limited to 5 per identifier per day'), zero cost ('Free; doesn't count against your tool-call quota'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later ... to read whether it was fixed and what changed'). It also states that the team reads digests daily, giving the agent a sense of expected 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?

The description is long but front-loaded with the core purpose and logically sequenced: what, when, exclusions, token flow, operational notes. Every sentence adds necessary detail for this feedback tool, though it could be tightened by trimming the duplicated 'Pipeworx connection' explanation. Structure is clear with natural topic transitions.

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 compensates by explaining the return token and how to poll for resolution. It also covers scope, rate limits, costs, and expected response time, making it self-contained for an agent to decide and invoke correctly. The nested context object is clarified as optional, and the use-case examples remove 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?

The input schema has 100% parameter coverage, so the baseline is 3. The description adds value by explaining the token-based follow-up flow with a concrete example (pipeworx_feedback({claim_token:"pwfb_…"})) and tying parameter usage to real scenarios. However, the schema descriptions already cover most parameter semantics, so the increment is modest.

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 action: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly naming the resource (Pipeworx team) and the purpose. It enumerates concrete feedback types (bug, feature, data_gap, praise) and distinguishes itself from siblings by restricting to Pipeworx-served tools, which is essential for differentiation.

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

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

Provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear when-not-to-use exclusion for tools from other MCP servers, plus a practical disambiguation tip ('Pipeworx tool names are the ones this connection lists').

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, open-world, idempotent, non-destructive. Description adds caching (5min-1h), data source (CF analytics), PII absence, and self-aggregating nature. No contradictions.

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

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

Three sentences plus a bullet list. Front-loaded with purpose. Every statement is useful and non-redundant.

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?

Describes return values (top tools, packs, volume) and caching. No output schema, but description compensates. Could mention approximate count limits or ordering, but adequate for a trending tool.

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

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

Single parameter 'window' has full schema coverage. Description adds guidance on interpreting window sizes: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clearly states it returns top tools, packs, and call volume over configurable windows, with three specific use cases. Differentiates from siblings like 'discover_tools' by focusing on trending usage.

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?

Lists three explicit use cases (discovering hot sources, confirming canonical tool, aligning use case). Lacks explicit when-not-to-use or alternative tool names, but 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 indicate read-only, open-world, idempotent behavior. The description adds extensive behavioral context: explains algorithms (monotonicity violations, partition-sum), fill check against live CLOB depth with realizable_edge_pp threshold, semantic anchor with Jaccard similarity, and partition filter for placeholder slugs. 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 lengthy but front-loaded with the core purpose. Every sentence adds value; no fluff. However, it could be slightly more concise by omitting some advanced details that might overwhelm first-time readers. Overall, well-structured 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?

Despite no output schema, the description explains the response structure: opportunities[] with fields and partition_check details. It covers fill check and custom sizing pointers. Completeness is high for a complex tool; only minor omissions like explicit mention of read-only behavior (already covered by annotations).

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

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

Schema coverage is 100% with descriptions. The description adds value beyond schema: explains the difference between event and topic modes, gives examples of slugs and seed questions, and mentions that full Polymarket URLs are accepted. This extra context justifies a score above baseline 3.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' with a specific verb and resource. It distinguishes from sibling tools like polymarket_edges and polymarket_edge_tracker by its unique approach.

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

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

Provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', or 'topic for a themed cross-event scan'. Recommends event mode for specific markets and explains cross-event mode benefits. Also references polymarket_fill_risk for custom sizing.

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

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

The description exhaustively details the three model families, their inner workings (e.g., lognormal barrier, GDELT ratio, partition overround with sport-specific α), output fields (edge_pp_net, kelly_fraction, etc.), caching behavior (1h), and diagnostics. This goes far beyond the basic readOnlyHint annotation, and there is 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 well-structured with clear sections and bullet points, but it is quite long. Some details could be more concise, but the length is justified by the complexity of the tool.

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

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

Given the tool's complexity (multiple models, filters, diagnostics, caching) and the absence of an output schema, the description is remarkably complete. It explains why segments might be empty, what knobs affect behavior, and provides detailed output field descriptions.

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

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

All 9 parameters have descriptions in the schema (100% coverage), and the tool description provides additional clarifications, such as explaining slippage_pp defaults, min_kelly usage, and tradeable-edge knobs. This adds significant meaning beyond the schema itself.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly designed for 'what should I bet on today'. It uses specific verbs ('scan', 'return') and resource 'Polymarket markets', distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description explicitly orients the tool toward the 'what should I bet on today' use case, mentions knobs and tradeable-edge filters, and explains when to adjust parameters (e.g., slippage_pp for thin partitions). It provides clear context for usage, though it does not explicitly list when not to use; however, this is implied by the presence of sibling 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?

The description adds substantial behavioral context beyond annotations: it explains the source (daily snapshots), response structure (tracked, expired, snapshot_dates), data gaps (cache misses), TTL (60-day), and decay computation (daily closes). 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 packed with necessary details. It front-loads the core question and structure (response fields), then covers limits. Every sentence is informative, but could be slightly more structured.

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 data-retrieval tool with no output schema, the description thoroughly explains the response, data gaps, TTL, and decay computation. It provides enough context 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%, so baseline is 3. The description repeats default values for days and window but adds no new semantic details beyond the schema. The 'clamp 2-30' note is from schema, not description.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots. It answers a specific trading question: fresh vs old wide edges. It implicitly distinguishes from sibling polymarket_edges by focusing on time-series trends.

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

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

The description explains when to use the tool (to check edge persistence and decay) and provides context by contrasting fresh vs old edges. However, it does not explicitly state when not to use it or name 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 mark the tool as read-only, idempotent, and not destructive. The description adds significant behavioral context: it walks the order ladder, returns verdicts (clean/degraded/cannot_fill), identifies thin legs, and warns about forced directional risk. No contradictions with annotations.

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

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

The description is well-structured with clear sections (mode selection, parameter defaults, return values) and uses capitalization for emphasis. It is somewhat lengthy but every sentence serves a purpose. A minor reduction in verbosity could improve conciseness, but it 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 no output schema, the description thoroughly explains both single-market and basket return fields: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk. It also covers edge cases and rationale.

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. However, the description adds substantial meaning: it explains the dual-mode semantics (market for single, event for basket), auto-detection of side in basket mode based on partition sum, and different interpretations of size_usd (spend vs proceeds vs settlement notional). This goes far 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 defines the tool as a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with specific verb ('check') and resource ('edge'). It distinguishes from siblings by stating it should be used before acting on polymarket_arbitrage or polymarket_edges signals, and explains two modes (single-market and basket) with detailed outcomes.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why with real-world consequences: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an 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 mark the tool read-only and idempotent, and the description adds extensive non-obvious behavioral context: compatibility codes can be non-empty even when matched_pairs>0, unknown legs are never paired, temporal_alignment null does not imply alignment, fees are gross not net, and pre-mapped does not equal tradeable. No contradiction with annotations.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, fees_note) and front-loads the core purpose. It is quite long and repeats a few points (e.g., the matcher identity and 'in EITHER mode'), so it is not maximally concise, but nearly every sentence conveys operational 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?

With no output schema, the description fully covers the response shape and caveats: per-leg prices, top_spreads_pp, compatibility fields, temporal_alignment semantics, skipped comparison counters, and the fees disclosure. An agent can predict and interpret the result without additional lookup.

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?

Even though schema description coverage is 100%, the description adds real interaction semantics: topic auto-fetches a mapped event, explicit tickers override the topic-mapped side, and both modes run the identical token-overlap matcher. This tells the agent how the parameters relate to each other, which the schema alone does not.

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: computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It also names the two invocation modes, which makes the tool's role unambiguous and distinct from the sibling Polymarket-only analytics tools.

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

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

Provides explicit mode-selection guidance: use topic shortcuts for 10 pre-mapped macros or use explicit tickers for custom pairings, and warns that most pre-mapped topics currently return compatibility_warning. It does not point to sibling alternatives or state when another tool should be preferred, so the differentiation stops short of a full 5.

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

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

Annotations already provide readOnlyHint true and destructiveHint false. Description adds scoping per identifier and pairing with other tools, providing 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?

Two sentences, front-loaded with core action, no wasted words, 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?

Simple tool (1 optional param, no output schema) and description covers retrieval, listing, scoping, and pairing. Sufficiently complete.

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

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

Schema coverage is 100%, so baseline 3. Description repeats schema info (omit key to list) but adds no new parameter meaning.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, distinguishing it from siblings remember and forget.

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

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

Provides explicit context for when to use (look up stored context like ticker, address, notes) and implicitly through pairing with remember/forget. Could explicitly 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?

Annotations declare readOnlyHint=true, but the description states that setting mark_read:true flags events as read, mutating state. This contradicts the readOnlyHint. Without the contradiction, the description adds value by explaining return fields and mark_read behavior, but the conflict is severe.

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 (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, return fields, filtering, mark_read behavior, and alternative access. No wasted words.

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

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

Given 5 parameters, no output schema, and annotations providing safety profile, the description covers the main use case, return structure, and polling behavior. It does not explain unread_only explicitly (though schema does), and error handling is omitted, but overall complete for an alerts-fetching tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds minimal extra context: it mentions filtering by type and since, and explains mark_read's effect on subsequent calls. It does not add meaning for limit or unread_only beyond the schema. Meets baseline for high coverage.

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

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

The description clearly states the tool pulls fired events from subscription feed, specifies key fields (source, citation_uri, raw payload), and mentions filtering capabilities. It distinguishes from siblings like list_subscriptions by focusing on recent alerts. The verb 'pull' and resource 'fired events' are specific.

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

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

Provides guidance on filtering by type and since, and explains the mark_read parameter for state management. Mentions polling and an alternative REST endpoint for scripts/dashboards, helping the agent decide when to use this tool vs. that endpoint. Does not explicitly compare with sibling tools like list_subscriptions, but 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 readOnlyHint, openWorldHint, idempotentHint true. Description adds significant behavioral context: parallel fan-out to multiple sources, fallback logic, and API deprecation notes. 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 a single dense paragraph that efficiently conveys purpose, usage, and edge cases. Front-loaded with examples. Slightly long 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?

Despite no output schema, description precisely states return structure (changes[] grouped by source, total_changes, citation URIs). Covers fallbacks, parameter formats, and sibling differentiation. Complete for a read-only aggregation tool.

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

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

Schema covers 100% of parameters, but description adds crucial details: 'since' accepts ISO or relative shorthand with examples, 'type' only supports 'company', 'value' accepts ticker or CIK. Goes beyond schema basics.

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 provides a change feed for a company in a time window, with concrete examples ('What's new with X', 'latest on Y'). Distinguishes from sibling tool entity_profile by noting when to use the alternative.

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

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

Provides clear guidance on when to use this tool vs entity_profile. Explains the fallback behavior between GDELT and GNews, and notes USTPO soft-failure. Gives preferred default for 'since' parameter (30d or 1m).

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 idempotentHint=true and destructiveHint=false. Description adds value by disclosing scope (by identifier) and retention policies (persistent for authenticated, 24h for anonymous), which are beyond annotation fields. No contradictions.

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

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

One focused paragraph, front-loaded with purpose, no fluff. Every sentence adds value (usage, examples, retention, pairing).

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 params, no output schema), the description covers all necessary aspects: purpose, when to use, behavior, data scope, retention, and related tools. Complete for decision-making.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning by suggesting naming conventions for key ('subject_property', 'target_ticker') and clarifying value type ('any text'). This goes beyond the schema's basic description.

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

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

The description uses a specific verb ('Save data the agent will need to reuse later') and clearly identifies the resource (data scoped by identifier). It distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning 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?

Explicitly states when to use ('when you discover something worth carrying forward'), provides examples, and contrasts with recall and forget. Also clarifies retention rules (authenticated vs anonymous sessions), giving clear usage context.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond that by disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, non-assertion via figi_candidates on ambiguity, and explicit unresolvable identifiers under `unresolved`. This rich behavioral context is exactly what an agent needs beyond the bare hints.

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

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

The description is front-loaded with examples and a clear purpose, but it becomes an extremely dense block with many parenthetical asides and some repetition of the type enum/value examples already present in the schema. Every sentence is informative, but the overall length and nesting are not concise.

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

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

There is no output schema, so the description carries the burden of explaining returned and edge-case behavior. It covers ambiguity handling, unresolved identifiers, source labeling, fallback behavior, and the fact that this replaces 2–3 manual lookups. For a two-parameter tool with these annotations, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: the value parameter gets entity-name-only instructions, an ISIN-to-LEI resolution example, and bond issuer formatting guidance ("NEW YORK ST DORM AUTH" vs. trailing security-class words). These details materially improve the chance a correct value is passed.

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

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

The description states a precise verb+resource: "resolve a user-spoken NAME to the canonical/official identifiers other tools require as input." It also gives many concrete query patterns (ticker, CIK, LEI, RxCUI), which makes the tool's role unmistakable and distinct from siblings like entity_profile or 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?

It gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID," and enumerates supported entity types and input forms. It does not explicitly name alternatives or state when not to use this tool vs. nearby siblings, so it stops just short of a 5.

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

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

Annotations declare idempotent, readOnly, openWorld, and not destructive. The description adds that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity—providing meaningful behavioral context beyond the annotations.

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

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

The description is three sentences long, front-loaded with the core action, followed by process details and a usage example. Every sentence adds value, with no redundancy or fluff.

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

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

Given no output schema, the description adequately describes the return value (ranked list with score, confidence, signal density). It covers purpose, process, output, and use case. It does not mention error handling or prerequisites for using non-default models, but the schema addresses the API key requirement.

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 adds value by clarifying that the first entity in the array is treated as the 'subject' and the rest as competitors, which is not in the schema. This aids correct invocation.

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

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

The description states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces which is most/least recognized. This clearly distinguishes it from single-entity probes like ai_visibility_check and from general comparison tools like compare_entities.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies this is for multi-entity comparison versus single-entity probing, but does not explicitly state when not to use or list alternatives.

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

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

Beyond read-only and idempotent annotations, the description reveals partial failure graceful degradation, potential 5-30s delay for bundlephobia first measurement, and a specific field (sources_failed) to report timeouts. No contradiction with annotations.

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

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

The description is a single paragraph that front-loads the core purpose. It is fairly concise but could be slightly tighter; every sentence provides necessary information.

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

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

Without an output schema, the description thoroughly enumerates the return fields, covers edge cases like partial failures, and provides timing caveats. It is complete for a complex composite tool.

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

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

Schema description coverage is 100%. The description restates what the schema already says about package name, scope acceptance, and version default. It does not add substantive new semantic 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 starts with a specific verb phrase 'composite check' and clearly states the resource (npm package) and scope (license, advisories, bundle size). It distinguishes from siblings by noting that other ecosystems are handled by a different tool.

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

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

Explicit use cases are given ('is X safe / popular / small', 'what does adding lodash cost me') and a clear exclusion ('NPM ecosystem only in v1') with a pointer to alternative tools for other ecosystems.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns IDs and names, providing useful behavioral context beyond annotations without contradiction.

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

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

Two concise sentences: first defines purpose, second provides usage guidance. No redundant words, 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?

The tool is simple with an output schema, so description need not detail return values. It covers what is returned (IDs and names) and how to use them, which is sufficient.

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

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

Input schema has 100% description coverage for all 4 parameters. The description does not add extra parameter details beyond the schema, meeting the baseline 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 it searches e-Stat statistical tables and returns IDs and names, with specific verb and resource. It also distinguishes from sibling tools get_data and get_metadata by directing to use the IDs 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 implies when to use (to find statistical tables) and references get_data/get_metadata as follow-up, but lacks explicit when-not-to-use or contrast with other search tools like deep_research.

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 detail beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that every passage carries character offsets for verification. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is highly concise—three sentences covering purpose, usage, output characteristics, pairing, and technical details. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description adequately explains output format (passages with character offsets and similarity scores) and truncation behavior. It covers all 3 parameters (100% schema coverage), refers to a sibling tool, and provides enough context for proper use.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the 'text' param is already-fetched content, 'query' is a natural-language query, and 'limit' range (1-20) and default (5). This provides context beyond the schema descriptions.

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

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

The description clearly states the tool performs semantic search within a fetched record, not search for records. It uses specific verbs ('search inside') and resources ('record'), and gives concrete examples (SEC 10-K, article, tool result). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description states when to use: 'when the record is too big to cram into the prompt' and explains it saves context. It also mentions pairing with ask_pipeworx_grounded. It does not explicitly list when not to use, 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?

Adds context on auth, type-specific parameters, delivery constraints (phone verification, 10/day cap, webhook auto-disable). However, idempotentHint=true contradicts the description's implication that each call creates a new subscription (returns new id). openWorldHint=true also seems mismatched as the return value is static, though side effects are dynamic.

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

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

Front-loaded with purpose and return type. While dense, the description uses clear categorization (types, delivery) and provides examples. Could benefit from more structured formatting (e.g., bullet points) but remains 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?

Covers the main workflow: auth, subscription types, parameters, delivery channels, and return value. Lacks details on error responses, rate limits beyond SMS, and exact format of the returned subscription id. Given the tool's complexity and no output schema, this is adequate but not exhaustive.

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

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

Schema coverage is 100%, and description significantly expands on each parameter: explains type enums with specific examples (e.g., sec_8k items codes, fred_series series_id), and details delivery fields with validation rules and caveats (webhook signing, SMS cap).

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

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

Clear verb 'Create' and resource 'subscription', with specific purpose 'proactive monitoring subscription to a live-data event stream'. Returns the new subscription id. Distinguishes 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?

Explicitly states requirements (Pipeworx OAuth account, not anonymous/BYO), lists supported types and delivery channels with examples. Implicitly suggests when to use vs other tools like recent_alerts, but does not explicitly compare to 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, openWorldHint, etc. Description adds that it returns exact tool+argument shapes and that it's drawn from a live catalog. 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 informative and well-structured with usage examples, but slightly long. It is front-loaded with purpose 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?

No output schema, but description fully explains what is returned (category-bucketed examples with tool shapes). Covers arguments, usage, and return value 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 is 100%. The description adds context for the optional topic parameter with examples and explains behavior when omitted.

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

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

The description clearly states it is the onboarding entry point for learning what Pipeworx can do, returning category-bucketed example questions. It uses specific verbs and distinguishes itself from siblings like discover_tools and ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions optional topic focusing. Does not explicitly exclude other scenarios but 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?

Discloses that the row is deactivated (not deleted) and historical events remain via recent_alerts, adding context beyond annotations. Ownership enforcement also provided.

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 filler, all information relevant and front-loaded.

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

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

Given simple tool with one parameter and no output schema, description explains purpose, ownership, and deactivation behavior 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 covers 100% of parameters with description. The description adds that id is returned by subscribe, which is minor. 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), implying when not to use. No explicit alternative for canceling others' subscriptions, but sufficient for most cases.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key behavioral semantics: the distinction between 'could_not_verify' (check did not happen, carries verification_error) and 'unsupported' (no source covers it), and the important caller warning that 'could_not_verify' must not be treated as evidence. It also explains the automatic routing between structured SEC/XBRL and grounded pipelines, adding significant 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 detailed and logically structured, front-loaded with purpose and then covering usage, behavior, returns, and caveats. The list of trigger phrases is useful recognition cues, and the important warning about 'could_not_verify' is necessary. It is somewhat long but every sentence serves a purpose for a complex tool; a minor point is that the trigger-phrase enumeration could be trimmed, so not a perfect 5.

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 takes full responsibility for explaining return values (verdict list, citation, reasoning) and failure semantics. It also describes the routing logic and the 'Replaces 4–6 sequential calls' benefit. The description is sufficiently complete for an agent to know what the tool does, what it returns, and how to interpret its results, including edge cases.

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

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

The input schema has 100% coverage, describing 'claim' with examples and 'tolerance_pct' with range, default, and purpose. The tool description adds only a brief mention of 'exact percent-delta math' and the default cap, which is already in the schema. Since the schema fully documents both parameters, the description does not need to compensate, but it also does not add extra meaning beyond what the schema provides.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification against authoritative sources, with explicit trigger phrases ('fact check', 'verify the claim that…', 'true or false'). It specifies the resource (authoritative sources) and the action (verify/judge), making the tool's role distinct from general Q&A or research siblings.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct,' giving a clear use case. It also explains the two-path behavior (SEC EDGAR for company-financial claims, grounded pipeline for all others) and notes it 'Replaces 4–6 sequential calls,' which implies an efficiency advantage. However, it does not explicitly name alternative tools or list when-not-to-use scenarios, so it falls short of a 5.

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