Data Paris

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already convey safety profile. Description adds useful behavioral context: it returns per-model score/confidence/signals/raw_response + combined view, and explains that passing _apiKey enables Anthropic probing with direct costs. 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?

Four sentences, front-loaded with main action and return format. Every sentence adds meaningful detail without repetition or fluff. Highly concise yet informative.

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 covers return format (per-model object + combined view). It explains key parameters and usage scenarios. Minor gap: lacks detail on 'signals' or how scores are computed, but acceptable for most use 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?

Schema covers all 4 parameters with descriptions (100% coverage). Description adds value by explaining default model, free usage for workers-ai, and cost implication of _apiKey. This goes beyond schema and helps agent understand parameter semantics better.

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 probes LLMs for knowledge about an entity and returns visibility scores (0-100). It names specific use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and distinguishes from sibling tools like scan_competitor_ai_presence and ask_pipeworx by focusing on scoring visibility across multiple models.

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

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

Description explains when to use: for AI-marketing audits and brand checks. It provides context on model selection (free default vs. BYO Anthropic key). While it doesn't explicitly list 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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: it is an auto-routing layer over many tools, fills arguments automatically, and returns cited structured answers, which is useful for setting agent expectations.

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 appropriately front-loaded with the key preference statement, followed by concrete domains, trigger phrases, and examples. Some redundancy exists between 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and the final sentence is slightly unclear, but the overall structure supports quick comprehension.

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

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

For a tool with one required natural-language parameter and no output schema, the description is generally complete: it covers what to ask, when to prefer it, what it does internally, and what kind of output to expect. It could be more explicit about the exact response format and the relationship to its sibling variants, but it is sufficient for initial 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?

The schema already documents the single required parameter 'question' and five aliases with 100% coverage. The description adds example questions but does not need to describe parameters further since the schema fully covers them.

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 core function: it routes a natural-language question to an appropriate data tool, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It is distinctive from a plain web search, but it does not explicitly differentiate itself from sibling tools like ask_pipeworx_grounded or ask_pipeworx_beta.

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 strong when-to-use guidance: prefer over web search for factual/current/historical data, with concrete categories, trigger phrases, and examples. It lacks explicit when-not-to-use guidance relative to the sibling tools, so it stops short of full routing clarity.

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 establish this as read-only, idempotent, and non-destructive. The description adds valuable context beyond that: no candidate routing improvement is currently active, it currently matches ask_pipeworx exactly, and it is a full working router rather than a fallback. This gives the agent an accurate sense of current runtime behavior.

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

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

The description is dense but every sentence earns its place: it establishes identity, current state, usage, and fallback behavior. The specific retirement date is slightly granular, but it supports the claim that no candidate is active right now.

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 that there is no output schema, the description reasonably defers response shape details by stating 'same response shape' as ask_pipeworx. Combined with full parameter schema coverage and clear safety annotations, the description is sufficient for selecting and invoking the tool, though it relies on the sibling for exact output details.

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

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

Schema description coverage is 100%, so the schema fully documents the aliases and required question field. The description only says the tool has 'same arguments' as ask_pipeworx, which is consistent but adds no parameter-level semantics 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 identifies the tool as a beta version of ask_pipeworx, a universal router with 5,798 tools, and explicitly states it has the same arguments and response shape. This clearly distinguishes it from the stable ask_pipeworx sibling by emphasizing the experimental routing improvements.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared against the stable router. It does not explicitly state a when-not-to-use condition, but the beta framing and 'experimental edge' make the tradeoff reasonably clear.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the exact success return shape, the refusal object with its possible refusal_reason values, and the behavior of extracting only from tool results. It also transparently notes the extra LLM call cost, which is a meaningful behavioral tradeoff.

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

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

The description is dense but every sentence serves a purpose: mode definition, mechanism, return contract, usage guidance, and cost tradeoff. It is front-loaded with the most important differentiator and contains no 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?

For a complex tool that routes across thousands of sources and has nuanced refusal behavior, the description is complete. It documents success and failure shapes, refusal reasons, usage context, cost, and the relationship to the main sibling tool, leaving no critical gap for an agent 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?

Schema description coverage is 100%, and the schema already documents the question parameter and its aliases clearly. The description adds no additional parameter-level syntax or formatting guidance, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies this as a hallucination-resistant answer extraction mode for high-stakes reads, distinguishing it from the sibling ask_pipeworx by emphasizing that answers are extracted only from tool results. The verb+resource+mode are specific, and the tool is clearly positioned within the sibling family.

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

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

The description explicitly states when to use this tool: whenever the answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples like financial verdicts, legal claims, and medical lookups. It also names the alternative ask_pipeworx and advises preferring it for casual lookups due to the extra LLM call cost.

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

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

The description extensively discloses behavioral traits beyond annotations: low-confidence resolution short-circuits, closed/dead market handling, wide-spread illiquidity, resolution-rule risk parsing, and parent-event extraction. It does not contradict any annotations (readOnlyHint, idempotentHint, etc.) and adds critical nuance.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the purpose in the first sentence. The length is justified by the tool's complexity, but could potentially be trimmed.

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

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

Given the tool's sophistication and lack of output schema, the description covers input formats, classifier categories, fan-out behavior, response structure, resolver contract, parent event extraction, news fields, safety mechanisms, and edge cases comprehensively. No gaps are apparent.

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 some schema info (e.g., depth enum) but adds no new parameter-specific detail. While the overall context enriches understanding, parameter semantics are adequately handled by the schema alone.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives detailed fan-out examples per category. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Description adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years, and mentions citation URIs. No annotation 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 dense and slightly unbroken but contains no filler. Every sentence adds value. Front-loading examples and usage hints improves usability.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns (paired data, sorted results, citation URIs) and how it handles entity types. Complete for its complexity.

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

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

Schema coverage is 100%, but the description enriches parameter understanding by explaining entity-specific input formats (tickers/CIKs for company, drug names) and confirming value constraints (2-5 items).

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: side-by-side comparison of 2-5 companies or drugs. It includes trigger phrases ('X vs Y', 'rank these companies') and distinguishes itself from single-entity tools like entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. Also explains that results are sorted by primary metric, aiding interpretation of queries like 'largest' or 'most'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds value by specifying the exact metadata fields returned and the intended use case (learning column names), going beyond what annotations provide.

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

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

The description is a single sentence of 24 words, immediately stating purpose and usage. No redundant information is present; every word earns its place.

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

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

Given the low complexity (1 parameter, no output schema, rich annotations), the description adequately covers purpose, usage, and return values. It mentions the metadata types returned, which compensates for the lack of an output schema.

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

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

With 100% schema description coverage and a single parameter, the description adds minimal new information about 'dataset_id' beyond the schema's 'Dataset id from search_datasets.' However, it does imply the parameter's role in the workflow, meeting the baseline.

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

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

The description uses a specific verb ('get') and resource ('metadata for one Paris Open Data dataset'), listing concrete items (fields/schema, themes, record count). It distinguishes from sibling tools like 'search_datasets' and 'query'.

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 ('call before query to learn the column names'), providing clear context. While it does not mention when not to use it, the instruction is sufficient for this tool's purpose.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is known. The description adds substantial beyond-annotation behavior: the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gap recovery behavior at standard/thorough depth, contradictions[] scans, semantic excerpting rather than head-truncation, and latency expectations (15-60s, up to ~90s). This goes well beyond what the annotations convey.

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

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

The description is dense but front-loaded with the most important constraint (account/payment, alternative tool). Every sentence adds meaningful information, though it is long and somewhat parenthetical-heavy, which slightly hurts scannability.

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

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

For a complex tool with 2 parameters, no output schema, and rich semantics, the description covers what the tool returns, how it behaves over time, edge cases, auth, and performance. This is arguably complete for everything an agent needs to decide to invoke it.

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 both parameters have descriptions, but the tool description enhances the depth parameter with real-world behavior (what 'standard' adds vs 'quick', what 'thorough' adds, and that 'thorough' requires a paid plan). question is well covered by the schema, so a 4 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 explicitly states the verb (research), resource (1517 structured data sources), and mechanism (parallel decomposition across 5,798 tools), and differentiates from open-web search and siblings like ask_pipeworx. This makes it clear what the tool does and how it differs from alternatives.

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

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

The description names ask_pipeworx as the alternative for non-signed-in users, states that it is NOT for single lookups, and gives explicit best-use examples ('compare X and Y', 'research the filings + market picture for ACME'). It also specifies depth tiers and when each is appropriate.

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) are consistent with description. Description adds value by detailing return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

Description is concise (3-4 sentences), well-structured, and front-loaded with purpose. Every sentence adds value: purpose, use cases, what it returns, and when to call.

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 (6 params, all covered in schema; no output schema), the description adequately explains behavior and usage. It lacks details on return format structure but compensates by noting 'full input schemas' and examples.

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

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

Schema coverage is 100%, so baseline is 3. Description adds examples and clarifies that parameters are aliases for 'query', but does not add deeper semantics beyond what schema provides. The examples help with usage 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 tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from siblings by instructing 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

Explicitly says when to use (when browsing/searching/discovering tools) and provides context ('Call this FIRST'). Does not explicitly state when not to use or offer alternatives, but the context implies it is for exploration before selecting a specific tool.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: fans out across many sources in one parallel call, patent data soft-fails until reactivated, empty sections mean real no-data, and private companies return resolved:false with a notes line. 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 information-dense and every part carries meaning, but it is one long unstructured paragraph with many parenthetical asides and a long list of examples. It would be easier to parse with bullets or clearer paragraph breaks, though its length is somewhat justified by the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: cik, company_name, resolved_from/resolved_to, recent_filings with URIs, fundamentals, source used/failed lists, and the no-data vs failure distinction. It also covers accepted input shapes and edge cases like private companies, making it complete enough to invoke correctly.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds useful semantics beyond the schema by clarifying that `type` accepts 'company' or 'ticker' interchangeably and that `value` can be a ticker, CIK, or company name resolved via SEC EDGAR.

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 action (build a full cross-source company profile) and opens with concrete trigger phrases like 'Tell me about X' and 'research Acme'. It also distinguishes itself from single-source SEC/XBRL/news lookups, so an agent can tell what it does without needing the schema.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' giving a clear when-to-use routing rule and naming the alternative approach. It also scopes applicability to US public companies and explains the private-company fallback behavior.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to repeat those. It adds context about use cases but does not disclose details like what happens if key does not exist. Still, it is consistent and sufficiently transparent.

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 that are front-loaded with action and resource, no fluff. Every sentence serves a purpose.

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

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

Given the tool's simplicity (one param, no output schema, annotations present), the description is complete: it explains what it does, when to use it, and its relationship to siblings. No gaps.

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

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

Schema description coverage is 100%, with the key parameter already documented as 'Memory key to delete' and an example. The description does not add extra semantics beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states that the tool deletes a previously stored memory by key, with a specific verb (Delete) and resource (memory). It distinguishes itself from siblings 'remember' and 'recall' by being the deletion counterpart.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also advises pairing with remember and recall, providing clear 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?

The description discloses that it 'fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which aligns with annotations (readOnlyHint=true, destructiveHint=false). It adds details about the output format and process beyond annotations.

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

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

The description is concise (two sentences plus a list) and front-loaded with the core purpose. Every sentence adds value, and there is no redundant or filler content.

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

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

For a simple read-only tool with two parameters and no output schema, the description provides sufficient context: what it does, how it works, and use cases. It could mention error handling or limitations, but overall it is complete enough.

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 adequately documents both parameters. The tool description does not add new meaning beyond the schema; it mentions the output format but not parameter specifics. Baseline 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL. It specifies the verb 'generate' and the resource 'llms.txt file', and distinguishes from siblings as no other tool produces this specific output.

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

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

The description lists concrete use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'), providing context for when to use the tool. However, it does not explicitly state when not to use or mention alternatives.

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

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

Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. Description adds the specific fields returned, which is helpful. No contradiction or missing behavioral details.

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 covers purpose and output, second provides usage guidance. No redundant information.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete enough with annotations covering safety. Could mention pagination or empty results, but not critical.

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% (single parameter with description). The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Clearly states it lists the caller's active subscriptions and specifies returned fields (id, type, params, etc.). Distinguishes itself from sibling tools like subscribe/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?

Explicitly advises when to use: to review monitoring before adding more subscriptions or to find an id to cancel. Could mention alternatives like subscribe/unsubscribe for context, but the guidance is clear and actionable.

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

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

All annotations are false, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), the claim_token mechanism for later status checks, that it's free, and behavioral constraints like 'don't paste the end-user's prompt.' It even explains the digest-read process and roadmap 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 information-dense. Every sentence contributes (purpose, when-to-use, exclusion, content guidance, claim_token behavior, rate limit). It is front-loaded with the core purpose and then expands logically. Slightly verbose but earns its length.

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

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

Given the tool's complexity (nested context object, no output schema, all-false annotations), the description covers usage boundaries, parameter interactions, rate limits, and the full feedback lifecycle. It even tells the user how to identify whether a tool belongs to Pipeworx. This is complete for an agent to invoke and follow up.

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

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

Schema coverage is 100%, so the description doesn't need to repeat parameter basics. It adds valuable semantics for claim_token: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed' and notes it should be used 'with no other arguments.' This goes 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 begins with a specific verb phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which precisely states the tool's purpose and resource. It distinguishes itself from sibling tools by explicitly scoping to tools served by this Pipeworx connection and excluding feedback for other MCP servers.

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

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

The description explicitly lists when to use (bug, feature/data_gap, praise) and when not to use (if the tool came from a different MCP server, file elsewhere). It also offers a disambiguation hint: 'Pipeworx tool names are the ones this connection lists.' This is model-explicit usage guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds non-obvious details: data sourced from CF analytics-engine, no PII, caching (5min-1h). Valuable behavioral context beyond annotations.

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

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

Concise: 3 sentences, front-loaded with purpose, then return shape, use cases, and technical notes. Every sentence adds value; no 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?

No output schema, but description specifies return shape (top tools, packs, volume). Single parameter well-documented. Caching and data source disclosed. Sufficient for a simple read-only tool.

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

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

Schema covers parameter completely (100% coverage with enum and description). Description mentions window options but adds marginal insight beyond schema's 'shorter windows surface hot; longer windows show steady-state'.

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 returns trending data: top tools, packs, call volume. Verb 'Returns' and specific resource. Distinguishes from sibling tools like discover_tools or suggest_questions by focusing on real-time agent calls.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical tool, checking alignment) and explains window trade-offs. Provides clear when-to-use guidance without needing to reference 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?

Discloses internal logic: semantic anchor (Jaccard >= 0.30), partition filter (placeholder slugs), fill check with CLOB depth, and response structure. Annotations already declare readOnly, idempotent, openWorld; description adds valuable context without contradiction.

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

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

Description is lengthy but well-structured, front-loading the core purpose then detailing each mode. Every sentence adds value, though some redundancy (e.g., repeated fill-check mention) could be trimmed.

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

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

Covers all modes, edge cases (low similarity, placeholders), response format with fields, fill-check behavior, and references to companion tools. Without output schema, the description provides a comprehensive picture of tool behavior and outputs.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds meaning: explains that 'event' accepts Polymarket URLs or slugs, how 'topic' triggers cross-event scanning with seed questions, and internal processes like flattening markets and checking partition sums.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no-args trending scan, event-specific, cross-event topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: call with NO args for trending scan, pass 'event' for specific market (recommended), or 'topic' for cross-event. It explains when to use each mode, recommends fill-check via polymarket_fill_risk for custom sizing, and warns against trading when realizable edge <= 0.

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. The description goes far beyond by detailing three model families, edge calculation, slippage assumptions, caching policy, and diagnostics. 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 extremely detailed and structured, but at 300+ words it is verbose. Key information is front-loaded, but later sections repeat concepts (e.g., 'TRADEABLE-EDGE KNOBS' re-explains filter parameters). Could be shortened without losing meaning.

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 9 parameters, no output schema, and complex response structure, the description thoroughly covers response segments, edge metrics, diagnostics, and caching. It leaves no major gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% with thorough parameter descriptions. The main description reinforces parameter use cases (e.g., tradeable-edge knobs) but does not add substantial new information beyond the schema's parameter-level descriptions. Baseline 3, marginal improvement yields 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 scans Polymarket markets and returns edge opportunities based on Pipeworx disagreement. It explicitly distinguishes itself as a daily discovery tool, not an arbitrage or tracking tool, which separates it from sibling tools.

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

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

The description positions the tool for 'what should I bet on today' scenarios and explains that Fed bets are excluded from ranking. However, it does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, so the agent must infer when to use which.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds concrete behavioral details: snapshot-based, daily closes, 60-day TTL, decay computation method. 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 thorough but well-structured, with clear sections for response fields and limitations. A slight overuse of dashes and parentheses could be tightened, but overall it is effectively 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?

No output schema exists, yet the description comprehensively explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields. It also notes data limitations and computation details, making it self-sufficient 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?

Input schema already provides full coverage with descriptions for both parameters. The description restates defaults and clamping but adds no new semantic meaning beyond what the schema offers, so baseline score is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical persistence and decay, not just current edges.

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

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

The description explains when to use this tool (to evaluate edge longevity and decay) and contrasts fresh vs. old edges. It implicitly differentiates from 'polymarket_edges' but does not explicitly list alternatives or 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?

The description adds behavioral context beyond annotations: it explains the ladder-walking mechanism, return fields (verdict, slippage, etc.), and risk factors (thin books, forced directional risk). Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description aligns with these.

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

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

The description is thorough and well-structured with clear sections for single-market and basket modes. While somewhat lengthy, every sentence provides important information without redundancy. It could be slightly more concise but remains effective.

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

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

Despite no output schema, the description lists all return fields and explains use cases thoroughly. It covers edge cases (thin legs, forced directional risk) and provides comprehensive context for the agent to understand tool behavior and limitations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining how size_usd is interpreted differently in single-market vs basket mode and that side defaults to auto in basket mode. This enriches parameter understanding beyond the schema.

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

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

The description clearly states that the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and specifies the relationship to sibling tools (polymarket_arbitrage and polymarket_edges).

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

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

The description explicitly instructs to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It warns against partial basket fills leading to unhedged directional positions, providing clear when-to-use and when-not-to-use guidance.

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

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

The description is exceptionally transparent about behavior well beyond the annotations. Annotations only cover readOnly/idempotent safety; the description discloses the compatibility_codes[] system, per-entry flags[], the rule that 'unknown' metric_type/match_subtype legs are NEVER paired, the semantic meaning of null temporal_alignment, the gross-vs-net fee disclosure (Kalshi fees not modeled), and the skipped_cross_type/cross_subtype counters. 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 content-wise, but the description is a single dense run-on wall of text with no paragraph breaks, headers, or bullets. The TWO MODES, codes list, and fee note are buried inside long compound sentences. It's informative but structurally poor — a reader must parse interleaved clauses. Appropriate for the complexity, but a structured rewrite would materially improve it.

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 high-complexity dual-venue comparison tool with no output schema, the description carries the full burden of explaining outputs — and it does. It documents leg-by-leg prices, top_spreads_pp format, all compatibility codes, per-entry flags, temporal alignment semantics, fee disclaimer, skipped-leg counters, and the low-confidence inspection path. Nothing an agent needs to interpret results is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value above baseline by explaining the topic param's 10 macro shortcuts, the override semantics for kalshi_event_ticker and polymarket_event_slug, and the key fact that BOTH modes run the identical token-overlap matcher. This clarifies how the three parameters interact, which the schema alone does not convey.

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

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

The opening sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes the tool from its polymarket_* siblings (arbitrage, edges, edge_tracker) by naming both venues and the comparison nature. The scope is unambiguous.

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

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

The description explicitly lays out TWO MODES (topic shortcuts vs. explicit ticker/slug), explains when each is appropriate, and notes that explicit arguments override the topic-mapped side. It also gives a strong usage caveat: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It doesn't name sibling tools as alternatives, but the mode guidance and expectation-setting are clear. Slight deduction for not explicitly comparing against polymarket_arbitrage or polymarket_edges as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false. The description adds valuable context about the ODSQL syntax and supported clauses, which is critical for correct invocation but does not disclose potential side effects 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?

Single sentence, front-loaded with the core purpose, followed by a parenthetical enumeration of key capabilities. No redundant information; every word serves a purpose.

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

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

Given 8 parameters and no output schema, the description provides a high-level overview but lacks details on ODSQL syntax (e.g., clause order, combining filters with aggregation) and does not mention return format or error conditions. Examples in the schema partially compensate.

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 individual parameter descriptions. The description adds semantic grouping by mapping operations to parameters (Filter (where), aggregate (group_by/select), etc.), which helps the agent understand parameter roles 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 uses a specific verb 'Query' with a concrete resource 'records from a Paris Open Data dataset' and clearly lists supported ODSQL operations (filter, aggregate, sort, paginate). It distinguishes itself from sibling tools like search_datasets by naming the query language and data source.

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

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

The description implies usage for ODSQL queries but does not explicitly state when to use this tool versus alternatives (e.g., search_within for simpler searches). No when-not or exclusion guidance is provided.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that omitting key lists all keys and explains scoping, providing useful 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?

Three sentences, front-loaded with main purpose, then usage context and pairing. No unnecessary words; every sentence adds value.

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

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

Complete for a simple tool with one optional parameter. Covers retrieval, listing, scoping, and relations to remember and forget. No missing information given the 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 description already explains the key parameter's purpose. The description does not add new parameter-level details beyond rephrasing the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if key is omitted. It uses specific verbs (retrieve, list) and resource (saved memory), and distinguishes from sibling tools remember and forget.

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

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

Explicitly describes when to use: to look up previously stored context without re-deriving. Provides context on scoping (anonymous IP, BYO key, account ID) and pairs with remember and forget for save/delete operations.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds behavioral details: return fields (source, citation_uri, payload), the effect of mark_read on subsequent calls, and polling suitability.

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 (four sentences) with no wasted words. It front-loads the main purpose and each subsequent sentence adds essential 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?

Given the absence of an output schema, the description explains return fields. All 5 parameters are covered in both schema and description. Annotations are present, and sibling context is provided via the tool list. The description is complete for this read-only polling 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 baseline is 3. The description adds value by explaining the purpose of each parameter (e.g., filter by type, ISO timestamp for since, effect of mark_read) and default limit, enriching 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 starts with a specific verb ('Pull') and resource ('fired events from your subscription feed'), immediately stating the tool's action. It distinguishes from siblings by focusing on reading alerts, as opposed to subscription management or search tools.

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

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

The description explains when to use the tool (e.g., polling works fine) and provides context like the same feed being available via GET. It does not explicitly state when not to use it, but the usage 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, and non-destructive behavior. The description adds transparency about multi-source fan-out, fallback mechanisms, soft-fails for USPTO, and the return structure (changes[] grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is efficiently front-loaded with query examples and covers all essential aspects without unnecessary words. Every sentence adds value, balancing detail and conciseness.

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

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

For a tool with 3 required parameters, no output schema, and complex multi-source behavior, the description thoroughly covers purpose, parameters, sources, fallbacks, and sibling differentiation. It leaves no significant gaps.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the 'since' parameter with examples (ISO dates, relative shorthand like '7d', '30d') and typical usage, and gives examples for 'value' (ticker or CIK). It also clarifies that 'type' is currently limited to 'company'.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists specific data sources (SEC EDGAR, GDELT/GNews, USPTO). It also distinguishes from the sibling tool 'entity_profile', making the purpose unambiguous.

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

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

The description includes example queries, specifies that it is for recent changes, and explicitly advises using 'entity_profile' for static profiles regardless of window. It also details fallback behavior between GDELT and GNews, providing 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 provide idempotentHint=true and destructiveHint=false. Description adds key behavioral details: scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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?

Concise, front-loaded with purpose, then usage guidance, then behavioral details. Every sentence adds value, no redundancy.

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

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

Given the low parameter count and full schema coverage, the description adequately explains scope, persistence, and pairing with other tools. There is no output schema, but return behavior is implied by the use case.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description adds examples of key patterns (e.g., 'subject_property') and value types, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations and sessions, using specific verbs and resource types. It distinguishes from siblings like recall and forget.

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

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

Explicitly tells when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget, and notes persistence differences for authenticated vs anonymous users.

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

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

Beyond the read-only/idempotent annotations, the description discloses meaningful behavior: it aggregates SEC EDGAR, GLEIF, OpenFIGI, and RxNorm sources; returns different identifier sets per type; and degrades gracefully when enrichment sources are unavailable. It also notes internal cascading lookups, which helps an agent set expectations.

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 information-dense and front-loaded with trigger phrases, but it is a long run-on with nested parentheticals and some redundancy with the schema (e.g., accepted inputs repeated). It earns most of its length, but would benefit from tighter structure.

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 carries the burden of explaining return contents, and it does so for both types, including fallback behavior and coverage of non-US issuers. Minor gaps remain around ambiguous-name behavior and exact response shape, but an agent has enough to select and call the tool correctly.

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

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

Schema coverage is 100% and the schema already documents both parameters precisely, so the baseline is 3. The description adds value on top by explicitly including ISIN as an accepted company input, giving the CH0038863350 example, and clarifying non-equity securities, which are not fully represented in the schema.

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

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

The description opens with concrete user phrasings and states the core verb-resource pair: resolve a name to canonical/official identifiers. It distinguishes itself from likely siblings by listing supported types (company, drug) and the identifiers returned, so an agent can tell it apart from related tools like entity_profile or validate_claim.

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

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

'Use FIRST whenever you have a name but need an ID' is an explicit when-to-use directive, and the trigger phrases make the matching intent obvious. It does not explicitly name alternatives or state when not to use the tool, but the guidance 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. Description adds context about ranking and output but no new behavioral traits beyond what annotations provide.

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

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

Three sentences, front-loaded with core action, no redundancy. Every sentence adds value.

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

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

Given moderate complexity (4 params, 1 required) and strong annotations, the description fully explains tool purpose, behavior, and output format (ranked list with score, confidence, signal density). No gaps.

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

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

Adds meaning beyond schema by noting the first entity is treated as the 'subject' for narrative, and implies relationship between models and _apiKey. Schema descriptions are complete (100% coverage) so description provides additional context.

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

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

The description clearly states the tool compares AI visibility across multiple entities, with specific actions: probe, rank, surface most/least recognized. It distinguishes from sibling ai_visibility_check by emphasizing side-by-side comparison.

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

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

Provides a concrete use case (competitive AI-marketing audits) and implies when to use it over ai_visibility_check. Lacks explicit when-not or alternatives, 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?

Beyond annotations (readOnly, idempotent, openWorld), description adds that bundlephobia first measurement can take 5-30s and may timeout, with sources_failed listing it. No contradiction with annotations.

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

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

Well-structured with front-loaded purpose: first sentence composite check, second usage, third return format, fourth ecosystem, fifth caveats. 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?

No output schema, but description fully enumerates return fields plus per-advisory, links, alternatives. Covers edge cases like partial failures and timeouts. Complete for a 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 covers both parameters fully. Description adds useful detail: scoped packages accepted and version defaults to latest, which goes above baseline of 3 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?

Description clearly states it is a composite check for adding npm packages, fans out across deps.dev and bundlephobia. Distinguishes from siblings by specifying NPM ecosystem and composite nature.

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

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

Explicitly says to use when agent asks about safety, popularity, size, or cost. Notes NPM-only in v1 and directs other ecosystems to deps.dev:version directly. Also explains partial failure degradation.

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, destructiveHint=false. Description adds useful behavioral context: returns specific fields, operates on Paris Open Data, and expects keywords. No contradictions.

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

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

Two sentences, no superfluous text. Front-loaded with purpose and actionable return 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 strong annotations and full schema coverage, the description is complete enough. It explains the return value (no output schema needed) and scope. Could mention pagination behavior, but offset parameter covers that.

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% (all three parameters have descriptions). The description adds thematic context but doesn't supplement parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches Paris Open Data for datasets by keyword, lists example themes, and specifies what it returns (dataset_ids, titles, themes, record counts). It distinguishes from sibling tools like query and dataset_info.

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

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

The description explicitly tells the agent to use returned dataset_ids with query/dataset_info tools, providing actionable guidance. Could be improved by noting when not to use (e.g., for specific queries already knowing the dataset).

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 technical details beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' This fully informs the agent of internal behavior and edge cases.

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

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

The description is concise yet comprehensive. It starts with a clear purpose statement, then provides usage context, pairs with a sibling, and ends with technical details. 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?

Given the complexity (3 params, no output schema), the description covers all necessary aspects: what it does, when to use, how it works internally, pairing with a sibling tool, and what the output contains (passages with offsets and scores). No gaps.

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

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

Schema coverage is 100% with good per-parameter descriptions. The description adds real-world examples for 'text' (SEC 10-K body, article) and 'query' (supply-chain risk), enhancing semantic understanding. Baseline is 3; these examples push it higher.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It uses a strong verb ('search') and specific resource ('inside a fetched record'), and distinguishes from siblings like 'search_datasets' by emphasizing internal search on already-pulled text.

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 the record is too big to cram into the prompt') and how it pairs with 'ask_pipeworx_grounded' as an alternative or complement. This provides clear guidance on context and avoids misuse.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds behavioral details like the OAuth requirement, return of subscription id, delivery channel constraints (e.g., SMS 10/day cap, webhook auto-disable after 10 failures), and type-specific param formats. This goes beyond annotations without contradiction.

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

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

The description is several sentences long but every sentence adds information (purpose, auth requirement, type examples, delivery details). It front-loads the main action. Slightly verbose due to detailed examples, but nothing is wasted. Could be more streamlined but still efficient.

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

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

Despite no output schema, the description covers the return value (subscription id) and all relevant usage aspects: prerequisites, type-specific filtering, delivery channels with constraints. For a tool with nested parameters and no output schema, this provides sufficient context for correct invocation and understanding of behavior.

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

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

Schema coverage is 100%, but the description enriches each parameter significantly. For the 'type' parameter, it explains what each enum value corresponds to (e.g., 'sec_8k' for 8-K filings with items). For 'params', it provides detailed format examples per type. For 'delivery', it explains each channel's behavior and validation. This adds substantial value beyond the bare 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 starts with 'Create a proactive monitoring subscription to a live-data event stream.' This provides a specific verb ('create'), resource ('subscription'), and scope ('proactive monitoring subscription to a live-data event stream'). It clearly distinguishes from sibling tools like list_subscriptions (which list) and unsubscribe (which removes).

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 a prerequisite ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)') and lists supported subscription types with examples. While it does not explicitly say when not to use this tool or contrast with specific alternatives, the context provides clear guidance on when it is appropriate.

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 destructiveHint. The description adds value by explaining that the tool returns example questions with tool+argument shapes from a live catalog of thousands of tools, and that it is an onboarding entry point. No contradictions.

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

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

The description is detailed but not overly verbose. It front-loads the purpose with natural language examples and then explains usage. Every sentence adds value, though minor trimming could improve conciseness.

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

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

The tool has no output schema, but the description fully explains what it returns: category-bucketed example questions with tool+argument shapes. It also mentions meta-tools. This is complete given the tool's simplicity and 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%, so baseline is 3. The description adds meaning beyond the schema by explaining that omitting 'topic' gives a full spread, while passing a topic focuses the results. It also lists possible topic values in context.

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

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

The description clearly states the tool's purpose: returns category-bucketed example questions for Pipeworx. It lists specific categories and explains that it serves as an onboarding entry point. The description distinguishes it from siblings by explicitly calling it the first tool to use when unsure of Pipeworx's capabilities.

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 usage context: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to use it with or without the 'topic' argument. However, it does not explicitly state when NOT to use it, though the context is clear.

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

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

The description adds beyond annotations by stating the row is deactivated (not deleted) and historical events remain accessible via recent_alerts. This informs the agent about the non-destructive nature and side effects, complementing the annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is three sentences, densely informative with no fluff. Each sentence adds essential information: the action, ownership constraint, and behavioral detail about deactivation.

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

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

For a simple tool with one parameter and no output schema, the description covers the action, ownership, and side effects (deactivation vs deletion, link to recent_alerts). It is fully adequate for an AI agent to understand and invoke the tool correctly.

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

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

The schema covers the single required parameter 'id' with a description, and the tool description does not add further meaning beyond what the schema provides. With 100% schema coverage, the description meets the baseline without adding extra semantic value.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb (Cancel) and resource (subscription by id). It distinguishes itself from sibling tools 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?

The description notes 'Ownership is enforced — you can only cancel your own subscriptions,' providing clear context on when the tool is applicable and a constraint. It lacks explicit alternatives but the guidance is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses crucial behavior: 'could_not_verify means the check did not happen ... must not be shown as one,' 'unsupported means we looked and cover no source for it,' and the verdict/error structure. This adds significant operational nuance that annotations alone do not convey.

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

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

The description is longer than average but every section earns its place: query patterns, routing rules, return values, caller warning, and efficiency claim. It is front-loaded with trigger phrases and organized logically, though slightly verbose.

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

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

Despite lacking an output schema, the description enumerates all verdict values, explains error semantics under could_not_verify vs. unsupported, mentions pipeworx:// citations and reasoning, and describes the internal pipeline. This is complete for a complex verification tool with no structured output definition.

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 both parameters are documented. The description adds practical guidance beyond the schema, e.g., advising 'set 1–2 for hallucination detection' and explaining tolerance default behavior, which enhances the agent's ability to choose values correctly.

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

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

The description clearly states a specific verb+resource: natural-language claim verification against authoritative sources, with explicit trigger phrases ('fact check', 'verify the claim that…'). It also distinguishes the tool's internal routing (SEC EDGAR fast path vs. grounded fallback), which differentiates it from generic query or research sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' and provides guidance on company-financial vs. other claims. It does not list sibling tools as alternatives or state when not to use it, so it's clear context but lacks explicit exclusions.

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