Yesterdays Number

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant context: per-model return format (score, confidence, signals, raw_response), combined view, free default model, and BYO key for Anthropic with direct payment. 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?

Three sentences front-load the core action, then details, then use cases. No fluff; every sentence adds value. Efficient and 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?

Given no output schema, the description covers return format (per-model objects and combined view). It mentions signals and raw_response but does not detail what signals contain or confidence ranges. However, for a tool with good annotations, this is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining each parameter's purpose (e.g., entity is 'the thing to ask about', models is 'which models to probe'), and provides examples for entity and context. This goes beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). The verb 'probe' and resource 'LLMs/visibility' are specific. It distinguishes from siblings by focusing on AI visibility checks, as opposed to entity profiles or competitor scans.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains model defaults and the optional API key for Anthropic. However, it does not explicitly state when not to use this tool or name specific 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about routing behavior, filling arguments, returning citation URIs, and being a single fast call, which goes beyond the structured annotations without contradicting them.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and every section contributes—domain examples, query triggers, alternative tools, and scope notes. It could be tightened, but it remains efficient for a highly reusable default 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?

With no output schema, the description adequately explains the return value ('structured answer with stable pipeworx:// citation URIs') and covers availability ('works on every tier'). It provides enough context for an agent to decide whether to use this tool, what to expect, and when to choose alternatives.

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

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

Input schema covers 100% of parameters, with the description of 'question' already noting alias support. The tool description's inline examples illustrate usage but add no new parameter semantics beyond what the schema provides, 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 clearly identifies ask_pipeworx as the default routing tool for factual questions, with a specific verb ('routes') and resource (5,529 tools across 1,455 sources). It explicitly contrasts with siblings like ask_pipeworx_grounded and deep_research, making its unique role unmistakable.

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

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

It provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-to-escalate ('Step up only when needed' to ask_pipeworx_grounded or deep_research). It also covers breaking-news use, giving clear alternatives and exclusions.

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

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

The description discloses that the tool is experimental, currently matches ask_pipeworx exactly, and that routing improvements may be active live. It also clarifies it is a full working router, not a stub. This adds significant behavioral context beyond the annotations, with 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 sentences, each serving a distinct purpose: stating the version, current state, usage direction, and full functionality. No fluff, efficiently front-loaded with the core 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?

The description is complete for a simple tool with one string parameter and rich annotations. It lacks a detailed response format but compensates by stating 'same response shape' as ask_pipeworx. Given the complexity is low and annotations cover key safety traits, this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description references 'same arguments' as ask_pipeworx but does not add specific parameter meaning beyond what the schema already provides for the aliases and question field. Adequate but not enhanced.

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

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

The description clearly states this tool is a beta version of ask_pipeworx, acting as a universal router for 5,529 tools. It explicitly distinguishes it from the stable ask_pipeworx by its experimental routing improvements, making purpose unmistakable.

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

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

It explicitly says to use it like ask_pipeworx when you want the newest routing, and mentions results are compared against the stable router. It implies the stable alternative (ask_pipeworx) but does not explicitly state 'use ask_pipeworx when you need stability', so not a full 5.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses refusal behavior with specific refusal_reason enum values, evidence verbatim quoting, and the extra LLM call cost. This adds rich behavioral context not available from annotations alone.

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 multi-sentence but each sentence earns its place: purpose, mechanism, return format, usage guidance, and cost tradeoff. It is front-loaded with the core concept and avoids fluff, though slightly dense.

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 fully specifies the success return shape and all failure refusal reasons. It also covers the routing mechanism and when to use, making it complete for a complex grounded-answer tool.

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

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

The schema has 100% coverage with aliases for the question parameter, so the description doesn't need to compensate. It adds no new parameter details, but the baseline of 3 is appropriate as the schema fully documents the single required parameter.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb ('answer') and resource (Pipeworx tool routing). It distinguishes itself from sibling ask_pipeworx by emphasizing evidence extraction and refusal behavior, making its unique purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' and notes the cost tradeoff of an extra LLM call, giving clear guidance vs alternatives.

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

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

The description goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint). It details market resolution, fan-out logic, response shapes, resolver contract, parent event extraction, news error handling, safety checks (low-confidence, closed markets, wide spreads), 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 very long (550+ words) and includes extensive examples and edge cases. While well-structured with sections like SAFETY, RESPONSE SHAPES, etc., it could be more concise. Some redundant examples could be trimmed 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?

Given the tool's complexity (multiple data sources, edge cases, response variations), the description covers all important aspects: market resolution, classification, fan-out by category, response fields, resolver match confidence, parent events, news fallback, safety, cancellation rules. No output schema exists, but the description thoroughly explains return values.

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

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

The input schema covers all three parameters with descriptions. The description adds significant value: explains the 'depth' enum (quick vs thorough), defines market input formats (slug, URL, question text), and clarifies the 'include_raw' boolean effect (summary vs full payloads). This exceeds schema-only information.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via data pull). It distinguishes from sibling tools like polymarket_arbitrage or validate_claim by focusing on holistic research.

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

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

The description explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It also covers when not to use (low-confidence matches, closed markets). However, it does not explicitly name alternative tools for each scenario, so it's not a perfect score.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description explains that company comparisons pull latest 10-K financials with correct fiscal year handling, while drug comparisons pull FAERS/FDA/trial counts. It also mentions sorted results and citation URIs, adding valuable behavioral context.

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

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

The description is a single well-organized paragraph that front-loads example queries, then concisely covers behavior for both entity types. Every sentence adds value without repetition or fluff.

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

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

Despite no output schema, the description thoroughly explains return format (paired data with citation URIs) and covers all essential aspects: entity types, data sources, sorting, and efficiency gains. It provides comprehensive guidance 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?

With 100% schema coverage, baseline is 3. The description clarifies the 'type' parameter by distinguishing company vs drug data sources and provides concrete examples for the 'values' parameter (tickers/CIKs for companies, drug names for drugs), adding useful 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 clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call. It provides natural language examples and explicitly contrasts with sequential single-pack lookups, distinguishing it from sibling tools.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also details the data retrieved per entity type, providing 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 annotations (readOnly, openWorld, idempotent), the description discloses critical behaviors: account/payment requirements, parallel routing to 5,529 tools, return packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), explicit gaps[] for unanswered facets, a never-invented guarantee, hop fields, resolvable citation_uri, contradiction scanning, semantic excerpting, and latency expectations. This far exceeds the annotation baseline and provides extensive operational context.

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

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

The description is a single dense block with no paragraph breaks, but every sentence carries high-value information. It front-loads the critical account prerequisite and alternatives before the core purpose. While lengthy, it maintains relevance; however, better structure (e.g., bullet points for depth modes or return format) would improve scannability.

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

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

With no output schema, the description compensates by detailing the findings packet format, gaps[] and contradictions[] behavior, citation semantics (always fetchable), performance expectations, and grounding guarantees. It also covers all parameters, prerequisites, and when-not-to-use guidance, making it fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value by noting that depth 'thorough' requires a paid plan, and that 'broad/multi-part is fine — decomposition is the point,' enriching the schema's enum descriptions. It also clarifies the behavior of each depth option in terms of hops, gap recovery, and contradiction scanning, offering more context than 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 explicitly states 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and clarifies it is NOT open-web search. It also distinguishes from sibling tools by recommending ask_pipeworx for single lookups and breaking news, making the tool's purpose and scope unmistakable.

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

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

Usage guidance is explicit and actionable: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also includes prerequisites (account required, fallback if not signed in), leaving no ambiguity about when to use this tool vs alternatives.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive. The description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral context beyond annotations. No contradictions.

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

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

The description is relatively concise but includes a long list of domains which adds verbosity. It is front-loaded with the primary action, but the list reduces conciseness. Could be more structured.

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

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

Given no output schema, the description explains the return value (top-N tools with names, descriptions, schemas). It also provides usage guidance and covers the main parameter. Parameter count is high but most are aliases; the description covers the key aspects.

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 lists all parameters. The description does not add significant meaning beyond the schema; it mentions limit defaults and aliases already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by emphasizing discovery and a broad range of domains, and explicitly says to call this first when many tools are available.

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 specifies when to use: for browsing, searching, discovering tools, listing domains. It also says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' which guides usage. However, it lacks explicit when-not-to-use or alternative tool references.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses that patents soft-fail until May 2025, that names are not supported, and details each data source and return field. No contradiction with annotations.

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

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

The description is information-dense but slightly long. However, every sentence adds value, and the structure (examples, then details, then constraints) is logical and effective.

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

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

Given the tool's complexity (multiple sources, no output schema), the description is remarkably complete: it lists all return fields (cik, company_name, filings with URIs, fundamentals, patents caveat, news, LEI) and explains input 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?

With 100% schema coverage, the description adds significant meaning: explains that type is currently only 'company', value must be ticker or zero-padded CIK, and provides examples. This goes 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's purpose: to provide a full cross-source profile of a US public company in one parallel call. It uses examples like 'Tell me about X' and distinguishes itself from related tools like resolve_entity.

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

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

Explicitly states when to prefer this tool over chaining single-source lookups, and advises using resolve_entity first if only a name is available. Provides clear context for when to use and 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 mark it as destructive; description adds context about deleting stored memories and clearing sensitive data, adding value beyond annotations.

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

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

Two efficient sentences, front-loaded with key information, 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?

Covers purpose, usage, and relationships well for a simple tool; could mention permanence of deletion but destructiveHint already implies it.

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

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

Schema coverage is 100% and the single parameter 'key' is well-described; the description does not add further semantics, so baseline 3 is appropriate.

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

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

The description clearly states it deletes a memory by key, contrasting with siblings like 'remember' and 'recall'.

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

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

Explicitly lists scenarios for use (stale context, task done, clear sensitive data) and mentions pairing with other tools, but lacks 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations by explaining the internal process and output format.

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 two sentences plus a concise list of use cases. It is front-loaded with the primary purpose and efficiently conveys all necessary information without redundancy.

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

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

Despite no output schema, description fully explains the output (single text blob, markdown format, ready for site-root). It covers purpose, behavior, parameters, and use cases. Rich annotations compensate for any missing details.

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

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

Schema covers 100% of parameters with clear descriptions. The description adds no additional meaning 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?

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb ('generate'), resource ('llms.txt file'), and context ('for any URL, so AI crawlers can index the site cleanly'). It lists concrete use cases (client's site, own project, competitor audit), which distinguishes it from sibling tools like scan_competitor_ai_presence that have a different focus.

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

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

Description explicitly states when to use the tool via a bulleted list of useful scenarios. While it does not explicitly state when not to use or name alternatives, the provided context is sufficient for typical use cases.

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

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

Annotations already declare readOnly and non-destructive. The description adds context about return fields and usage purpose, which is valuable 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 with no redundancy. First sentence states purpose and output, second gives usage guidance. Efficient and front-loaded.

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

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

Given the simple tool with one optional parameter and rich annotations, the description adequately covers purpose, output, and usage. Could mention open-world or pagination, but not essential.

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 covers the only parameter (include_inactive) at 100%, so baseline is 3. The description doesn't add extra 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 clearly states the tool lists active subscriptions and specifies the returned fields. It differentiates from sibling tools like subscribe and unsubscribe by indicating it's for review before adding or to find an ID to cancel.

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

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

Explicitly says to use for reviewing monitored subscriptions before adding more or finding an ID to cancel. While it doesn't say when not to use, the sibling tools provide context for 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 are all false but give no safety profile. The description compensates by disclosing the claim_token flow, rate limit ('5 per identifier per day'), cost ('Free; doesn't count against tool-call quota'), and operational cadence ('team reads digests daily'). 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 longer than typical but every sentence earns its place: usage categories, exclusion for non-Pipeworx tools, token mechanics, rate limits, roadmap. It is front-loaded with the core purpose. The 'Not sure?' sentence could be trimmed slightly but remains useful.

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 4-param tool with no output schema, the description covers what to report, how to structure feedback, how to retrieve resolution status, rate limits, cost, and channel. It also handles the no-account edge case with claim_token. An agent has everything needed to invoke correctly.

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

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

Input schema already documents all 4 parameters with descriptions (100% coverage), so baseline is 3. The description adds meaningful round-trip semantics for claim_token ('pass it back later') and message content guidance ('don't paste the end-user's prompt'). Nothing contradicts the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx (Q&A) and discover_tools (catalog) by scoping feedback to Pipeworx tools only.

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 enumerates when to use ('Use when a tool returns wrong/stale data...') and when not to ('if the tool came from a different MCP server... file it with that server instead'). Provides concrete decision rules for each feedback type and a fallback 'Not sure?' case.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds cache duration, data source (CF analytics-engine), no PII, and aggregated data structure, which provides significant value beyond annotations.

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

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

The description is concise (three sentences) with no fluff. It front-loads the main output and uses bullet points for use cases, making it easy to scan.

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

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

Given the tool's simplicity (1 optional param, no output schema, no nested objects), the description fully covers what is returned and how it behaves. No gaps.

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

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

The schema describes the window parameter with 100% coverage. The description adds guidance on interpretation: shorter windows for hot trends, longer for steady-state. This adds practical meaning beyond the enum.

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 verb 'Returns' and resource 'top tools, top packs, and total call volume over a recent window'. It distinguishes from siblings like 'discover_tools' by focusing on trending data from Pipeworx.

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

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

Three explicit use cases are listed: discovering hot data sources, confirming popular tools, and checking alignment. It lacks explicit when-not-to-use instructions but provides 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?

Annotations already indicate safe, idempotent, read-only behavior. Description adds rich detail: scanning process, Jaccard similarity threshold, placeholder filtering, fill check with book depth, and conditions for trade avoidance. No contradiction with annotations.

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

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

Description is lengthy but each sentence adds necessary detail. Front-loaded with main action and mode summary. Slightly verbose but not excessive; could be tightened 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?

Given no output schema, description thoroughly explains return structure: opportunities array with fields, partition_check object, fill_check details. Covers all modes and edge cases (placeholder filtering, low similarity). Complete for the tool's complexity.

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

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

Schema coverage is 100% but description adds substantial value: explains that event accepts slugs or URLs, topic uses a seed question for cross-event scanning, and details behavior of each mode. This exceeds what the schema alone provides.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each argument: no args for trending_scan, event for specific market, topic for cross-event. Recommends event mode for specific markets. Mentions alternative polymarket_fill_risk for custom sizing. Could be clearer about when not to use this tool versus other siblings.

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

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

The description discloses extensive behavioral traits: caching (1h at KV level), model families, response segmentation, diagnostics, tradeable-edge filters, and a warning about 24h moves. This goes far beyond the annotations (readOnly, openWorld, idempotent). 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 very long and dense, lacking clear structure such as bullet points or sections. While it front-loads the main purpose, the technical details could be better organized for quick parsing.

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 is highly complete given the complexity (9 parameters, no output schema). It covers the response structure, diagnostics, caching, edge cases (Fed bets), and why segments might be empty, leaving negligible gaps.

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

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

The description adds rich context beyond the schema, explaining how parameters interact (e.g., edge_pp_net after slippage, min_kelly vs min_partition_leg_kelly). It also clarifies the impact of tradeable-edge filters on opportunity realizability.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and it is built for 'what should I bet on today'. It distinguishes itself from siblings by focusing on edge detection across multiple model families.

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

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

The description provides clear context for when to use the tool, including specific use cases like model-driven, structural arbitrage, and concentrated longshots. However, it does not explicitly state when not to use it or contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 significant detail: response structure (tracked, expired, snapshot_dates), computation of decay, TTL limits, and snapshot gaps. 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 lengthy but well-structured: main purpose first, then response format details, then limitations. Every sentence adds value. Could be slightly more concise but is appropriate for the complexity. Front-loading the core question helps.

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 fully specifies the response fields (tracked, expired, snapshot_dates) with their sub-fields and meanings. It also covers limitations (TTL, snapshot gaps). For a tool with 2 simple parameters, this is 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?

Input schema covers both parameters with clear descriptions (days lookback with default/clamp, window family with enum-like values). Schema coverage is 100%, so baseline is 3. Description adds default values and slightly more context (e.g., window families) but does not significantly expand 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 clearly states it provides 'edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It uses specific verbs (track, analyze) and resource (edges snapshots), distinguishing it from siblings like 'polymarket_edges' which likely focus on current edges without time-series.

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

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

The description implies usage context (for comparing fresh vs. old edges) but does not explicitly state when not to use or contrast with alternatives like 'polymarket_edges' or 'polymarket_arbitrage'. However, the focus on historical decay makes its purpose clear enough for an agent to infer 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and not destructive, indicating a safe, read-only operation. The description adds detailed behavioral context: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage, shares_filled, max_fillable, and a verdict. For basket mode, it lists additional outputs and warns about forced_directional_risk. No contradictions with annotations.

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

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

The description is thorough but appropriately structured with sections for single-market and basket modes. Every sentence provides essential information, though it is long. It front-loads the core purpose and requirements. Conciseness is good given the complexity.

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

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

Despite no output schema, the description comprehensively explains all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg details, thin_legs, etc.). It also covers edge cases like partial fills and unhedged directional risk.

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 each parameter. The description adds value by explaining mode-dependent interpretation: for side, defaults and auto behavior; for size_usd, different meaning in single-market vs basket. It enriches understanding beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it (before acting on arb signals or trades above $500).

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

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

Provides explicit when-to-use guidance: before acting on arb signals or trades above $500. Describes two modes (single-market vs basket) and when each is appropriate. Warns about the danger of partial basket fills converting an arb into an unhedged directional position.

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

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

Annotations already mark it as read-only and idempotent. The description adds critical behavioral details: compatibility_warning for non-equivalent bet shapes, temporal_alignment for date mismatch, and skipped counters. No contradictions with annotations.

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

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

The description is thorough and well-organized into sections (purpose, modes, response, safety). Every sentence adds information, though slightly verbose for a rapid scan.

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, so the description must cover return fields. It explains spread calculation, leg prices, safety fields, and temporal alignment. For a tool of this complexity, it is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the 10 topic shortcuts and giving examples for explicit tickers, beyond what the schema provides.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use each mode and warns that most pre-mapped topics may return compatibility warnings, implying spreads aren't always tradeable. However, it doesn't explicitly contrast with alternative tools like polymarket_edges, leaving some ambiguity.

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

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

Annotations already declare readOnly and idempotent. Description adds scoping detail (identifier-based isolation), which is valuable behavioral context beyond annotations.

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

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

Four concise sentences, each providing unique value: function, use case, scoping, and pairing with siblings. No redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers function, usage context, scoping, and relationships to other tools. Return value is implied 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?

Schema coverage is 100% and the description restates the schema's parameter semantics without adding extra constraints or examples. Barely adds 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?

Clearly states the tool retrieves a saved value or lists all keys, with specific verb-resource pairing. Differentiates from siblings remember and forget by naming them and explaining 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 says when to use: to look up context stored earlier without re-deriving. Mentions scoping and pairing with remember/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?

The description discloses return fields (source, citation_uri, raw payload) and explains the effect of mark_read:true (flags events read so next call shows only newer ones). This adds behavioral detail beyond the readOnlyHint and idempotentHint 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-loaded with the core purpose, and every sentence provides useful information without redundancy.

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

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

Although no output schema exists, the description lists key return fields and explains the behavior of mark_read and polling. It covers the tool's capabilities well, but could mention the default limit behavior or unread_only effect.

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

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

Schema coverage is 100%. The description adds value by providing an example for type ('sec_8k') and explaining the effect of mark_read, enhancing understanding beyond the schema descriptions.

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

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

The description clearly states the tool's verb ('Pull fired events') and resource ('subscription feed'), and distinguishes it from siblings like list_subscriptions by emphasizing real-time alert retrieval with filtering.

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

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

The description explains filtering options (type, since) and the mark_read flag behavior, and notes that the same feed is available via a direct URL for scripts/dashboards, providing context for when to use the tool vs. 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 indicate read-only, open-world, idempotent, non-destructive. Description adds rich behavioral details: parallel fan-out, fallback on rate-limit/5xx, USPTO soft-fail, and structured return format with citation URIs. No contradictions.

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

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

Compact yet information-packed: starts with examples, then explains the tool in a few sentences covering sources, fallback, parameters, and output. 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?

Covers purpose, sources, fallback, parameter types, and output structure. Lacks mention of result limits or pagination, but overall complete for a multi-source tool with no output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining since accepts ISO date or relative shorthand with examples, suggests typical monitoring value, and explains value accepts ticker or CIK.

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

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

The description starts with user intents like 'What's new with X' and clearly states it's a change feed for a company in the last N days/weeks/months. It specifies multiple data sources (SEC EDGAR, GDELT→GNews, USPTO) and differentiates 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?

Provides explicit guidance to use entity_profile for static profile. Describes fallback behavior (GDELT→GNews) and soft-fail for USPTO. Lacks explicit 'when not to use' beyond sibling mention.

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 scoping by identifier and persistence durations (authenticated vs anonymous), adding value beyond annotations which already indicate idempotence and non-destructiveness.

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 action purpose, no redundant sentences; every sentence adds information while remaining brief.

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?

Thoroughly addresses usage, storage mechanism, scope, persistence, and companion tools; no output schema needed for this simple write operation.

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

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

Schema covers 100% of parameters with descriptions; description adds context with example key patterns and value flexibility, exceeding baseline.

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

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

Clearly states the tool saves data for reuse across conversations or sessions, distinguishing it from siblings recall and forget via explicit pairing mention.

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

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

Explicitly says 'Use when you discover something worth carrying forward' with concrete examples, and directs to pair with recall/forget for complementary operations.

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

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

The description adds rich behavioral context beyond the annotations. It discloses that identifiers are labeled by source, that unresolved identifiers are listed under `unresolved` rather than omitted, and that LEI/FIGI enrichment degrades gracefully when upstream services are unavailable. These are non-obvious behaviors that help the agent anticipate response characteristics. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with relatable examples, but it is fairly long. Each sentence carries useful information, so there is little waste, but it could potentially be tightened. The structure is logical, moving from purpose to supported types to behavioral details.

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 and moderate complexity, the description covers the key aspects: what inputs are accepted, what outputs to expect, how unresolved data is handled, and that it replaces multiple manual lookups. It could mention error behavior or exact response structure, but it is complete enough for an agent to invoke the tool correctly.

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

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

While the schema describes both parameters (type and value), the description greatly enriches their semantics. For type='company', it details the full set of identifiers returned (CIK, ticker, LEI, FIGI), the sources, and acceptable input formats (ticker, CIK, name). For type='drug', it lists RxCUI, ingredient, brand, and citation format. This goes far beyond the schema's brief descriptions.

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

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

The description is exceptionally clear, using specific verbs ('resolve', 'look up') and naming the exact resource (canonical/official identifiers for company and drug entities). It opens with concrete example queries and explicitly states that it provides the IDs other tools require, which distinguishes it from sibling tools like entity_profile or compare_entities. This goes far beyond a vague purpose statement.

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

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

The description provides a clear when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' This gives strong contextual guidance. However, it does not explicitly name alternative tools for when an ID is already known or when other capabilities are needed, so it falls short of the full 5 (which requires explicit 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond that: probing each entity, ranking, output format (score, confidence, signal density), and the use of ai_visibility_check internally.

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

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

The description is three sentences, front-loading the core action. No superfluous words; every sentence adds value.

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

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

No output schema exists, but the description covers return fields (score, confidence, signal density). It explains the ranking and the input usage. Could mention number of entities allowed (2-8) more explicitly, but that's in the schema.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds meaningful context: first entity is the subject, rest are competitors; models default to workers-ai; _apiKey is only needed for anthropic. This goes beyond mere schema repetition.

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 verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes from siblings like ai_visibility_check by specifying side-by-side comparison and naming ai_visibility_check as a sub-probe.

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

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

The description gives a concrete use case: competitive AI-marketing audits. It implies when to use (comparing multiple brands) but does not explicitly exclude scenarios where a single entity check 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 indicate readOnlyHint, idempotentHint, etc., and the description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list it if it times out. 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 informative but not overly long. It front-loads the main purpose and then adds necessary details. Every sentence contributes value, though it could be slightly more terse.

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 details the return structure (summary block fields, per-advisory detail, links, alternative versions). It also covers ecosystem limitation and partial failure behavior. Combined with annotations, it is fully complete.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds that scoped packages (e.g., '@types/node') are accepted for 'package', and that 'version' defaults to the latest when omitted, enhancing the schema.

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

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

The description clearly states it is a composite check for evaluating npm packages, listing specific sources (deps.dev, bundlephobia) and what they provide (license, advisories, size, etc.). It distinguishes from siblings by focusing on dependency scanning, with no direct sibling tool for this 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 says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also notes scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This provides clear when-to-use and 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?

Discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and that passages include offsets for verification. No contradiction with annotations.

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

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

Four dense sentences with no wasted words. Front-loaded with purpose, efficient in conveying all critical 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?

Despite no output schema, the description explains return format (passages with offsets and scores) and edge case (truncation). Fully covers behavior for a tool with 3 parameters.

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

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

Schema coverage is 100% with individual descriptions. The description adds value by explaining the query field as natural-language with examples, and notes the max length for text and default for limit.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and explains the specific use case of reducing context for large records. It also mentions its pair with ask_pipeworx_grounded, providing implicit differentiation.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Lacks explicit 'when not to use' but provides clear contextual 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 readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds context: required authentication, creation of a subscription with an id, persistence limitations, delivery constraints (10 SMS/day, webhook auto-disable after 10 failures), and details on webhook signing. This enriches the behavioral understanding beyond annotations. No contradiction.

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

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

The description is thorough but slightly verbose; it could use bullet points or shorter sentences for some parts (e.g., delivery channels). However, it is front-loaded with the core purpose and returns, and the examples are well-placed. It earns its length with valuable information, but a more structured format would improve 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?

For a tool with 3 parameters (one enum, two nested objects) and no output schema, the description covers all necessary aspects: types with params, delivery options with limitations, and the fact that it returns an id. It also mentions prerequisites and post-creation behavior (webhook secret, auto-disable). The agent has sufficient information to invoke correctly.

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

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

With 100% schema coverage, the description still adds significant value. It explains each type's params with concrete examples (e.g., sec_8k items meaning, polymarket_edge topics, webhook HMAC signing). The delivery object is detailed with constraints and verification steps. This goes beyond the schema definitions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It specifies the verb (create), resource (subscription), and distinguishes from sibling tools like list_subscriptions and unsubscribe. The supported types and delivery channels are detailed, leaving 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?

The description provides when to use (proactive monitoring), prerequisites (Pipeworx OAuth account; not for anonymous/BYO), and examples for each type. It lacks explicit when-not-to-use or alternatives, but the sibling context and clarity on what is supported are adequate. A slight improvement would be mentioning when to use alternatives like polymarket_arbitrage.

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, so the description does not need to repeat safety traits. It adds behavioral context: the tool returns example questions with tool+argument shapes and can be focused by topic. 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 well-structured, front-loading the purpose and providing a bullet-like list of categories. It is efficient but slightly dense; each sentence earns its place. A minor improvement could be to rephrase the bullet list for 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?

Even without an output schema, the description fully explains what is returned (category-bucketed example questions with tool+argument shapes) and lists the categories. For a simple onboarding tool with one optional parameter, this is 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%, so the description adds marginal value beyond the schema. It explains the purpose of the optional topic parameter and lists allowed values, which matches the schema description. A baseline of 3 is appropriate as the schema already documents the parameter well.

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: it is an onboarding entry point that returns category-bucketed example questions to help users (or agents) understand what Pipeworx can do. It specifies the verb 'returns' and resource 'example questions', distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing clear when-to-use guidance. It does not explicitly exclude alternatives, but the context strongly implies when to use it and contrasts with other 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?

Adds value beyond annotations by explaining the row is deactivated (not deleted) and historical events remain via recent_alerts. Annotations already indicate non-destructive and idempotent 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?

Two efficient sentences with no redundancy. First sentence states purpose, second adds 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?

Simple tool with one parameter and no output schema. Description covers ownership, deactivation, and history preservation, fully addressing agent needs.

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

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

With 100% schema coverage, baseline is 3. Description adds context that the id is a uuid returned by subscribe, providing useful linkage 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?

Clearly states 'Cancel a subscription by id.' Uses a specific verb and resource, distinguishing it from siblings like subscribe and list_subscriptions.

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

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

Explicitly notes ownership enforcement ('only cancel your own subscriptions'), guiding when to use. Does not explicitly mention alternatives, but no sibling tool for cancellation exists.

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 signal read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: the verdict values, distinction between could_not_verify (check did not happen) and unsupported (no source), the verification_error payload, and the two routing paths. It adds value beyond annotations with 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 dense but well-structured, opening with trigger phrases, then purpose, then behavior, then important caller warnings. Every sentence adds value; the length is justified by the tool's complexity. The 'IMPORTANT' section is clearly front-loaded for the critical misuse case.

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

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

With no output schema, the description fully covers return values (verdict values, actual value with citation, reasoning) and explains error semantics. It also explains the two processing paths and when each applies. For a complex tool, this is complete enough 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?

Input schema covers both parameters 100% with descriptions and examples. The description adds extra nuance for tolerance_pct: 'set 1–2 for hallucination detection where any material error must be refuted' and notes the default is capped at 5. This exceeds the baseline for fully-covered 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 does natural-language claim verification against authoritative sources, with specific trigger phrases and two distinct pipelines (SEC EDGAR for financial claims, grounded pipeline for everything else). It distinguishes itself from siblings by being the dedicated fact-checking tool and explicitly says it replaces 4-6 sequential calls.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies handling for financial vs. other claims, and gives a crucial caller instruction about interpreting could_not_verify as not evidence. This is clear when-to-use guidance.

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

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

The description contradicts annotations. It says 'random number' implying non-determinism, but annotations include idempotentHint: true, meaning identical requests should yield identical results. This inconsistency undermines transparency.

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

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

Brief at three sentences, but the content is whimsical and not actionable. Conciseness is not helpful if it sacrifices 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?

The description is incomplete for a tool with one optional parameter and an output schema. It fails to clarify what the random number represents, how the format affects output, or any usage 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 coverage is 100% (format parameter described), but the description adds nothing about parameter meaning. It does not explain the enum values (raw, bloomberg, sommelier), leaving the agent without context for choosing a format.

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 'A random number, aged 24 hours for smoothness' is vague on the tool's purpose. It never explicitly states that it retrieves a number from yesterday, and the whimsical tone obscures the core function. No clear verb+resource structure.

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

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

No guidance on when or when not to use this tool compared to siblings. The description does not mention use cases, prerequisites, or alternatives.

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