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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the large safety burden is covered there. The description adds useful behavioral context beyond annotations: it performs routing, fills arguments, works on every tier, makes one fast call, and returns structured answers with stable pipeworx:// citation URIs.

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

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

The description is long but every section earns its place: the 'prefer over web search' instruction is front-loaded, examples are compact, and sibling routing guidance is packed into the latter half. It is slightly dense but not padded.

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

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

For a read-only, open-world query router with no output schema, the description is complete: it covers scope, use cases, trigger phrases, examples, citation output, alternatives, and the default positioning. An agent has enough context to decide when to call this tool instead of web search or sibling tools.

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

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

The input schema covers all parameters at 100%, including documenting that question accepts query, q, prompt, text, and input as aliases. The description does not add much beyond the schema, though its examples illustrate the expected question style. This is an appropriate baseline given high schema coverage.

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

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

The description states a specific verb and resource: it routes a natural-language question to the right tool among 5,708 tools across 1,494 sources and returns a structured cited answer. It also differentiates itself from siblings by calling itself the default entry point and naming ask_pipeworx_grounded and deep_research as step-up 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?

Usage guidance is explicit and extensive: it says to prefer this tool over web search for factual/current/historical data, lists trigger phrases and examples, designates it as the default starting point for most questions, and clearly identifies when to step up to ask_pipeworx_grounded or deep_research.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable beyond-annotation context: candidate routing improvements are enabled live when under test, results are compared against the stable router, and there is no degraded fallback—it is a full working router. This clarifies the beta semantics without contradicting 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?

Four sentences, each earning its place: identity/scope, current state, usage condition, and fallback behavior. Slightly dense and block-formatted, but appropriately sized for a tool that is a live experimental variant of a large router and needs to preempt confusion about differences.

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 router variant with no output schema, the description covers everything an agent needs: the tool is fully functional, argument-compatible with ask_pipeworx, has identical response shape, is currently in stable-match state, and when to use it. Annotations cover safety traits, so nothing important is missing.

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

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

Schema description coverage is 100%, with all six parameters (including five aliases for 'question') fully documented. The description adds no parameter-level detail beyond saying 'same arguments' as ask_pipeworx, which is a useful cross-reference but not new semantic meaning. Baseline 3 applies because the schema carries the required information.

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

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

The description states a specific resource ('beta version of ask_pipeworx'), a clear verb/role ('universal router'), and differentiates it from ask_pipeworx by the experimental routing candidate behavior. It explicitly identifies the sibling relationship, so an agent can distinguish this from ask_pipeworx at a glance.

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 it exactly like ask_pipeworx when you want the newest routing,' naming the alternative and the condition that selects it. It also adds practical guidance that no candidate is currently active, so behavior matches ask_pipeworx exactly, removing uncertainty about when the tool is safe to invoke.

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

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

The description goes well beyond the annotations by disclosing the exact success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the explicit refusal reasons, and the behavioral guarantee that the answer uses ONLY the tool result content. It also discloses the extra LLM call cost. This is rich, useful behavioral context that annotations alone do not provide, and no contradiction with readOnlyHint/openWorldHint/idempotentHint exists.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, output contract, refusal contract, usage criteria, cost tradeoff, and alternative recommendation. Important usage directives are front-loaded at the start, and the cost/alternative guidance comes last. There is no filler or repetition of schema 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?

Although there is no output schema, the description explicitly enumerates the success return fields and all refusal_reason enum values, covering the main missing structured information. It also explains when to use the tool, cost implications, and its relationship to ask_pipeworx. For a read-only Q&A tool with a single required natural-language parameter, the definition is complete enough for an agent to invoke it correctly and interpret its results.

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

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

Schema description coverage is 100%: all six parameters (question plus aliases) are documented in the schema, so the baseline is 3. The description does not add parameter-specific meaning beyond explaining that the question drives internal routing and arguments, which is more about tool behavior than parameter format. No extra syntax or formatting guidance is given, so the baseline 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 opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes itself from ask_pipeworx by emphasizing extraction from tool results only, with evidence and refusal semantics. The contrast with the sibling tool is explicit, so an agent can tell them apart without opening schemas.

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

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

It states exactly when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains like financial verdicts, legal claims, and medical lookups. It also names the alternative ask_pipeworx and explicitly says to prefer it for casual lookups, including the cost tradeoff of one extra LLM call.

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?

With readOnlyHint/idempotentHint already present, the description adds substantial behavioral context: it returns gaps[] for unanswered facets without inventing data, includes contradictions[] on standard/thorough, guarantees fetchable citation_uri, semantically excerpts large records, and states response-time ranges. It also discloses the paywall for 'thorough' depth. All consistent with annotations.

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

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

The description is long but densely informative — every clause contributes a distinct fact (prereqs, source scope, routing behavior, output shape, latency). It is front-loaded with the most decision-critical account requirement, followed by purpose and alternatives. While not terse, the complexity justifies the 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?

With no output schema, the description must define the return contract — it does thoroughly: findings packet fields, gaps[], contradictions[], hop and citation_uri semantics. Combined with usage rules and parameter semantics, an agent can determine when to call it, what inputs to pass, and what to expect back. Nothing important is missing.

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

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

Schema coverage of the two parameters is 100%, setting a baseline of 3. The description goes further by explaining what depth values actually do (gap recovery, lead chasing, contradiction scan, parallel facet count) and by clarifying that the question parameter tolerates broad/multi-part input. This added semantic value pushes it to a 4.

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

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

The description opens with a concrete definition: 'Grounded multi-source research across Pipeworx's 1494 STRUCTURED data sources ... in ONE call'. It explicitly contrasts with open-web search and names what it is not. It also names sibling ask_pipeworx for comparison, making the tool's purpose unmistakable.

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

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

Provides explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and account prerequisite note ('If you are not signed in, use ask_pipeworx instead'). This goes beyond implied context to explicit 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 (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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds context: fans out across multiple sources, returns specific fields, notes patents soft-fail until May 2025, and that names are not supported. 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?

Front-loaded with example queries, well-organized information. Every sentence adds value, but could be slightly more concise. Still efficiently communicates purpose, usage, and returns.

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, but description fully explains return fields (cik, recent_filings, fundamentals, patents, news, LEI) and their sources. Covers complexity of multi-source aggregation comprehensively.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by providing concrete examples (e.g., 'AAPL', '0000320193') and clarifying the 'type' enum and that names are not supported. Slight improvement over schema alone.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It lists specific sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields, distinguishing it from sibling tools like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name is provided, giving 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?

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?

Beyond annotations, the description thoroughly discloses behavior: compatibility_warning and compatibility_codes can be non-empty even on returned pairs, legs with 'unknown' metric_type or match_subtype are never paired, and pre-mapped pairings are unverified. It also exposes edge-case counters and explicitly states that real cross-venue spreads are rarer than the shortcut list implies, which is highly valuable honesty about reliability.

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

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

The description is long but dense and logically organized: purpose, modes, response shape, safety fields, and edge cases. It is front-loaded with the core purpose and every section contributes operational guidance. It could be slightly trimmed, but the complexity of the tool justifies the 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?

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: top_spreads_pp, compatibility fields/codes, temporal_alignment, skipped counters, low_confidence_pairs, and non-pairing rules. Given the tool's complexity and annotation coverage, nothing an agent needs to invoke or interpret it correctly is missing.

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

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

Schema coverage is 100% and each parameter already has a meaningful description. The tool description adds value by explaining how topic mode auto-fetches matching events, how explicit ticker/slug overrides work together, and how parameters map to response behavior. It mostly enhances rather than replaces schema information.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly differentiates itself from siblings like polymarket_arbitrage by focusing on cross-venue spread and explicitly defines the computation direction (Kalshi − Polymarket).

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

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

The description clearly separates the two invocation modes: topic shortcuts for pre-mapped macros and explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility_warning and that 'pre-mapped ≠ tradeable,' giving practical guidance on when results should be trusted. It does not explicitly name alternative tools, but the mode selection context is strong.

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 readOnly/idempotent annotations, the description adds critical behavioral context: it cascades through multiple lookup endpoints, degrades gracefully (LEI/FIGI enrichment still returns EDGAR data if unavailable), explicitly lists unresolved identifiers rather than omitting them, and labels each identifier with its source. This is substantial additional transparency.

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

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

The description is long but well-structured, leading with user-facing examples and a clear purpose. Every sentence adds value, though the density of technical detail might be slightly overwhelming. It earns a 4 rather than 5 due to its length, but nothing is wasted.

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

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

With no output schema, the description fully covers return semantics: identifiers labeled by source, unresolved entries, and drug results including RxCUI, ingredient, brand, and citation. It also addresses edge cases like ISIN resolution and service degradation, making it complete for a complex lookup tool.

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

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

Despite 100% schema description coverage, the description adds significant meaning: it explains that 'value' for company accepts ticker, CIK, ISIN, or name; details how an ISIN resolves to a legal entity; and gives concrete examples for drug lookups. This goes well beyond the schema's brief field descriptions.

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

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

The description clearly states a specific verb ('resolve') and resource ('user-spoken NAME to canonical/official identifiers'). It distinguishes from siblings by noting the output is what 'other tools require as input' and provides concrete example queries. It fully clarifies the tool's purpose.

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

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

Explicitly instructs to 'Use FIRST whenever you have a name but need an ID.' This is a strong when-to-use directive. It also clarifies the tool's role as a prerequisite for other tools, giving clear context for choosing it over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and 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.