Dbnomics

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

The description discloses key behavioral traits: default model is free, Anthropic requires user's own key (BYO), and the return structure includes per-model and combined views. These details complement the annotations (readOnlyHint, etc.) without contradiction, providing actionable guidance.

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

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

The description is concise (4-5 sentences), front-loads the core purpose and output, explains optional parameters, describes return structure, and lists use cases. Every sentence adds information without redundancy.

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

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

Given the tool's complexity (multi-model, optional auth), the description covers purpose, usage, model options, and return structure. It lacks explicit details on error handling or rate limits, but provides sufficient context for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the default model, the optional nature of models and apiKey, and providing examples for entity and context. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's action ('probe one or more LLMs'), the specific resource ('business / brand / product / topic'), and the output ('score visibility (0-100) per model'). It distinguishes itself from siblings by focusing on AI visibility scoring, a unique function among the listed siblings.

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

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

The description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies when to provide an API key for Anthropic. It implicitly differentiates from siblings by its focus, but does not explicitly state when not to use this tool or compare directly to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds meaningful context beyond annotations: it routes to thousands of tools, fills arguments automatically, and returns structured answers with stable citation URIs, including live news routing for breaking-news queries.

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

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

The description is information-dense and front-loaded with the most important guidance, but the ending is noticeably garbled and truncated (' default entry point, one fast call...'), suggesting a missing phrase. The long list of domains and examples is useful, but the malformed tail hurts overall structure.

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

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

Given no output schema, the description does well to state what the agent gets back: a structured answer with stable citation URIs. It covers supported domains, trigger phrases, routing behavior, and key sibling alternatives. Minor gaps like rate limits or failure behavior are not critical for a read-only, open-world question-answering tool.

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

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

Schema description coverage is 100%, and each parameter is documented as an alias for the natural-language question, so the schema already carries the semantic load. The description reinforces that the input is a natural-language question but does not add new parameter-level detail beyond the schema.

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

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

The description clearly identifies a specific purpose: a routing/answering tool that redirects questions to one of 5,798 tools and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, 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?

The description is unusually explicit about when to use this tool: prefer over web search, start here for most factual questions, and use examples like 'current US unemployment rate' and 'Apple's latest 10-K'. It also gives concrete alternatives, telling the agent to use ask_pipeworx_grounded for grounded citations and deep_research for broad multi-part questions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses the beta operational state, that candidates are enabled live only when under test, that none is active, and that the tool does not fall back to another route. This is valuable non-obvious context for an experimental router.

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 each sentence contributes: beta identity, current candidate state, usage direction, and fallback clarification. It could be slightly tightened because the current-state detail is restated, but it remains well 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?

For a single-parameter router with rich annotations, the description covers identity, experimentality, invocation equivalence, and response-shape equivalence. It leaves only the specifics of ask_pipeworx's routing behavior to the sibling tool's definition, which is reasonable but slightly indirect.

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 each parameter documented as an alias for question. The description adds no parameter-specific detail beyond pointing to ask_pipeworx's identical arguments, so the schema carries the semantic load and the baseline 3 applies.

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

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

The description identifies this as a beta version of ask_pipeworx with a concrete resource (universal router, 5,798 tools) and distinguishes it from the stable sibling by the experimental routing candidates. It also states the current behavior (matches ask_pipeworx exactly) so an agent knows what to expect.

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

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

It gives an explicit when-to-use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results feed merge decisions, which implies the stable ask_pipeworx is the alternative for non-experimental use, but it does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructure, and the description adds rich behavioral detail: routing across 5,798 tools, fetch data, extract only from tool result, specific success return shape, and concrete refusal reasons. No contradiction with annotations; the description complements them.

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

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

The description is dense but every clause earns its place: purpose, routing, extraction behavior, return shapes, refusal taxonomy, usage triggers, and cost tradeoff. Key scoping is front-loaded and the structured return details are compact.

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

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

For a complex tool with no output schema, it covers the return contract, failure modes, and selection criteria. It explains the extra LLM cost, which is essential for choosing between siblings. Minor gaps such as exact confidence semantics are acceptable given the annotations and the detailed description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema; it only implies a natural-language question. It does not clarify the alias/required interaction, but that is a schema concern rather than a description gap.

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

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

States a specific purpose: hallucination-resistant grounded answer mode for high-stakes reads. It names ask_pipeworx as same routing and explicitly distinguishes grounded mode from the casual ask_pipeworx. Clear from the first sentence.

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?

Gives explicit when-to-use criteria: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts. Explicitly says to prefer ask_pipeworx for casual lookups and discloses the cost tradeoff: 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 details behaviors beyond annotations (readOnly, openWorld, idempotent, non-destructive). It explains market resolution with confidence levels, fan-out logic with examples, response shapes, safety short-circuits, cancellation rules, and fallback mechanisms. No contradictions with annotations; the description adds significant behavioral context.

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

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

The description is well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with core purpose. However, it is quite lengthy and includes detailed classifier lists and fan-out examples that could be summarized. Every sentence adds value, but some redundancy exists (e.g., repeating safety mechanisms). Still earns its length for a complex tool.

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

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

Given the complexity of the tool (multiple data sources, rich response, no output schema), the description is remarkably complete. It documents response fields (market, analysis, evidence), resolver contract with confidence and alternatives, parent event extraction, news fallback, safety checks, wide-spread handling, and cancellation rules. Covers all necessary context for an agent to use the tool appropriately.

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

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

All 3 parameters have descriptions in the schema (100% coverage). The description further clarifies the 'market' parameter input formats (slug, URL, text), explains the 'depth' enum values with their implications, and provides guidance on 'include_raw' (recommended false, use true for specific needs). This adds substantial meaning beyond schema definitions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and core actions (resolve, classify, fan-out, return evidence + comparison). The use cases ('should I bet on X', 'what does the data say about Y') help distinguish it from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Explicit guidance on when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when the tool provides limited results (low-confidence matches, closed markets, illiquid spreads) and how to interpret them. No explicit when-not-to-use, but the context and examples implicitly differentiate from sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds useful behavioral context: handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and replaces many sequential lookups. No contradiction with annotations.

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

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

The description is relatively long but well-structured with examples and clear use cases. It front-loads the purpose and every sentence adds value, though it could be slightly more concise.

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

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

Given the complexity of comparing two entity types with multiple metrics, the description covers key aspects: data sources, sorting, citations, and parallel execution. No output schema exists, but the description mentions return format. Lacks details on error handling or timeouts.

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 both parameters with descriptions, but the description adds concrete examples (tickers for company, drug names) and explains what data is pulled for each type (SEC EDGAR 10-K data for companies, FAERS/FDA trials for drugs). This significantly enhances 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 performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses explicit trigger phrases like 'compare X and Y' and 'which is bigger', and distinguishes from sibling tools by stating 'ALWAYS PREFER over sequential single-pack lookups' and 'Replaces 8–15 sequential lookups'.

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

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

The description explicitly tells when to use this tool (comparing entities) and advises preference over sequential lookups. It implies when not to use by contrasting with single-entity lookups, but does not explicitly name alternatives like entity_profile.

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 discloses output structure (findings packet with verbatim evidence, confidence, source, fetched_at, citations), the explicit gaps[] mechanism for unanswerable facets, the contradictions[] scan, semantic excerpting, and latency expectations. It also clarifies that citations are only returned when fetchable, which directly informs trust and follow-up behavior.

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

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

The description is dense and information-rich, and the account requirement is front-loaded as a practical gate. However, the heavy use of nested parentheticals and run-on asides makes it harder to scan than it could be; a slightly more structured layout would improve readability without losing 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 tool with no output schema, the description covers the essential operational context: authentication, plan limitations, when to choose an alternative, internal parallel decomposition, output format, citation resolvability, gap handling, contradictions, and timing. An agent has enough information to decide, invoke, and interpret results correctly.

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

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

Schema coverage is 100%, and the description substantially enriches the depth parameter: quick=3 facets, standard=3 with gap recovery and contradictions, thorough=6 paid with iterative lead-chasing. It also ties depth to expected latency, which the schema alone does not communicate.

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 action and resource: grounded multi-source research across Pipeworx's 1,517 structured data sources in one call. It explicitly distinguishes itself from open-web search and from ask_pipeworx, so an agent can tell quickly what this tool is and is not.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly routes simpler/single-lookup cases to ask_pipeworx. It also provides an auth-based exclusion: if not signed in, use ask_pipeworx instead. Alternatives and conditions are clearly named.

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=true and idempotentHint=true. The description adds that returns '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,' providing valuable behavioral detail 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 front-loaded with purpose and includes a comprehensive list of data domains, but is slightly long. Still, every sentence adds value, earning a 4.

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 discovery tool with no output schema, the description fully covers what the tool returns (tools with schemas and examples) and how to use it, making it complete and actionable.

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 mentions the query parameter and limit, and lists aliases for query, but adds little semantic depth beyond what the schema already provides.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates many specific data domains (SEC filings, FDA drugs, etc.), making the tool's purpose highly specific and distinguishing it from siblings like search or compare_entities.

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

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

Explicit instruction to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)' provides clear when-to-use guidance and implies not to use when you already know the 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 read-only, idempotent, open-world, non-destructive behavior. The description adds substantial behavioral detail beyond that: source fan-out, soft-fail behavior for USPTO PatentsView, sources_used/sources_failed semantics, empty sections meaning no data not a bug, and private-company resolution behavior. There is no contradiction with annotations.

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

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

The description is long, but every sentence carries meaningful information about a genuinely complex tool. It is front-loaded with example queries and the key 'ALWAYS PREFER' guidance, and it organizes output sections and failure semantics efficiently. Slightly dense and run-on, but the length is justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: each output section is listed with its semantics, edge cases are explicitly handled, and source success/failure reporting is explained. For a tool with this much fan-out complexity, the description is effectively complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by reinforcing that type accepts 'company' or 'ticker' interchangeably and that value can be a ticker, CIK, or company name, with name resolution via SEC EDGAR. This is helpful beyond the schema, though not dramatically novel.

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 as producing a full cross-source profile of a US public company, with concrete example queries and a list of return sections. It distinguishes itself from single-pack SEC/XBRL/news lookups by explicitly stating it fans out across many sources in one parallel call.

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

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

The description gives explicit when-to-use guidance: prefer this over chaining single-pack lookups when the user wants a holistic view. It also covers important edge cases such as private companies returning resolved:false and type/value interchangeability, leaving little ambiguity about selection or invocation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds a genuinely useful behavioral detail: 'If a filter matches nothing, the response lists the dimension codes the dataset actually accepts.' This aids error handling and goes 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 two sentences, front-loaded with the core purpose and followed by a concise usage context and a relevant edge-case behavior. Every sentence earns its place with 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?

Given the tool's 6 parameters, nested objects, and presence of an output schema, the description is concise but sufficient. It covers the primary use case and a key behavioral nuance, while the schema and annotations fill in parameter and safety details. It doesn't cover pagination or observations, but those are clearly documented in the schema, so completeness is adequate.

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

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

Schema description coverage is 100%, with detailed explanations for each parameter, including the dimensions filter semantics and the observations flag. The description adds only conceptual context ('structured filters', 'provider+dataset') without introducing new parameter-level meaning. Thus, the baseline 3 is appropriate as the schema does the heavy lifting.

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 action ('browse series') with a clear resource ('series') and mechanism ('structured filters'). It further clarifies the use case of enumerating series by dimensions for a given provider and dataset, which distinguishes it from related tools like get_series (which likely retrieves a single series) and list_datasets/list_providers.

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 phrase 'Useful when you know the provider+dataset' explicitly indicates the prerequisite context for use. It does not name alternatives or state exclusions, but the implied contrast with tools that discover datasets/providers gives clear guidance. A minor gap is the lack of explicit 'when not to use' scenarios.

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

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

Annotations already indicate destructive and idempotent behavior. Description adds value by clarifying why you would use it (clear sensitive data) and how it relates to sibling tools, without contradicting annotations.

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

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

Two concise sentences – the first states the action, the second gives usage guidance. No wasted words, front-loaded with 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?

For a simple deletion tool with one parameter and no output schema, the description covers purpose, when to use, and relationships with siblings. Fully adequate.

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

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

Schema coverage is 100% and the schema describes the parameter ('Memory key to delete'). Description adds no additional parameter information, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' – a specific verb and resource. It distinguishes from siblings by mentioning 'remember' and 'recall' as paired tools.

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

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

Explicitly states three scenarios for use: stale context, task completion, clearing sensitive data. Implicitly contrasts with remember and recall as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds detail on the process (fetches page, extracts title/description/links, emits markdown) and output format, which supplements the annotations. No contradictions.

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

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

Three sentences: first states the core function, second explains the process, third provides use cases. No superfluous content. Information is front-loaded and efficiently presented.

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 two parameters and no output schema, the description fully covers the purpose, process, and output format. It explains how the output is used, making it complete for an agent to understand and invoke correctly.

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

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

Both parameters have full schema descriptions (100% coverage). The parameter descriptions are clear and concise. The tool description does not add new meaning beyond the schema, merely reiterates the purpose of the parameters. Thus, 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?

Description clearly states the tool generates an llms.txt file for a URL, with specific actions (fetches, extracts, emits). It distinguishes itself from sibling tools, which are mostly search, analysis, or data retrieval tools. The purpose is unambiguous.

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

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

Description explicitly lists use cases: getting a client's site indexed, drafting llms.txt for own project, auditing competitor. It provides context for when to use the tool, though it doesn't explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by indicating that including observations returns data points, which is beyond annotation coverage. No contradictions.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the action and resource, then provides the identifier format and optional behavior efficiently.

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, the output schema exists, and annotations cover safety, the description is complete. It tells agents exactly what they need: what it fetches, how to identify it, and the key optional parameter.

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

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

Input schema covers all parameters with descriptions (100% coverage). The description only restates the observations parameter's function without adding new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool fetches a specific time series using the verb 'Fetch' and identifies the resource. It specifies the identifier components (provider, dataset, series_code), distinguishing it from sibling tools like 'find_series' which searches for series.

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 indicates usage when exact identifiers are known and mentions the optional observations parameter. However, it does not explicitly state when not to use or compare to alternatives like 'find_series', leaving some ambiguity for agents.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the description adds meaningful behavioral context: pagination via limit/offset, the return of code/name/dimension metadata, and the single-provider scoping. It does not contradict annotations.

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

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

Two sentences, with the first verb ('enumerate') front-loaded. The opening phrase 'DBnomics economic time-series aggregator' is slightly verbose but provides useful context. Every sentence contributes to purpose or usage, so it 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 schema and annotations, the description is complete for a list tool: it covers pagination, return contents, and integration with sibling tools. The output schema exists, so detailed return structure is not needed in the description. No significant gaps remain.

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 three parameters described and example values provided. The description does not significantly add meaning beyond the schema, merely reinforcing that provider is a DBnomics code, which is already in schema examples.

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 enumerates datasets for a specific DBnomics provider code, using a specific verb and resource. It distinguishes from siblings by mentioning that returned codes are what get_series and find_series expect, and provides concrete provider examples.

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

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

The description provides clear context for when to use the tool (to list datasets for a provider) and even indicates downstream usage ('those codes are what get_series and find_series expect'). However, it lacks an explicit 'do not use when' or comparison with list_providers, so it's not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context by stating the approximate count (80+) and what data is returned (codes and names), which aligns with annotations and adds value beyond them.

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

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

Two sentences with no wasted words. The first sentence states the core action and scope; the second provides usage guidance. Front-loaded and concise.

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

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

Given the tool has no parameters and an output schema exists, the description is complete. It covers the tool's output and how to use it with 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?

With zero parameters, the baseline is 4. The description does not need to add parameter details, but it does mention the output content (provider codes and names), which indirectly clarifies what the tool provides.

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

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

The description clearly states the action ('List all statistics providers'), specifies the resource ('DBnomics'), and notes the content (codes and names). It also hints at linkage with sibling tools, but the core purpose is distinct from tools like list_datasets or get_series.

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 to use provider codes with list_datasets and get_series, guiding the agent on downstream usage. It does not explicitly say when not to use, but the simplicity of the tool (no parameters) makes that unnecessary.

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, destructiveHint=false. Description adds value by listing exact return fields and default filtering for active subscriptions.

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

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

Two sentences with no waste. First sentence defines purpose and output; second gives usage guidance.

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

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

For a simple read-only list tool with one optional parameter, the description covers purpose, behavior, output fields, and usage. No output schema needed; annotations cover safety.

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

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

Schema description coverage is 100%. The one parameter is fully described in the schema; description does not add extra semantics.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe/unsubscribe by explaining its usage.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Gives clear context for when 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?

While annotations only state readOnlyHint=false, the description goes well beyond structured data by disclosing important behavioral traits: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, returns a claim_token for later retrieval, and that the team reads digests daily. It also explains the pattern of passing the token back to read status and changes. 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?

Though longer than typical descriptions, every sentence serves a purpose. It opens with a clear one-line purpose, then systematically covers use cases, exclusions, follow-up behavior, and rate limits. The information is front-loaded and logically organized, with 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?

Given the tool's complexity (4 params, nested objects, no output schema), the description is remarkably complete. It explains return behavior via claim_token, rate limits, free status, and connection scoping. The absence of an output schema is compensated because the description explicitly states what filing returns ('a `claim_token`') and how to use it later. No gaps remain 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?

The schema already documents all 4 parameters with 100% coverage, providing a baseline of 3. However, the description adds meaningful guidance beyond the schema: it clarifies the purpose of `context` as optional structured context, advises 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt', and specifies that the `claim_token` should be passed 'with no other arguments'. This enriches parameter usage beyond the schema descriptions.

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

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

The description opens with a specific, action-oriented purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings by identifying it as the feedback channel for Pipeworx tools, while all other siblings are data/research tools. The verb+resource combination ('Tell the Pipeworx team') leaves no ambiguity about what the tool does.

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 provides when-to-use scenarios ('Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise)') and exclusions ('ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead'). It also gives guidance on how to phrase feedback and how to use the claim_token for follow-ups.

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

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

The description adds significant behavioral context beyond the annotations: the data source (CF analytics-engine), absence of PII, caching behavior (5min-1h depending on window), and the differential behavior of window options (shorter windows show hot content, longer show steady-state). This complements the annotations (readOnlyHint, idempotentHint) effectively.

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 with no filler. It front-loads the core purpose, then provides usage guidelines and behavioral details in a single paragraph. 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 the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers what the tool returns, the data source, caching, and the effect of the parameter. Annotations cover safety. No additional information is necessary.

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

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

The input schema already documents the only parameter (window) with an enum and description. The description adds valuable semantics: explaining that shorter windows surface 'what's hot right now' and longer windows show 'steady-state demand.' This goes beyond the schema's basic description.

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

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

The description clearly states the tool's purpose: 'What other AI agents are calling on Pipeworx right now.' It specifies that it returns top tools, top packs, and total call volume over a recent window. The three enumerated use cases further clarify the purpose and help distinguish it from sibling tools like discover_tools or search.

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

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

The description provides three explicit and concrete use cases for when to use this tool: discovering hot data sources, confirming canonical choices, and aligning use cases. However, it lacks guidance on when not to use it or explicit alternatives, which prevents a perfect score.

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, destructiveHint=false, which the description does not contradict. The description adds detailed behavioral context: the fill check, Jaccard similarity threshold, placeholder filtering, and the fact that the tool returns signals but may advise against trading. It goes well 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 relatively long but well-structured with sections (FILL CHECK, SEMANTIC ANCHOR, etc.). Every sentence adds value, though some redundancy exists (e.g., explaining partition_check twice). Could be slightly more concise, but overall efficient for the complexity.

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

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

For a complex arbitrage tool with multiple modes and no output schema, the description is remarkably complete. It explains input options, internal logic (Jaccard, partition filter, fill check), response fields (opportunities[] with gap_pp, suggested_trade, etc.), and even when not to trade. Sibling tools exist but this description is self-contained.

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% for both parameters. The description adds substantial meaning: it gives concrete examples of event slugs and topic seeds, explains what each mode does, and clarifies that no args triggers a default trending scan. This goes significantly beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) and the name/title explicitly indicate the domain (Polymarket) and function (arbitrage). No confusion with 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 provides explicit guidance: no args for trending scan, event for specific market slug, topic for cross-event scanning. It explains when to use each mode, warns about the fill check condition (do not trade if realizable_edge_pp ≤ 0), and mentions alternative for custom sizing (polymarket_fill_risk).

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: caching, model families, edge calculation, filtering logic, and diagnostics. It also explains why fed_candidates are excluded. 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 verbose but every sentence adds value, with clear structure: purpose, model families, filters, response fields. It is front-loaded with the core task but could benefit from tighter editing.

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 high schema coverage and no output schema, the description fully covers response structure, edge details, caching, and diagnostics. It anticipates user questions (e.g., why Fed bets are excluded) and is complete for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds meaningful context for parameters like slippage_pp (mentioning bid/ask costs) and min_partition_leg_kelly (explaining relationship to min_kelly). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes from sibling tools by detailing its unique approach and output structure.

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

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

The description provides clear context for when to use the tool (discover opportunities without paging) and details configurable knobs. However, it does not explicitly state when not to use it or compare to alternatives, though siblings like polymarket_arbitrage exist.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: it explains the response structure (tracked, expired, snapshot_dates), the meaning of trend and decay_pp_per_day, data freshness (snapshot written on cache-miss), and TTL constraints (60-day snapshot TTL).

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

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

The description is well-structured, front-loading the core purpose, then breaking down the response into labeled sections (RESPONSE, LIMITS). Every sentence serves a purpose, and the length is appropriate for the tool's complexity.

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

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

Given the absence of an output schema, the description thoroughly explains the return values (tracked, expired, snapshot_dates) including field meanings and limitations (e.g., decay from daily closes, not intraday). No critical information 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?

The input schema has 100% coverage with clear descriptions for both parameters (days and window). The description repeats the defaults and adds minor context (clamp range for days), but does not provide significant additional meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes itself from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on historical persistence.

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

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

The description provides context on when to use the tool (e.g., comparing fresh vs. old edges) and includes limits on data depth and snapshot gaps. However, it does not explicitly state when not to use it or name 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?

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it 'walks the ladder,' returns specific fields like 'top_of_book, vwap_fill_price, slippage_pp,' and provides a 'verdict (clean|degraded|cannot_fill).' It also explains the risk of partial fills converting arbs into directional positions, beyond what annotations convey. No contradiction.

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

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

The description is lengthy but well-organized into sections for single-market and basket modes. It front-loads the core purpose and requirement (REQUIRES one of market or event). Every sentence adds value, explaining parameters, return values, and risks. No fluff.

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

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

With 4 parameters, no output schema, and no nested objects, the description covers all necessary context: it explains both modes, all parameters, return fields (enumerates them), and potential risks. Given the tool's complexity (two modes, risk warnings), this is fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning: it explains the default logic for 'side' (auto from partition sum), interprets 'size_usd' differently for single-market vs basket modes, clarifies that 'market' and 'event' are mutually exclusive, and notes the clamp range 10–1,000,000. This goes well beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the verb 'check' accurately reflects the tool's purpose. This differentiates it from sibling tools like 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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about consequences like 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position,' providing clear when-to-use and when-not-to-use guidance.

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

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

The description goes far beyond the annotations' readOnly/openWorld/idempotent hints. It discloses that matched pairs can still carry warnings, that pairing is keyword-based and unverified, that spreads are gross of Kalshi fees, and that unknown legs are never paired. This is exemplary behavioral disclosure.

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, with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). No sentence is filler, though some details could arguably be moved to output documentation given the absence of an output schema. The structure makes the length navigable.

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 the response. It covers top_spreads_pp, compatibility warnings and codes, temporal alignment semantics, fee caveats, skipped-leg counters, and unclassified legs. For a tool with this complexity, the description is complete enough for an agent to invoke it confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant meaning beyond the schema: it explains what the 10 pre-mapped `topic` shortcuts do, that explicit parameters override the mapped side, and that both modes use the identical token-overlap matcher. This adds real selection and usage insight.

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

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

The description states a clear, specific purpose: computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from related sibling tools by emphasizing the cross-venue comparison and same-question matching, which is unambiguous.

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

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

The description clearly explains the two invocation modes (`topic` and explicit ticker/slug) and when each is appropriate. It also warns that pre-mapped topics may not imply tradeable spreads. However, it does not explicitly name sibling alternatives like `polymarket_arbitrage` or `polymarket_edges`, or state when those would be preferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about scoping (anonymous IP, BYO key hash, or account ID), which is beyond annotations. No contradiction.

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

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

The description is concise, with three well-structured sentences that front-load the purpose. Every sentence adds value: purpose, usage examples, scoping, and pairing with siblings. No unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description explains what it does, when to use it, how scoping works, and how it relates to sibling tools. It is fully adequate for an agent to understand and invoke correctly.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description reiterates the behavior (omit to list all keys) but does not add significant new semantics beyond the schema. 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 the tool retrieves a value previously saved via remember or lists all saved keys when omitting the key argument. It specifies the resource (saved memory) and verb (retrieve/list), and distinguishes from siblings like 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?

The description provides explicit guidance on when to use this tool: to look up context stored earlier without re-deriving it. It also mentions pairing with remember and forget, implying alternatives, and notes scoping to the agent's identifier.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the mark_read behavior and feed persistence, which are not covered by annotations. No contradictions.

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

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

The description is concise, well-structured, and front-loaded with the main purpose. 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?

For a read-only list tool with no output schema, the description adequately explains return fields, parameter usage, and behavior. All parameter types and effects are covered.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds minor context (e.g., mark_read flags returned events as read) but does not significantly expand 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 'pulls fired events from your subscription feed' and specifies the contents (source, citation_uri, raw event payload). It distinguishes from sibling tools by focusing on recent alerts from the user's feed.

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

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

The description provides clear usage context: it works for polling and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or list 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?

The description details the multi-source fan-out behavior, fallback mechanisms (GDELT→GNews), and edge cases (USPTO soft-fail). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description complements these 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 informative and structured, starting with purpose and examples. While it is somewhat long, every sentence adds necessary detail. It is well-organized with clear sections.

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 (3 params, multi-source fetch, no output schema), the description sufficiently explains return format (changes grouped by source, total_changes, citation URIs) and limitations. It could mention rate limits or pagination, but overall complete.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value beyond the schema by providing examples for 'since' shorthand (e.g., '30d', '1y') and clarifying that 'value' accepts ticker or CIK. It also notes 'type' is 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 within a time window, using specific verbs like 'what's new' and 'latest on'. It distinguishes itself from the sibling 'entity_profile' tool by stating when to use each.

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

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

The description explicitly tells when to use this tool (recent changes) and when not to (use 'entity_profile' for static profile regardless of window). It also provides example queries that clarify usage scenarios.

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

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

The description adds behavioral details beyond annotations: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours,' 'scoped by your identifier,' and linking to recall/forget. Annotations already indicate idempotentHint=true and destructiveHint=false, which the description reinforces 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 three sentences, front-loading the core purpose and immediately followed by usage guidance and storage details. Every sentence adds information without redundancy or filler.

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

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

Given the tool's simplicity (2 required string params, no output schema), the description covers all essential aspects: purpose, usage context, storage behavior, persistence, and companion tools. No gaps remain for effective use.

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

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

The schema covers both parameters with descriptions (100% coverage). The description adds value by providing example key formats ('subject_property, target_ticker') and value types ('findings, addresses, preferences, notes'), which aids in understanding proper usage beyond the schema's brief 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 'Save data the agent will need to reuse later' with specific verb 'Save' and resource 'data' (key-value memory). It distinguishes from siblings like 'subscribe' by specifying key-value pair scoped by identifier and cross-session reuse, differentiating it from other tools.

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

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

The description explicitly says when to use ('when you discover something worth carrying forward') and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' It also clarifies the benefit ('so you don't have to look it up again'), giving clear context for choosing this tool over others.

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 discloses meaningful behavior: graceful degradation when GLEIF/OpenFIGI are unavailable, returning unresolved identifiers explicitly rather than omitting them, and asserting nothing when a name matches multiple instruments (returning figi_candidates instead). These details materially shape invocation and interpretation of results.

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 informative but is written as one extremely long, run-on paragraph with many parenthetical asides. It is front-loaded with purpose and use guidance, yet the lack of structure makes it harder to scan quickly. Every sentence earns its place, but the formatting does not.

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 no output schema, the description covers the essential invocation context comprehensively: input formats, supported entity types, ambiguity handling, unresolved identifiers, source labeling, ISIN-to-LEI behavior, and graceful degradation. An agent has enough context to use this tool correctly in most situations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: it explains entity types in depth, gives valid value examples for both company and drug, and warns against passing full noun phrases like 'revenue bonds' because the FIGI lookup matches instrument names. This goes well beyond the schema's short 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 opens with concrete user phrasings and states a specific job: resolving a name to the canonical identifiers other tools need. It explicitly differentiates this from ordinary search by declaring 'Use FIRST whenever you have a name but need an ID,' so an agent can tell it apart from siblings like entity_profile or search.

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

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

The description gives a clear triggering condition: whenever the user has a name but needs an ID, use this tool first. It also notes that one call replaces several manual lookups. It does not explicitly name alternative sibling tools or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by detailing the probing process, ranking, and output fields (ranked list with score, confidence, signal density). No contradictions.

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

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

Three sentences, each earning its place: main action, use case, output summary. No wasted words, front-loaded with 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?

With no output schema, the description still explains the return type (ranked list with score, confidence, signal density). All key aspects covered: purpose, parameters, usage, 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 coverage is 100%, but the description adds meaning: entities[0] is treated as 'subject' for narrative, models default to workers-ai, _apiKey is conditional. This enriches 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 it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities.

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling list.

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

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

The description adds significant behavioral context beyond annotations: explains partial failures, the 5-30s first measurement for bundlephobia, and the sources_failed list. It also confirms the idempotent, read-only nature, 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 dense but well-structured: purpose first, then details, usage guidance, limitations, and edge cases. Every sentence adds value. 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?

Even without an output schema, the description lists all return fields (summary block, advisories, links, alternatives). It covers inputs, behavior, partial failures, and timestamp expectations, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example of scoped packages (`@types/node`) and clarifying that omitting version defaults to latest. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by being specific to npm dependencies in v1.

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

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

The description explicitly says when to use this tool: when an agent asks about safety, popularity, size, or cost of adding a package. It also notes the NPM-only scope and mentions fallback tools for other ecosystems.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds context about searching across all providers and return format, but no additional behavioral traits beyond what annotations convey.

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

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

Description is a single concise sentence that conveys the core purpose. Could be slightly more structured but is 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?

With low complexity, full schema coverage, and output schema present, the description sufficiently covers what the tool does and returns.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds no new meaning beyond the schema.

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

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

Description clearly states it performs full-text search across all providers and returns series with codes and labels. However, it does not differentiate from sibling tools like 'search_within' or 'find_series'.

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

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

No explicit guidance on when to use this tool versus alternatives. Sibling tools exist but no mention of their distinctions.

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

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

Annotations already indicate safe (readOnly, idempotent, openWorld, not destructive). Description adds valuable behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' 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?

A single, well-structured paragraph that front-loads the purpose and concisely covers usage, behavior, and limitations. 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 explains return format (passages with offsets and scores). Covers limitations (200K char cap, truncation flag). Complete for a tool with such clear annotations and 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?

Schema coverage is 100%. Description adds examples ('e.g. a SEC 10-K body, an article, a long tool result'), example queries ('supply-chain risk', 'fiscal year 2024 revenue'), and default for limit (5).

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and specifies inputs (text + natural-language query) and outputs (top-N passages with character offsets and similarity scores). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative workflow: 'Pair with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 and idempotentHint=true, which are consistent with creation. The description adds OAuth requirement, delivery caps (10/day for SMS), and webhook signing details 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 thorough but slightly verbose. It front-loads the main purpose and then organizes types and delivery details logically.

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

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

The description covers all parameters, delivery options, prerequisites, and even webhook signing. No output schema, but return value (subscription id) is mentioned.

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

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

With 100% schema coverage, the description adds rich details for each parameter (e.g., type-specific params, delivery channel constraints) that greatly aids understanding.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It differentiates from sibling tools like unsubscribe and list_subscriptions by specifying creation behavior.

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

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

It explicitly requires a Pipeworx OAuth account and lists supported types with examples, providing context for use. However, it lacks explicit guidance on when not to use or comparisons with alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant context by explaining it draws examples from a live catalog of thousands of tools and returns exact tool+argument shapes. No contradictions with annotations.

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

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

The description is front-loaded with core purpose, then efficiently elaborates on output, parameter usage, and when to invoke. Every sentence serves a purpose without redundancy, balancing completeness with 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?

Given the tool's simplicity (one optional parameter, no output schema) and its role as an onboarding tool, the description provides all necessary information: what it returns, how to use it, and its context relative to other tools. The output format is implied clearly enough for an agent to understand the result structure.

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

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

The input schema covers the single optional parameter with 100% description coverage. The description adds value by listing example topic values (finance, pharma, etc.) and explaining the behavior difference between omitting and providing the topic argument, which 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 clearly states the tool is an onboarding entry point for agents new to Pipeworx, listing multiple user intents and explicitly describing its output (category-bucketed example questions with tool+argument shapes). It effectively distinguishes from siblings like ask_pipeworx or discover_tools by positioning itself as a first-use guide.

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 tool explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without the topic argument. Although it doesn't list specific alternatives or when-not-to-use, the guidance is clear and practical for the intended use case.

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

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

Adds behavioral context beyond annotations: cancellation is a mutation (consistent with readOnlyHint=false), deactivation not deletion (consistent with destructiveHint=false), and preserves historical events via recent_alerts. Provides ownership enforcement detail.

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 concise sentences, each adds unique value: action, ownership constraint, deactivation vs deletion, historical preservation. No fluff or 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?

Covers input (id), behavior (cancellation, ownership, deactivation), and consequence (history available via recent_alerts). Lacks handling of edge cases (e.g., invalid id), but sufficient for a simple tool with clear 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?

Only one parameter 'id' with schema description already covering it ('Subscription id (uuid) returned by subscribe'). Description does not add new parameter details beyond the schema, so baseline 3 applies.

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

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

Clearly states 'Cancel a subscription by id', using a specific verb and resource. Distinguishes 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?

Specifies ownership enforcement ('only cancel your own subscriptions') and notes the row is deactivated not deleted, providing clear context on when to use and what happens. Does not explicitly mention alternatives but sufficient guidance.

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

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

Beyond the read-only/idempotent annotations, the description reveals critical behavior: the SEC EDGAR fast path vs. grounded pipeline, the full set of verdicts, and the crucial distinction that could_not_verify means the check did not happen and must not be treated as evidence. It also explains unsupported as 'we looked and cover no source' — nuanced context a caller needs.

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 contributes: query patterns, use case, dual routing, return contract, error semantics, and efficiency note. It front-loads the purpose and ends with a comparative benefit. Length is justified by the tool's complexity.

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

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

With no output schema, the description fully specifies the return payload (verdict, actual value, citation, reasoning) and explains the two failure modes (could_not_verify, unsupported). It also covers the tolerance override and routing rules, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving a concrete example for claim ('Apple's FY2024 revenue was $400 billion') and explaining tolerance_pct's default behavior ('implied by wording, capped at 5') and its use for hallucination detection. This is practical guidance 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 opens with concrete natural-language query patterns ('Is it true that…', 'fact check') and states it performs 'natural-language claim verification against authoritative sources', returning a verdict. This clearly identifies the verb (verify) and resource (claims), and distinguishes it from sibling tools that search or retrieve information without issuing a judgment.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives guidance for two claim types (company-financial vs. other) and notes it 'Replaces 4–6 sequential calls', indicating when it is the efficient choice. The description does not name alternatives but the when-to-use instruction is unambiguous.

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