Base64

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds operational transparency: default model (Workers AI, free), BYO key for Anthropic, and per-model return structure (score, confidence, signals, raw_response). 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 three sentences, front-loading the primary purpose and output. Every sentence adds necessary information (what it does, default model, return values, use cases). No wasted words.

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

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

Given 4 parameters, no output schema, and no nested objects, the description is highly complete. It explains return structure (per-model fields + combined view), default behavior, optional key usage, and typical use cases. The tool is well-differentiated among many siblings.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default model behavior and the API key usage ('passed straight through to api.anthropic.com'), which is not fully captured in schema descriptions. This helps agents understand parameter semantics beyond the schema.

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

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

The description uses specific verbs ('Probe', 'score') and clearly identifies the resource (LLMs about a business/brand/product/topic) and the output (visibility score 0-100 per model). It effectively distinguishes itself from sibling tools like ask_pipeworx or compare_entities which serve different purposes.

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: AI-marketing audits, brand checks, competitive monitoring. It also explains when to use the _apiKey parameter (to probe Anthropic). However, it does not explicitly mention when not to use this tool or point to alternative sibling tools, though the context is sufficient.

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

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

Annotations already cover read-only, idempotent, and open-world properties, so the description only needs to add non-obvious behavior. It discloses that the tool routes to one of 5,743 sub-tools across 1,500 sources, fills arguments, and returns answers with stable 'pipeworx://' citation URIs. This gives the agent an accurate mental model of the call's effect and result. It does not mention failure modes, but that is beyond what is expected given the annotations.

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

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

The opening is strong and front-loaded with the preference over web search and the list of supported domains. However, the description becomes redundant: the same set of example questions and the 'START HERE' phrase appear twice, with the final 'Examples: ...' dangling and unexplained. This repetition wastes tokens and reduces clarity, making the text less concise than it should be.

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

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

For a complex routing tool with no output schema, the description is largely complete: it explains purpose, mechanism, when to use, and the shape of the response. The main gap is the absence of guidance for choosing among sibling tools named 'ask_pipeworx_beta' and 'ask_pipeworx_grounded', which could confuse an agent deciding between them. Annotations and aliases are also well-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?

The input schema is fully described (100% coverage): the main 'question' parameter is documented along with five aliases, so the schema carries the semantic load. The tool description adds no parameter-specific constraints, though its examples (e.g., 'current US unemployment rate') illustrate valid question forms. Per baseline rules for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly identifies the action: it routes the user's question to an appropriate tool among 5,743 tools and returns a structured answer with citation URIs. It also lists specific domains (SEC filings, FDA, FRED/BLS, etc.), making the tool's function concrete. However, it never differentiates this tool from sibling variants 'ask_pipeworx_beta' and 'ask_pipeworx_grounded', so an agent may be unsure which variant to choose.

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 opening line 'PREFER OVER WEB SEARCH' explicitly names the primary alternative and the conditions under which to choose this tool ('questions about current or historical data', 'anything requiring authoritative structured data with citations'). It goes further with 'Use whenever the user asks "what is", "look up", ... even if web search could also answer it', giving clear trigger patterns. No exclusions are stated, which is acceptable for a default question-answering 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?

The description adds substantial behavioral context beyond annotations: it is a beta edge router, currently has no active candidate so it matches ask_pipeworx exactly, falls back to nothing, and is a full working router. This is unusually transparent about experimental state and expected 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 front-loaded with the beta purpose and contains no wasted sentences. Some redundancy exists between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but the detail about candidate state earns its place.

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

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

For a complex routing tool with no output schema, the description explains current behavior, experimental status, no fallback, and how to use it. It is complete enough for safe invocation, though it could mention the grounded sibling for fuller decision-making context.

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

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

Schema description coverage is 100%, and the input schema already documents the question parameter and its aliases. The description adds only that this tool takes the same arguments as ask_pipeworx, which does not meaningfully extend parameter understanding.

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

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

The description clearly identifies this as a beta universal router identical to ask_pipeworx, with routing improvements under test. It distinguishes itself from the stable ask_pipeworx router, but does not explicitly differentiate from ask_pipeworx_grounded, so sibling differentiation is incomplete.

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

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

The description explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, and explains that results are compared against the stable router. It does not state exclusions or when to choose ask_pipeworx_grounded, so it lacks full when-not 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 by disclosing the return contract, the explicit refusal object, the refusal reasons, the extra LLM call cost, and the hard constraint that answers use only the tool result. It also explains the evidence field is a verbatim quote. None of this is available from the annotations alone, and it gives the agent an accurate model of how the tool behaves.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, return contract, refusal behavior, use cases, and cost/alternative are all covered. The most important distinguishing fact is front-loaded, and the guidance ends with a practical preference rule. No filler or repetition.

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

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

Given there is no output schema, the description fully compensates by specifying the success and refusal response shapes, the meaning of evidence, and the possible refusal reasons. It also covers selection logic, cost trade-offs, and when to prefer a sibling. An agent has everything needed to decide whether and how to invoke this 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%: all six parameters are documented as aliases for the natural-language question, with the main 'question' parameter fully explained. The description adds no parameter-level detail beyond this, but it does not need to because the schema already carries the full semantic load. 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 opens with a specific, differentiating purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly identifies the tool as a grounded variant of ask_pipeworx and explains its exact behavior: selecting a tool, fetching data, and extracting answers only from the result. This is more than a generic statement and cleanly separates it from siblings like ask_pipeworx and ask_pipeworx_beta.

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

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

The description gives explicit when-to-use guidance: use when answers will be 'quoted, cited, or acted on' and the agent must not invent facts, with concrete domains listed. It also names the alternative, ask_pipeworx, and gives a clear preference rule: 'prefer ask_pipeworx for casual lookups.' This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safe operation. The description adds context of 'keyless, offline', which reveals no external dependencies and local execution. This extra information enhances transparency beyond the annotations, though no mention of error handling or output format is included.

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

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

The description is a single sentence that efficiently communicates the core action and key constraints. It is appropriately front-loaded and contains no extraneous words, earning its place with every part contributing to clarity.

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

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

For a simple decoding tool with no output schema, the description adequately specifies the input encodings and default variant. It mentions the output format (UTF-8 text) implicitly. However, it does not address behavior for invalid input or error cases, leaving minor gaps in completeness.

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

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

Schema description coverage is 100%, with both 'data' and 'variant' documented in the schema. The description mentions setting variant and the default base64, but the schema already lists the default. Thus, the description does not add significant meaning beyond the schema, meeting the baseline for full coverage.

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

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

The description clearly states the tool decodes multiple encodings (Base64, Base64URL, Base32, Hex) to UTF-8 text, with explicit mention of being keyless and offline. The verb 'Decode' and resource enumeration provide specificity, and the tool distinguishes from its sibling base64_encode via opposite functionality.

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

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

The description implies usage for decoding encoded strings but offers no explicit guidance on when to use this tool versus alternatives. It does not specify when not to use it or mention any prerequisites. The context of sibling tools includes base64_encode, but the description itself lacks comparative guidance.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description adds that the encoding is keyless and offline, providing extra behavioral context. 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 extremely concise: two sentences that clearly state the purpose and mention the parameter. It is front-loaded with the core functionality and contains 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 encoding tool with no output schema, the description provides sufficient context: input type (UTF-8 text), available encoding options, and key properties (offline, keyless). It is complete enough for an agent to understand the tool's capabilities.

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 mentions the default for 'variant' (base64), adding a small amount of value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: encoding UTF-8 text to Base64, Base64URL, Base32, or Hex. It specifies that the operation is keyless and offline, and the sibling tool base64_decode provides the inverse, making the purpose distinct.

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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., base64_decode). However, the purpose is clear from the description, and the agent can infer usage from the naming and context. No exclusion criteria or suggested contexts are mentioned.

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 thoroughly discloses behavioral traits beyond annotations: fan-out logic by category, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety guards for low-confidence matches, and resolution-rule risk. No contradictions with annotations.

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

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

The description is verbose, containing extensive detail on classifiers, fan-out examples, and edge cases. While structured with sections and front-loaded with purpose, it could be trimmed without losing essential 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?

Given no output schema, the description fully explains return fields (result.market, result.analysis, result.evidence, etc.) and all edge cases (low-confidence, closed markets, wide spreads, resolution rules). Covers all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining market input types, depth defaults ('Default thorough'), and include_raw recommendations ('keeps responses under ~20KB'), which are not in the schema.

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

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

The description specifies the tool's purpose with a clear verb-resource combination ('Research a Polymarket bet') and distinct input flexibility (slug, URL, question text). It differentiates from sibling tools by detailing a comprehensive fan-out to multiple data sources, which is unique among Polymarket-related 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?

Explicit use cases are given ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). The description provides context for when to expect certain outcomes (e.g., low-confidence matches, closed markets), but it does not explicitly exclude alternative tools for related tasks like arbitrage or edge tracking.

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. The description adds valuable context: it fetches latest 10-K data with correct off-calendar fiscal year handling, returns sorted results by primary metric, and includes citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries, then explains when to prefer this tool, then details data sources and sorting. Every sentence provides value, though the example list is slightly verbose. Still, it is efficient for the amount of information conveyed.

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 compensates by stating returns 'paired data + pipeworx:// citation URIs per entity' and mentions sorting by primary metric. For a comparison tool, this covers key behavioral aspects, though it omits exact return format or pagination limits.

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 both parameters. The description significantly enriches meaning by explaining that type='company' pulls financial metrics and type='drug' pulls adverse-event counts. It also clarifies the values parameter format (tickers/CIKs for company, names for drug), going beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, listing example query patterns and specifying data sources (SEC EDGAR for companies, FAERS for drugs). It effectively distinguishes itself from sibling tools like entity_profile which handle single 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides concrete example queries. While it lacks explicit when-not-to-use scenarios, the guidance is strong and clear for comparison tasks.

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 by explaining decomposition, parallel routing, return packet contents, explicit gaps[], contradiction[], hop fields, citation_uri fetchability, semantic excerpting, latency expectations, and plan-based depth behaviors. It also discloses that citations are only included when actually fetchable, which is useful 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?

Although long, the description is front-loaded with the most critical operational constraint (account requirement and fallback) and every subsequent sentence adds useful information about selection, behavior, output, or limitations. No filler or tautology.

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 compensates by covering return fields, citation behavior, gap handling, contradiction reporting, latency, authentication, and alternatives. Given the tool's complexity, nothing essential is missing for an agent to select and invoke it correctly.

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

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

The schema already documents both parameters fully at 100% coverage, so the baseline is 3. The description adds meaning by explaining what each depth level actually does (standard gap recovery, thorough multi-hop and contradictions scan), that thorough requires a paid plan, and expected latency implications.

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

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

The description clearly states that deep_research performs 'Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources' in a single call, and explicitly distinguishes itself from open-web search. It also identifies the sibling ask_pipeworx for single-lookup cases, so an agent can tell which tool fits.

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

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

Usage guidance is explicit: if not signed in, use ask_pipeworx instead; deep_research is best for broad/multi-part structured-data questions; and for a single lookup, prefer ask_pipeworx because deep_research returns mostly empty gaps for topics outside its structured catalog. This gives clear when-to-use and when-not-to-use direction.

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 and destuctiveHint=false, so safety is covered. The description adds that it returns top-N most relevant tools with full schemas and curated examples, ready to call—useful behavioral context beyond annotations.

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

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

The description is front-loaded with purpose and usage guidelines. It lists many domains in a dense format but remains understandable. Slightly wordy but effective.

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

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

For a discovery tool with 6 parameters (many aliases) and no output schema, the description explains the return value (names, descriptions, schemas with examples) and readiness to call. It does not mention pagination or rate limits, 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 description coverage is 100%, so the schema already documents all parameters including aliases. The description does not add significant parameter-level meaning beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool finds tools by describing a data or task, listing specific domains (SEC filings, financials, FDA drugs, etc.). It explicitly distinguishes itself from sibling tools by instructing to call this FIRST to see the option set.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use context. It does not explicitly state when not to use, but the implied purpose is sufficient.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations by explaining the fan-out across EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, news, and GLEIF. It also clarifies that empty sections mean real absence of data via sources_used/sources_failed, that private companies return resolved:false with a notes line, and that FDA absence is expected for small-molecule-only companies.

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 strong examples and a clear 'ALWAYS PREFER' heuristic, but the middle section is a dense run-on chain of semicolon-separated output fields and parenthetical caveats. Every sentence is informative, but the structure makes quick scanning harder than necessary for such 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?

There is no output schema, so the description carries the full burden — and it largely succeeds. It identifies the main returned fields (cik, company_name, recent_filings with URIs, fundamentals, sources_used/sources_failed) and covers edge cases such as private companies, name resolution, and expected empty data sections.

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 real value by stating that type='company' and type='ticker' are interchangeable, that value may be a ticker, zero-padded CIK, or company name, and that name resolution happens via SEC EDGAR's company-name match with resolved_from/resolved_to in the response.

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

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

The description states a specific verb and resource: 'full cross-source profile of a US public company in ONE parallel call.' Example queries like 'Tell me about X' and 'brief me on Tesla' anchor intent, and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' distinguishes it from sibling lookup 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?

It gives an explicit trigger condition — 'when the user asks for a holistic view' — and directs the agent to prefer this tool over chaining single-pack SEC/XBRL/news lookups. It lacks a crisp 'when not to use' statement for narrow, single-document or single-source requests, though that is reasonably implied.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds usage context 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?

Two sentences, front-loaded with action, no wasted words. Efficient and clear.

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

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

Simple tool with one parameter and annotations present. Description covers purpose, usage, and pairing. No gaps for this complexity.

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

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

Schema coverage is 100% with a single parameter 'key' fully described. Description adds no extra parameter meaning beyond 'by key'.

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' with a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly lists when to use: stale context, task done, clear sensitive data. Mentions pairing with remember and recall, but no explicit when-not 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 declare readOnlyHint and idempotentHint; the description adds that it fetches the page, extracts title/description/links, and outputs a single text blob, providing useful behavioral context beyond annotations.

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

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

Two concise sentences plus a use-case sentence, 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 tool with 2 parameters, full schema coverage, and no output schema, the description adequately explains what the tool does and what output to expect (a text blob).

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

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

Schema coverage is 100% and description adds context: url is a full URL to summarize, max_links has default 25 and max 50. This meaningfully supplements 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 generates an llms.txt file for a URL, using specific verbs and resource. It distinguishes from all sibling tools (none of which generate llms.txt).

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

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

The description provides explicit use cases (client's site, own project, auditing competitor) but does not mention when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds no contradictory information and provides additional context on return fields, but no extra behavioral traits beyond annotations.

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

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

Two sentences front-loaded with purpose and return fields, followed by usage guidance. No wasted words.

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

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

For a simple list tool with one optional param and good annotations, the description covers what the tool returns, when to use it, and aligns with schema and annotations.

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

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

Schema coverage is 100% with a single well-described parameter. The description does not add parameter details, but given high coverage, baseline 3 is appropriate.

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

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

Clearly states the verb 'List' and resource 'the caller's active subscriptions'. Distinguishes from siblings like subscribe and unsubscribe by specifying it lists subscriptions for review or cancellation.

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

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

Provides explicit usage guidance: review before adding more subscriptions or to find an id to cancel. Does not explicitly name alternatives but context is clear.

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

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

Annotations are all false and provide no safety profile, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota independence ('doesn't count against your tool-call quota'), and the claim_token mechanism, including how to retrieve status later. It also states the team reviews digests daily, making side effects and expected response behavior clear.

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

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

The description is long but front-loaded with purpose and followed by logically ordered sections: usage categories, exclusions, content guidelines, and operational details. Every sentence contributes unique information, and the length is justified by the tool's claim_token and rate-limit complexity. It could be slightly tighter, but nothing is wasted.

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

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

For a feedback tool with nested context, no output schema, and unhelpful annotations, the description is self-sufficient. It covers all invocation scenarios, exclusions, token handling, rate limits, and content best practices. An agent has everything needed to decide when to call and how to construct arguments 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%, so the baseline is 3, but the description adds meaningful semantic guidance: it instructs the agent to describe issues in terms of Pipeworx tools/packs and specifically not to paste the end-user's prompt. It also demonstrates claim_token usage with an example call, which goes beyond the schema's static description. This adds value without redundancy.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly differentiates from sibling tools by scoping exclusively to Pipeworx tools and explicitly stating that issues with other MCP servers should be filed elsewhere. This is unambiguous and action-oriented.

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 when-to-use guidance with concrete categories (bug, feature, data_gap, praise) and a clear exclusion rule: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' It even offers a fallback for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists.'). This is exemplary usage guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: self-aggregating, no PII, caching behavior (5min-1h). This 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?

Concise, front-loaded with core purpose, then use cases, then technical details. No redundant sentences. 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 mentions return fields (tools, packs, volume). Could be slightly more explicit about format, but sufficient for an agent to understand what to expect. Caching and PII details add completeness.

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

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

Schema covers the only parameter (window) with enum and description. The tool description adds meaning by explaining the trade-off: shorter windows for current trends, longer for steady-state demand. Adds value beyond schema.

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

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

Clearly states it returns top tools, packs, and call volume over a window. Specific verb ('returns') and resource ('trending usage on Pipeworx'). Distinguishes from sibling tools like ask_pipeworx (question-answering) and discover_tools (tool discovery) by focusing on trending data.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use case with demand. Does not explicitly mention when not to use or compare to alternatives, but the use cases are clear and context-appropriate.

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

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

Annotations indicate read-only, open-world, idempotent. Description adds deep behavioral context: partition check mechanics (sum of YES prices ≈1, deviation >3pp triggers signal), semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), and fill check against live CLOB depth. 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?

Front-loaded with purpose, then structured by mode. Dense but informative; could be slightly more concise but no wasted sentences. Capitalization and layout aid readability.

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

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

No output schema, but description details the response structure for both modes (opportunities array, partition_check fields, fill check). Covers edge cases (placeholder filtering, thin legs, custom sizing via sibling). Contextually complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds further meaning: event parameter accepts slugs or full URLs, topic parameter examples, and clarifies that each mode triggers different scanning logic. Exceeds schema value.

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

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

Clearly states 'find arbitrage opportunities via monotonicity violations + partition-sum checks'. Distinguishes three modes (no args, event, topic) and differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event mode for a specific market and explains cross-event mode's advantage. Also warns when not to trade (realizable_edge_pp ≤ 0).

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

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

The description adds substantial behavioral context beyond the annotations, including caching at the KV level per knob combination, diagnostic output to explain empty segments, and a 24h-move warning. It explains model families and their assumptions, as well as rare-by-design behavior for concentrated longshots. 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 very long and detailed, covering model families, output structure, and caching. While every sentence adds value, the length may overwhelm agents. It is front-loaded with purpose but could be more concise by trimming redundant explanations of knobs already documented in the schema.

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 (9 parameters, no output schema, nested response), the description is extremely thorough. It explains the by_segment output, fed_candidates, diagnostics, and edge fields like edge_pp_net and kelly_fraction. It also details why Fed bets are excluded and caching behavior, leaving no ambiguity about return values.

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

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

All 9 parameters have descriptions in the input schema (100% coverage). The tool description adds additional context for some parameters (e.g., slippage_pp explains Polymarket fees; min_partition_leg_kelly explains its specific application). However, the description focuses more on the output and methodology than parameter details.

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 top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage 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 it is built for 'what should I bet on today' and explains three response segments. It provides guidance on using knobs like min_liquidity and max_spread_pp to filter tradeable edges. However, it does not explicitly compare to alternative tools or state when not to use it.

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

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

The description discloses behavioral traits beyond annotations: reads snapshots, is non-destructive, explains data availability (cache-miss snapshots) and limits (60-day TTL). Annotations already indicate readOnly and openWorld, and the description adds 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 fairly long but front-loaded with the key question and every sentence adds value. Slight room for tightening, but overall well-structured.

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

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

For a tool with no output schema, the description comprehensively details the response structure (tracked[], expired[], snapshot_dates[]) and all relevant aspects. Covers complexity adequately.

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 both parameters with descriptions (100% coverage). The description adds semantics like default and max values, and previews the response structure, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry, answering how long edges have existed and if they are shrinking. It specifies the verb 'answers' and the resource 'edge persistence', distinguishing it from sibling tools like 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 implicitly explains when to use (when needing edge persistence info) and provides context about fresh vs. old edges. However, it does not explicitly state when not to use or alternatives.

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

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

Annotations already show readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context about forced directional risk, thin legs, and the dominant loss mode, without contradicting annotations.

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

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

The description is lengthy but well-structured with clear sections for single-market and basket modes. Each sentence adds value, though minor redundancy exists (e.g., repeating 'default 1000').

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 4 params, no output schema, and high complexity (CLOB depth, basket mode), the description thoroughly explains return fields, edge cases, and safety warnings, making it 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%, baseline 3. The description adds meaning by explaining modes (single-market vs basket), default auto detection for basket side, and interpretation of size_usd for both modes, justifying a 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes with specific verbs and resource names.

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

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

Explicitly states when to use: 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about risks of thin books and partial fills, providing clear context.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations. It discloses the matching methodology, the meaning of compatibility codes, the null semantics of temporal_alignment, the gross-vs-net fee limitation, and the skipped-comparison counters. It even warns that safety fields can be non-empty even when matched_pairs is positive.

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

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

The description is long, but it is organized into recognizable sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and every sentence carries substantive caveats or operational guidance. It is front-loaded with purpose and modes before diving into edge cases. A bit of redundancy exists, but the density 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 full responsibility for explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, per-entry flags, compatibility fields, skipped counters, temporal_alignment, and fees_note. Given the tool's complexity and the absence of an output schema, nothing needed for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic context: topic is one of ten pre-mapped shortcuts that auto-fetch matching events, explicit parameters override the topic-mapped side, and both modes run the identical token-overlap matcher. This adds behavioral nuance the schema alone does not provide.

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

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

The description opens with a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also clearly frames what makes this tool distinct from siblings like polymarket_arbitrage or polymarket_edges: it is venue-to-venue, question-to-question spread analysis with explicit compatibility disclosure.

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 clear, actionable usage context: two modes, topic shortcuts vs explicit ticker/slug pairings, and the warning that pre-mapped topics frequently return compatibility warnings and are not automatically tradeable. It does not explicitly name alternative sibling tools for when this tool is the wrong choice, so it stops short of full when-not guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about scoping and behavior when key is omitted, complementing annotations without contradiction.

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

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

Two sentences, front-loaded with the core action, followed by usage guidance. 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 simple tool with one parameter and no output schema, the description fully covers functionality, usage context, scoping, and sibling relationships.

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 one optional parameter. The description clarifies that omitting the key lists all keys, adding value beyond the schema 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: retrieve a value by key or list all keys. It specifies the verb 'retrieve' and resource 'memory', and distinguishes from sibling tools 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 explicitly says when to use it: to look up context stored earlier without re-deriving. It also mentions scoping and pairing with remember/forget, providing clear 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?

Description implies that mark_read:true modifies state (flags events read), contradicting the readOnlyHint annotation which indicates no state changes. This is a direct contradiction, so score is 1.

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 paragraph, efficiently conveying purpose, filters, and extra context. Could be more structured, but not overly verbose.

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

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

No output schema, but description specifies returned fields (source, citation_uri, raw event payload). Covers filtering and mark_read behavior. Adequate for a read tool with good annotations, but missing explicit return format.

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

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

Schema covers all 5 parameters with descriptions. Description adds minor context (e.g., mark_read effect on subsequent calls) but does not significantly enhance beyond schema, maintaining baseline 3.

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

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

Clearly states it pulls fired events from subscription feed, returns recent alerts with specific fields, and describes filtering options. Distinguishes itself from sibling tools like 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?

Mentions polling works fine and points to an alternative HTTP endpoint for scripts/dashboards. Provides context for when to use, but lacks explicit when-not or exclusion criteria.

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

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

Discloses fan-out to multiple sources, fallback logic, USPTO soft-fail condition, and output format with citation URIs. No contradiction with annotations.

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

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

Front-loaded with query examples and packed with useful detail. Slightly long but every sentence earns its place.

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

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

For a complex tool with multiple sources, fallback, and no output schema, the description covers return format, source grouping, and citation URIs completely.

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

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

Schema coverage is 100% with descriptions. The description adds value by documenting relative shorthand for 'since' and typical usage ('30d' or '1m').

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

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

The description clearly states it is a change feed for a company, returning filings, news, and patents. It uses specific verbs ('fans out', 'returns') and distinguishes from sibling tool entity_profile.

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

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

Explicitly says when to use this tool vs entity_profile. Provides example queries and explains fallback behavior from GDELT to GNews.

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 idempotentHint=true and destructiveHint=false. The description adds context: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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?

Four concise sentences, front-loaded with purpose. Every sentence adds value with 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?

Despite lacking an output schema, the description explains storage behavior, persistence, and lifecycle (save, recall, forget), making it complete for a simple write tool.

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

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

Schema coverage is 100% with clear descriptions. The description does not add extra parameter semantics beyond what is in the schema, 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 purpose: 'Save data the agent will need to reuse later'. It specifies the resource (data for reuse) and distinguishes from sibling tools like recall and forget.

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

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

Explicit guidance on when to use: 'when you discover something worth carrying forward'. Mentions pairing with recall and forget, but does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds substantial behavioral detail: cascading lookups, ambiguous matches returning figi_candidates, explicit unresolved identifiers, source labeling, and graceful degradation. This goes well beyond the structured hints.

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

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

The description is long but front-loaded with examples and 'Use FIRST', and organized by SUPPORTED TYPES. There is some redundancy between the opening line and the later 'Use FIRST whenever...' sentence, and the dense parentheticals make it heavier than strictly necessary, though every major detail serves a purpose.

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

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

For a two-parameter tool with no output schema, the description covers accepted input forms, supported types, ambiguity behavior, unresolved identifiers, and failure degradation. An agent has all the information needed to call it correctly in realistic name-to-ID scenarios.

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?

Although schema coverage is 100%, the description adds critical meaning beyond the schema: 'Pass the ENTITY NAME ONLY', the bond-issuer-as-printed rule, that trailing security-class words match nothing, and that ISIN inputs resolve via GLEIF to the legal entity. This materially improves correct invocation.

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

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

The description states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes this from sibling tools by presenting it as the first-step lookup utility, with supported entity types listed explicitly.

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 trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains when enrichment degrades gracefully, so the agent knows when results are still valid. It does not explicitly name an alternative tool to use instead, but the intended context is unambiguous.

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 explains the internal process (probes each entity with ai_visibility_check) and the return format (ranked list with score, confidence, signal density). This adds value beyond the annotations (readOnlyHint, idempotentHint, etc.) 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 two sentences plus a short example quote. Every sentence adds value: it states the main action, explains the process, and gives a concrete use case. No wasted words.

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

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

Despite no output schema, the description explains the output format (ranked list with score, confidence, signal density). It also covers constraints (2-8 entities, first as subject, optional models/apiKey/context). This is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema: it specifies that the first entity in 'entities' is treated as the subject, and it gives usage guidance for 'models' (omit for workers-ai). This helps the agent correctly invoke the parameters.

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

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

The description uses specific verbs (compare, probe, ranks, surfaces) and identifies the resource (AI visibility across entities). It clearly distinguishes from the sibling ai_visibility_check by being the multi-entity comparison version.

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 ('competitive AI-marketing audits') and includes an example question. It implicitly contrasts with ai_visibility_check (single entity) but 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 indicate readOnly, idempotent, safe. The description adds behavioral details: composite fan-out, partial failure graceful degradation, and specific timing (5-30s for new bundlephobia measurements). 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?

Single paragraph but well-structured, starting with purpose, then sources, usage guidance, return format, limitations, and edge cases. Dense but clear; could benefit from slightly more formatting but still effective.

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

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

No output schema, but description lists all return fields (summary block, details, links, alternatives) and explains partial failures. Both parameters are documented. Complete for an agent to understand tool behavior and output.

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

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

Schema coverage is 100% with descriptions for package and version. The description adds context: version defaults to latest when omitted, scoped packages accepted, and explains how parameters are used in the composite call. Adds value beyond schema.

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

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

The description specifies the tool as a composite check for npm packages, clearly stating the verb 'scan' and resource 'dependency'. It distinguishes from siblings by focusing on npm ecosystem and listing return fields. No ambiguity.

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

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

Explicitly states when to use: 'whenever an agent asks "is X safe / popular / small"'. Also provides a negative guideline: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', pointing to an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, return format (passages with offsets and scores). 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?

Four sentences, all substantive. Front-loaded with core purpose. No redundant or vague language. 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?

For a semantic search tool with 3 parameters and no output schema, the description covers behavior, technical details, limits, return format, and integration with sibling tool. 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 coverage is 100% with each parameter described. The description enriches the schema by explaining the role of 'text' (the fetched record), 'query' as a natural-language example, and 'limit' as top-N passages. This adds context 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 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and specifying the scope (inside a record).

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt'. Also explains alternative: 'Pairs 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?

The description adds significant behavioral context beyond the annotations, such as the need for a Pipeworx OAuth account, delivery channel specifics (webhook signing, auto-disable after failures), and type-specific parameter examples. 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 dense and well-structured, with each sentence adding value. However, it is somewhat lengthy; a more concise version could maintain clarity while reducing verbosity.

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, prerequisites, limitations, and return value (new subscription id). For a tool with no output schema, it provides sufficient context to understand expected behavior and constraints.

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 provides additional detailed examples and clarifications for each parameter (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02","1.01"]}') and elaborates on delivery channel constraints 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource combination that distinguishes it from sibling tools like unsubscribe, list_subscriptions, and recent_alerts.

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 on when to use the tool, including prerequisites ('Requires a Pipeworx OAuth account') and delivery channel limitations (e.g., '10/day cap' for SMS). However, it does not explicitly mention when not to use it or direct alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, nondestructive. The description adds significant behavioral context: returns example questions with exact tool+calls shapes, drawn from a live catalog. No contradictions.

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

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

The description is detailed but well-structured with front-loaded example queries and clear categories. Every sentence adds value, though the length could be slightly reduced without losing clarity.

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

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

For a discovery tool with no output schema, the description fully explains the return format (category-bucketed examples), the use case, and how to adapt via topic. Complete and 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 coverage is 100% with one optional parameter. Description adds valuable enumeration of topic values (finance, pharma, etc.) and explains the effect of omitting vs. providing a topic, going beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point, returns category-bucketed example questions, and explains its role. It distinguishes from siblings by being the first-use tool.

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

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

Explicitly states when to use this tool (first when unsure, to learn capabilities) and suggests an alternative focus via the topic parameter. Provides clear context for use.

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

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

Annotations already indicate non-destructive and idempotent. The description adds valuable detail: the row is 'deactivated (not deleted)' and historical events remain available via recent_alerts, which the annotations do not convey.

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

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

Two sentences, no redundancy, action first. Efficiently communicates purpose, constraint, and behavioral nuance.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and post-action behavior. No missing aspects for an agent to use it correctly.

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

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

Schema has 100% coverage with a clear parameter description for 'id'. The description echoes 'by id' but does not add new information beyond what the schema provides. Baseline score is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', directly aligning with the tool name and title. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and resource.

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 ownership constraint ('you can only cancel your own subscriptions') but does not explicitly mention when to use this tool versus other subscription-related tools. Still, it gives clear context for appropriate 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?

Beyond the readOnly/idempotent annotations, the description adds crucial behavioral detail: the distinction between 'could_not_verify' (check did not happen, must not be treated as evidence) and 'unsupported' (no source covers it). It also discloses the internal routing logic and that tolerance is capped at 5% by default, giving agents a fuller picture of tool 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 front-loaded with example triggers, then states the core use case, pipeline routing, return values, and error semantics. Every sentence earns its place—there is no fluff. It is dense but well-organized, making it easy for an agent to parse the essential information.

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

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

With no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning) and error handling. It also covers the two distinct operational paths and the meaning of each verdict category. Given the tool's complexity, this description is complete and self-sufficient.

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

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

The input schema provides 100% coverage for both parameters: 'claim' is described as a natural-language factual claim with examples, and 'tolerance_pct' is fully explained including its default. The description body itself does not add parameter-specific meaning beyond what the schema already says, so the baseline 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 gives a specific verb (verify, fact check) and resource (natural-language factual claims against authoritative sources). It clearly distinguishes this from sibling tools by focusing on producing a verdict. Examples like "is it true that" and "confirm or refute" immediately signal the tool's purpose.

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

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

Explicitly states when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two routing paths (SEC EDGAR for company financials, grounded pipeline for other claims), providing clear context for these different cases. The note about replacing 4–6 sequential calls further guides efficient usage.

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