Yesterdays Number

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, which the description does not contradict. The description adds behavioral context: it explains that the default model is free, Anthropic requires a BYO key, and returns per-model structured data. This goes beyond annotations by detailing the probing behavior and data flow.

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 at four sentences, front-loading the core purpose and then providing details on model options, return format, and use cases. Every sentence adds value without redundancy, making it efficient for an AI agent to parse.

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 adequately explains the return value structure ('per-model {score, confidence, signals, raw_response} + a combined view'). It covers required parameters, optional ones, and practical use cases, making the tool understandable and actionable for the intended scenarios.

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

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

Schema coverage is 100% with all four parameters described in the schema. The description adds value by specifying the default model ('Workers AI Llama-3.3-70b'), clarifying that _apiKey is optional and only needed for Anthropic, and noting that context helps disambiguate. This extra information enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100) per model. It specifies the verb 'probe' and 'score', the resource 'LLMs' knowledge about an entity, and distinguishes from sibling tools by focusing on multi-model visibility scoring.

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 usage, including use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), default model, and when to use the API key. It does not explicitly state when not to use or list alternatives among siblings, but the context is sufficient for an AI agent.

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

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

With no annotations, the description carries the full burden. It discloses that the tool picks the right tool and fills arguments, but doesn't detail limitations, failure modes, or behavior under ambiguity. The description is moderately transparent but leaves gaps about edge cases.

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

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

The description is three sentences plus examples, which is concise and front-loaded with the core function. It efficiently conveys the tool's purpose without unnecessary detail, though the examples could be shortened.

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

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

Given the tool has a simple single-parameter schema and no output schema, the description adequately explains what the tool does and how to use it. It covers the essential aspects for a natural language query tool, though it could mention response format or expected behavior more explicitly.

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

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

Schema coverage is 100% for a single parameter. The description adds value by clarifying that the parameter should be a natural language question, and provides examples. It goes beyond the schema's 'Your question or request in natural language' by illustrating usage.

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: answer plain English questions by automatically selecting the best data source, filling arguments, and returning results. It distinguishes itself from sibling tools by describing an agent-like capability rather than direct data retrieval or memory operations.

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

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

The description explains when to use the tool: when you have a question in plain English and don't want to browse tools or learn schemas. It provides concrete examples. However, it doesn't explicitly state when not to use it or mention alternative tools for specific scenarios.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating safe, read-only behavior. The description adds substantial behavioral detail: it uses only the tool result for answers, returns explicit refusal reasons (e.g., 'not_in_source', 'no_tool_match'), and describes the exact return structure. This goes well beyond what annotations provide.

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

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

The description is highly concise and well-structured, starting with the key purpose, then detailing behavioral specifics, return format, usage context, and cost tradeoff. Every sentence adds value and there is no redundant information.

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

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

Despite the tool's complexity (routing to many sources, extracting answers with refusal handling), the description is complete. It explains the routing mechanism, the extraction process, the return structure (including all refusal reasons), and the appropriate use cases. No output schema exists, but the description adequately covers output expectations.

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 100% of parameters with descriptions, including aliases for the 'question' parameter. The description does not add additional parameter-level semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results, returning evidence and refusal reasons. It distinguishes itself from the sibling 'ask_pipeworx' by specifying it is for answers that will be quoted or cited, where invention of facts is unacceptable.

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

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

The description explicitly tells when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also advises preferring 'ask_pipeworx for casual lookups' and notes the cost tradeoff of one extra LLM call. This provides clear guidance on alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral detail: fan-out logic (e.g., BTC bet triggers coingecko+fred+gdelt+gnews), resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback handling, and safety mechanisms (low-confidence short-circuits, closed market detection, wide-spread warnings). No contradiction with annotations.

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

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

The description is long but well-structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with the main purpose and usage. While lengthy, every sentence adds necessary detail for a complex tool. Could be slightly more concise, but still effective.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers input variants, classification categories, fan-out examples per bet type, response fields, resolver matching details, parent event extraction, news field behaviors, and safety edge cases. The absence of an output schema is compensated by detailed response shape descriptions.

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 beyond the schema by explaining the meaning of 'depth' (quick vs thorough), the flexible 'market' parameter (accepts slug, URL, question text), and 'include_raw' (summarized vs full payloads). Examples are also provided, enhancing understanding.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet, comparison). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by being a comprehensive research tool that fans out to multiple data sources.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also discusses when not to trust results (low-confidence matches) and mentions blocking paths for closed markets. However, it does not explicitly state when to use sibling tools like polymarket_edges instead.

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

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

With no annotations, the description discloses return data (paired data + resource URIs) and query fields per type. It does not mention failure modes, rate limits, or if the operation is read-only; however, for a comparison tool, the disclosed detail is adequate.

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

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

The description is extremely concise: two sentences, no fluff, front-loaded with purpose and key details. Every sentence earns its place.

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

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

Given no output schema, the description fully explains return format (paired data + URIs) and covers all required inputs. It also mentions the efficiency gain vs. sequential calls, making it contextually 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%, and description adds value by explaining type-specific fields, giving examples (tickers vs. drug names), and clarifying entity constraints (2-5 items). This exceeds the baseline.

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

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

The description clearly states the tool compares 2-5 entities in one call, with explicit differentiation by type (company vs. drug) and specific fields returned. It also contrasts with sequential agent calls, distinguishing it from siblings.

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

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

The description specifies when to use (comparing entities in bulk) and the entity count range (2-5). It implies efficiency benefits but does not explicitly list when-not-to-use or alternatives among siblings, though the context excludes common scenarios.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds specifics: returns verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, and gaps[] for unanswerable facets. Mentions 'never invented' and timing expectation. Adds behavioral detail beyond annotations.

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

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

Description is moderately long but well-structured, front-loaded with key information. Every sentence adds value, but could be slightly more concise for efficiency.

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 description must cover return values. It does: structured findings packet with detailed fields. Also covers prerequisites, timing, and scope. Fully 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%, baseline 3. Description adds meaning by explaining depth levels (quick=3, standard=5, thorough=8) and the paid plan requirement for thorough. Also clarifies that question can be broad/multi-part.

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: 'Grounded multi-source research in ONE call.' It explains decomposition, parallel routing, and extraction of grounded answers. It distinguishes from siblings like ask_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?

Explicit guidelines: use for broad/multi-part questions; use ask_pipeworx for single lookups. Also mentions prerequisites (Pipeworx account, paid plan for thorough depth) and expected time (15-60s).

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?

No annotations provided, so description carries full burden. It states the tool returns 'most relevant tools with names and descriptions', which is helpful but doesn't disclose details like whether results are ranked, if there is pagination, or if it only returns tools from the same server. Adequate but not exhaustive.

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, both front-loaded with key information. No redundant words. Every sentence provides value: first sentence defines purpose, second gives usage guidance.

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

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

Given the tool is simple (2 params, no output schema), the description is fairly complete. It explains what it does, when to use it, and the nature of the query. Minor gap: doesn't mention the return format beyond 'names and descriptions', but for a search tool that returns tool metadata, this is acceptable.

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 does not add extra parameter details beyond the schema. The schema itself includes clear descriptions for 'query' and 'limit'. The description reinforces the use of natural language for query, but doesn't add new semantics.

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

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

Clearly states it searches the tool catalog using natural language queries. The verb 'Search' and resource 'Pipeworx tool catalog' are specific. The description also differentiates from siblings by advising to call this first when there are 500+ tools, which is a unique role.

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

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

Explicitly tells the agent to 'Call this FIRST when you have 500+ tools available', providing clear when-to-use guidance. It does not mention when not to use, but the directive to use it first implies it's for tool discovery, not for other tasks.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable behavioral details: fans out across multiple sources, lists exact returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents with soft-fail note, news, LEI). Patents API sunset noted, providing honest constraint.

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

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

Single paragraph packs comprehensive information without being overly verbose. Could be slightly more structured (e.g., bullet points for returned fields) but remains efficient and front-loaded with key facts.

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 2 params and no output schema, the description covers most aspects: sources, returned fields, limitations (patents sunset, names not supported). Missing explicit mention of pagination or rate limits, but acceptable given the holistic overview focus.

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 already describes both parameters (type, value) with 100% coverage. Description reinforces meaning: 'zero-padded CIK' and explicitly states names not supported, adding clarity beyond the schema enum and description.

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

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

Description explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call' and lists common user queries. It distinguishes itself from chaining single-pack lookups and from sibling tools like resolve_entity.

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

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

Clearly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name is available, providing explicit when-to and when-not-to use guidance.

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

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

The description indicates deletion, which is destructive, but no annotations exist. It does not disclose whether the deletion is permanent, requires confirmation, or has any side effects. With no annotations, the description partially carries the burden but is minimal.

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

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

Single sentence, no wasted words. Perfectly concise for a simple tool.

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

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

Given the low complexity (1 required param, no output schema), the description is adequate but could mention if the key must exist or what happens on success/failure. No output schema means description could clarify return value.

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 parameter 'key' is already described in the schema. The description adds no additional meaning 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 deletes a stored memory by key, which is a specific verb+resource. It distinguishes from siblings like 'remember' (store) and 'recall' (retrieve).

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 is provided on when to use this tool versus alternatives (e.g., recall vs forget). The description implies usage when deleting a memory, but does not mention prerequisites or 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?

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. It could mention error handling but is sufficient.

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 (3-4 sentences), front-loaded with the main action, and includes use cases without redundancy. Every sentence adds value.

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

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

Given no output schema, the description adequately explains the output format. Parameters are well-documented. It could mention limitations like public-only URLs, but overall complete for the tool's simplicity.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds minor context ('a specific landing page') but largely relies on 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from siblings like ai_visibility_check by focusing on file creation rather than checking AI visibility.

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: getting a client's site indexed, drafting for own project, or auditing a competitor. It does not explicitly mention when not to use or alternatives, but the context is clear given sibling tools.

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

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

Annotations already indicate read-only and non-destructive behavior. Description adds the default 'active' filtering and output field details, enhancing transparency beyond annotations.

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

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

Two concise sentences with no unnecessary verbiage. Front-loads the main purpose and follows with usage guidance.

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

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

Given the simplicity of the tool (single optional param, no output schema), the description fully covers what the agent needs: output fields, default behavior, and when to use.

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

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

Schema coverage is 100% and includes a description for the only parameter. Description mentions 'active subscriptions' implicitly but doesn't add new meaning beyond schema. Adequate but not exceptional.

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

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

Clearly states it lists the caller's active subscriptions and specifies the returned fields. Distinguishes from sibling tools like subscribe and unsubscribe.

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 this tool before adding more subscriptions or to find an id to cancel, providing clear usage context. Lacks explicit when-not-to-use but sufficient for a simple list.

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

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

With no annotations, the description discloses the rate limit (5 messages per identifier per day) and that feedback is sent to the team. No destructive or behavioral side effects are relevant here.

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 with zero waste. Purpose first, then guidelines, then rate limit. Every sentence adds value.

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

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

For a simple feedback tool with no output schema, the description covers purpose, usage, rate limit, and content constraints. Sufficient for correct agent invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds little beyond summarizing the 'type' enum and optional 'context' object, but the schema already does the heavy lifting.

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

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

The description clearly states 'Send feedback to the Pipeworx team' and lists specific use cases (bug reports, feature requests, missing data, praise). It distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on feedback submission.

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

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

Explicitly tells when to use (bug reports, etc.) and provides content guidelines (describe in terms of Pipeworx tools, do not include end-user prompt verbatim). No explicit 'when not to use' but clear enough for the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). This goes beyond the annotations, but could include more details like rate limits or result structure, hence 4.

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 well-structured sentences. The first sentence states the action and result, followed by bulleted use cases. Every sentence adds value; no wasted words. The structure is front-loaded with key 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, data provenance, privacy, caching, and use cases. It is fully self-contained and sufficient for an agent to understand and invoke correctly.

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

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

Only one parameter (window) with full enum and description. The description enhances the schema by explaining the trade-off between windows: shorter windows show 'hot' trends, longer windows show steady-state demand. This adds meaning beyond the schema's enum listing.

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 returns top tools, top packs, and total call volume over a window. It uses a specific verb ('returns') and resource ('trending data'). Among sibling tools like ai_visibility_check or ask_pipeworx, this is uniquely positioned as an aggregate/trending tool, so it's well-differentiated.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning use case). It does not explicitly mention when not to use or provide alternative tool names, but the context is clear enough for an agent to decide. A minor gap in exclusion guidance prevents a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral details: it walks child markets, checks date-axis/threshold-axis ordering, computes partition checks, applies Jaccard similarity (>=0.30) for cross-event pairs, and filters partitions with placeholder slugs. 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 detailed but well-structured with clear sections for requirements, modes, semantic anchor, partition filter, and response. It front-loads the requirement. While slightly lengthy, every sentence adds necessary context. Could be more terse but remains organized.

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

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

Given the complexity of arb detection, the description covers modes, filters, similarity thresholds, response structure, and constraints. No output schema exists, but the description details the response fields. It doesn't cover error handling or rate limits, but essential usage is comprehensive.

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

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

Schema coverage is 100% with descriptions for both parameters. The description significantly expands on each: event is explained as a slug or URL for single-event mode, topic as a seed question for cross-event mode. It provides examples and explains the behavior of each mode, adding substantial meaning beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) with distinct use cases, making it specific to arbitrage detection on Polymarket. It does not explicitly distinguish from sibling Polymarket tools like polymarket_edges, but the verb and resource are clear enough.

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

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

The description provides explicit guidance on when to use each mode: event for a specific market slug, topic for cross-event scanning with examples. It warns that calling with no args fails. However, it does not mention when not to use this tool or compare it to alternatives like polymarket_edges or polymarket_kalshi_spread.

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

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

The description extensively details behavioral traits beyond annotations, including caching (1h), model families, filtering logic, edge calculations, diagnostic fields, and special handling of Fed bets. The annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds comprehensive 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 long but well-structured with clear sections and front-loaded purpose. Every sentence adds value, though it could be slightly more concise. It avoids redundancy and uses structured formatting for the model families.

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

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

Given the complexity of the tool and lack of output schema, the description is exceptionally complete. It explains the output structure (by_segment, diagnostics), field meanings, and caveats (e.g., Fed bets, caching). No output schema exists, so the description carries the full burden and meets it thoroughly.

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

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

The input schema has 100% coverage with detailed descriptions for all 9 parameters. The description adds some context (e.g., slippage_pp explains Polymarket fees), but it does not fundamentally enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). However, it does not explicitly distinguish itself from sibling tools like polymarket_arbitrage, which could cause confusion.

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 lacks guidance on when to use this tool versus alternatives. It mentions the tool is 'built for what should I bet on today' but provides no exclusions or comparisons to other tools in the sibling list, such as polymarket_arbitrage or bet_research.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds critical behavioral context: 60-day snapshot TTL, data starts from when snapshotting was enabled, decay computed from daily closes (not intraday), and gaps in data due to no cache-miss. This goes well beyond annotations.

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

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

The description is verbose but efficient: each sentence adds information. It is front-loaded with purpose, then details the response structure and limitations. Could be slightly tightened, but no wasted words.

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

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

Given the complexity (time-series, multiple arrays) and no output schema, the description compensates by detailing the response fields (tracked, expired, snapshot_dates) and their meanings. It also mentions limitations. Very complete, though not explicitly stating JSON format.

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

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

Schema coverage is 100% with good descriptions. The description adds value by explaining that 'window' refers to a snapshot family and enumerating the options (24hr, 1wk, 1mo) and explicitly stating defaults and max. The slight clamp vs max discrepancy (schema: clamp 2-30; description: max 30) is minor.

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' and answers 'how long has this edge existed and is it shrinking?'. It uses a specific verb ('track') and resource ('edges over time'), and distinguishes from siblings like polymarket_edges by focusing on time-series persistence.

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

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

The description explains the use case: differentiating fresh wide edges from old wide edges. It implies when to use (when temporal edge behavior is relevant). However, it does not explicitly compare to or exclude sibling tools beyond the implicit contrast with polymarket_edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: it requires exactly one of market or event, explains the difference between single-market and basket modes, and lists all return fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) including edge cases like thin_legs and 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 fairly long but every sentence adds functional value. It is structured with a summary, then mode explanations with parameter instructions, then output details. Could potentially be slightly more concise, but the density of information justifies the length. No filler sentences.

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, so the description fully carries the burden of explaining return values. It lists all fields for both modes (top_of_book, vwap_fill_price, shares_filled, verdict, etc., and for basket mode: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk). Covers edge cases and the dominant loss mode, making the tool self-contained despite lacking an output schema.

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

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

Schema description coverage is 100% for 4 parameters, but the description adds critical context beyond the schema: default values (size_usd=1000, side defaults), interpretation of size_usd for buys vs sells and basket mode, and auto-detection of side in basket. The tool's behavior described enriches parameter understanding significantly.

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?

Opens with a clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Quickly distinguishes single-market and basket modes, and explicitly differentiates from sibling tools (polymarket_arbitrage, polymarket_edges) by stating when to use this tool before acting on those signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides clear context for when-not and explains the risk of partial fills turning arb into directional positions (dominant loss mode). No ambiguity about prerequisites 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: explains compatibility_warning scenarios, temporal_alignment, skipped_cross_type/subtype counters, and the output structure. No contradiction with annotations.

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

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

The description is relatively long but well-structured with clear sections (modes, response, safety fields). Every sentence adds value, though some detail could be condensed. It is appropriately 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?

Despite the absence of an output schema, the description thoroughly explains the response format (leg-by-leg prices, spread array, safety fields). Given the tool's complexity (3 parameters, moded behavior, safety indicators), the description is complete and leaves no ambiguity about inputs or outputs.

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

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

Schema coverage is 100%, but the description goes beyond by explaining the two modes (topic vs explicit tickers), providing concrete examples for topic values, and describing how parameters interact. This adds significant meaning beyond the schema's property 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 it measures the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts and explicit tickers), and the title references the two platforms. The sibling tools include polymarket_arbitrage and polymarket_edges, and this description differentiates itself by focusing on cross-venue spread.

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

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

The description provides explicit guidance on when to use each mode, warns that most pre-mapped topics return compatibility warnings, and states that spreads are mathematically meaningless when temporal_alignment is false. It says 'pre-mapped ≠ tradeable' and advises that real spreads are rarer than the shortcut list suggests.

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?

No annotations provided, so description must convey behavior. It states retrieval of stored memories, implying a read operation. However, it does not disclose whether memories persist across sessions, what happens on missing key, or any side effects. Adequate but lacks depth for a memory tool.

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

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

Two sentences, front-loaded with core action, no wasted words. Efficiently communicates both retrieval modes.

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

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

For a simple read tool with one optional parameter and no output schema, the description is mostly complete. It explains both usage modes and context. Lacking details on return format or error handling, but acceptable given tool simplicity.

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

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

Schema description coverage is 100% and the single parameter 'key' is well described. The description adds value by clarifying that omitting key lists all memories, which is not in schema. This extra context elevates the score above baseline 3.

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

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

Description clearly states the tool retrieves a memory by key or lists all memories when key is omitted. Verb 'retrieve' and 'list' combined with 'memory' resource is specific, and the phrase 'previously stored memory' distinguishes it from other tools like remember or forget.

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

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

Explicitly tells when to use: 'retrieve context you saved earlier in the session or in previous sessions.' The omission of key is clearly noted for listing all memories, and no alternatives are needed as it's a distinct retrieval tool among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavior details: return format, filtering by type/since, mark_read effect on subsequent calls, and polling suitability. No contradiction.

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

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

The description is concise yet comprehensive, with two sentences that front-load the core purpose and structure information efficiently. Every sentence adds value.

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

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

Given no output schema, the description covers return fields (source, citation_uri, raw payload) and all parameters. It is complete for the tool's complexity and provides additional context (alternative endpoint, polling suitability).

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 explains each parameter beyond the brief schema descriptions: type filter, limit max, since timestamp, mark_read flags events as read, unread_only filters null read_at. This adds substantial value.

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

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

The description clearly states it pulls fired events from the subscription feed, returning recent alerts with specific fields (source, citation_uri, raw payload). This distinguishes it from sibling tools like list_subscriptions and search_within.

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 it (pull fired events from feed) and mentions polling works fine, with an alternative GET endpoint for scripts. However, it does not explicitly state when not to use or compare directly to siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds detailed behavioral context: fans out to multiple sources (SEC, GDELT/GNews, USPTO), fallback behavior, soft-fail for USPTO, and return format (structured changes, URIs). No contradiction with annotations.

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

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

The description is concise (single paragraph) and well-structured: use case examples first, then data sources, parameter details, return structure, and sibling differentiation. Every sentence adds value without redundancy.

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

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

Given the complexity (multiple sources, fallback, parameters with special formats), the description comprehensively covers inputs, behavior, and outputs. It mentions return structure despite no output schema, making the tool self-contained.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds practical semantics: explains that 'type' is only 'company', gives examples for 'since' (ISO date and relative shorthand like '30d'), and clarifies 'value' accepts ticker or CIK. This enhances 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 explicitly states the tool provides a 'change feed for a company' with specific examples of use cases ("What's new with X", "latest on Y"). It distinguishes from the sibling tool 'entity_profile' by noting that alternative is for static profiles.

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 guidance including example queries, and explicitly directs to use 'entity_profile' when a static profile is desired, providing a clear alternative. It also explains the parameter format (ISO or relative) and typical values.

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 key behavioral traits: persistence based on authentication status and session expiration for anonymous users. Since no annotations are provided, the description carries full burden, and it does so adequately without contradictions.

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

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

Three concise sentences: first states core function, second gives usage examples, third clarifies persistence. Every sentence adds value, no wasted words.

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

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

Given the simplicity of the tool (2 parameters, no output schema, no nested objects), the description fully covers what the agent needs: what it does, when to use it, and behavioral quirks (memory duration). No gaps remain.

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

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

The schema already describes both parameters well (key with examples, value as free text). The description doesn't add extra meaning beyond confirming the key-value nature. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the tool stores a key-value pair in session memory, with specific use cases (saving intermediate findings, user preferences, context). The verb 'store' and resource 'key-value pair' are specific, and it distinguishes itself from siblings like 'forget' 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?

The description explains when to use the tool (to save context across calls) and provides some guidance on persistence differences (authenticated vs anonymous). However, it doesn't explicitly state when not to use it or mention alternatives, but the sibling tools (forget, recall) imply complementary 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?

With no annotations, the description takes the burden. It mentions returns (ticker, CIK, name, URIs) implying a read operation, but does not disclose behavior on non-existent entities, side effects, or permission requirements. Adequate but not exhaustive.

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 highly concise at two sentences, front-loading the purpose and providing key details without unnecessary words. Every sentence adds value.

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

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

Given the tool's simplicity and no output schema, the description covers the main purpose, accepted inputs, and return values. It lacks details on edge cases but is complete enough for a 2-parameter lookup tool.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description adds concrete examples (e.g., 'AAPL', '0000320193') and clarifies the type enum, providing additional 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 resolves an entity to canonical IDs, with specific verb 'Resolve' and resource 'entity to canonical IDs'. It also distinguishes from sibling tools by noting it replaces 2-3 lookup 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?

The description provides explicit usage context for the 'company' type, including accepted inputs (ticker, CIK, name) and examples. It does not explicitly state when not to use or alternatives, but the context is sufficient for the current version.

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 idempotent and read-only behavior. The description adds behavioral context: it internally calls ai_visibility_check for each entity, ranks results, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations by detailing the process and output structure.

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 only two sentences, perfectly front-loaded with the core action and followed by use-case and output details. No redundant words or unnecessary 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?

Without an output schema, the description adequately covers the return format (ranked list with score, confidence, signal density) and the aggregation logic. It could be slightly more explicit about handling multiple models, but the overall completeness is high.

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

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

Schema coverage is 100%, but the description adds value: it explains that entities[0] is the 'subject' for narrative, specifies model support and key requirements, and describes the context parameter's purpose. This enriches 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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), the resource (AI presence/visibility), and distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (generic 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 provides clear context for use: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple entities) and not to use (single entity, where ai_visibility_check would suffice), though it does not explicitly exclude alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds detailed behavioral traits: partial failure graceful degradation, bundlephobia's first measurement timeout (5-30s), and that sources_failed lists timed-out sources. 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?

Well-organized with dashes and line breaks, front-loading key info. However, slightly verbose with repeated detail already in schema and annotations. Still efficient overall.

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 details return structure (summary block fields, per-advisory, links, alternatives), sources, partial failure, and ecosystem scope. 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% and both parameters are well-documented in schema. The description repeats schema text verbatim (e.g., scoped packages, version default). No additional semantic value beyond the schema.

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

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

The description clearly states it is a composite check for should-I-add-this-npm-package questions, specifying the verb 'check' and the resource 'npm package'. It distinguishes itself from sibling tools by explicitly limiting to the NPM ecosystem in v1.

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

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

Explicit guidance on when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also clarifies when not to use: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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 readOnly, idempotent, etc. Description adds critical behavioral details: embedding model, window size, character cap (200K chars with truncation flag), and output structure (offsets, scores).

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

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

Front-loaded with purpose, then usage, then technical details. Every sentence earns its place, though slightly lengthy. Good structure overall.

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 still indicates return format. Covers purpose, usage, behavioral traits, and parameter semantics thoroughly. No gaps.

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

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

Schema coverage is 100%, but description adds value by explaining 'text' as a document, 'query' as natural-language query, and provides examples. Enriches understanding beyond schema.

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

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

Clearly states it performs semantic search inside a fetched record. Uses specific verb 'search within' and distinguishes from siblings by pairing with ask_pipeworx_grounded.

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

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

Explicitly advises use when the record is too large for the prompt, explains how it saves context, and mentions alternative tool (ask_pipeworx_grounded). Does not explicitly state when not to use, but context is clear.

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

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

The description adds substantial behavioral context beyond annotations: it requires OAuth, details phone verification, imposes daily caps, and explains webhook auto-disable after failures. This is valuable given the annotations (readOnlyHint=false, idempotentHint=true) are already present and not contradicted.

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, front-loaded with the main purpose and requirement, and efficiently packs type-specific examples and delivery details into a few dense sentences with no wasted words.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers most aspects: type examples, parameter constraints, delivery behaviors, and return value. Minor gaps like error handling or subscription ID format exist, but overall it is sufficient for an agent to use the tool effectively.

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 coverage is 100% with descriptions, but the tool description enriches parameters with concrete examples (e.g., sec_8k items, polymarket_edge topics) and delivery constraints (phone verification, webhook signing). This adds meaning beyond the schema, justifying a score above baseline 3.

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

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

The description uses a specific verb 'Create' and identifies the resource as 'proactive monitoring subscription'. It clearly states the action and distinguishes from sibling tools like list_subscriptions, unsubscribe, recent_alerts, which serve different purposes.

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

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

The description provides detailed context for when to use the tool, including requirement of a Pipeworx OAuth account and limitations on delivery channels (e.g., 10 SMS/day). However, it does not explicitly state alternatives or when not to use it, relying on implicit differentiation from sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing that the tool returns example questions with tool+argument shapes and that it's safe to call with no arguments. 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 front-loaded with natural language queries and is informative, but slightly verbose. Every sentence adds value, though some redundancy exists.

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 simplicity (1 optional param, no output schema), the description is fully complete: it explains what the tool returns, how to use it, and when to use it. 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 input schema covers the single parameter with 100% coverage. The description adds context: 'Call with no arguments for the full spread, or pass topic... to focus', providing examples and behavioral guidance beyond the schema.

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

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

The description specifies the verb 'returns' with the resource 'category-bucketed example questions' and clearly differentiates from sibling tools by positioning itself as the onboarding entry point.

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 this FIRST when you do not yet know what Pipeworx can do for you' and explains how to focus with the optional topic parameter. However, it doesn't explicitly state when not to use it.

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

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

Adds key behavior beyond annotations: deactivation not deletion, and reference to recent_alerts for historical events. Annotations already indicate non-destructive and idempotent, but description provides concrete 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?

Two sentences, front-loaded with the core action, no extraneous information. Every sentence adds value.

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

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

Given simple tool with 1 param and no output schema, description covers ownership, effect on data, and link to historical access. Complete for agent invocation.

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

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

Schema coverage is 100%, so the schema already describes the id parameter. The description does not add new parameter-specific semantics beyond what 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 it cancels a subscription by ID, with ownership enforcement, distinguishing it from 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 states ownership enforcement (only own subscriptions) and mentions that historical events stay via recent_alerts, but could 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?

Adds context beyond annotations by specifying domain (US public company financial claims), return format (verdict, citation), and efficiency claim (replaces 4-6 calls). Annotations already indicate read-only, idempotent, open-world.

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

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

Front-loaded with usage examples and efficient, though slightly lengthy. 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?

Comprehensive for a claim verification tool: explains input, output, domain, methodology, and comparative advantage. No output schema, but summary covers 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?

Schema coverage is 100%, so baseline is 3. Description provides examples but does not add significant meaning beyond the schema description.

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

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

Description clearly states it verifies natural-language claims about company finances using SEC EDGAR, distinguishing it from siblings like 'bet_research' or 'compare_entities'.

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

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

Explicitly says 'Use whenever the agent needs to check factual correctness' and gives trigger phrases, but does not explicitly state when not to use (e.g., non-financial claims).

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 minimal behavioral insight beyond annotations. It mentions 'random' but this conflicts with idempotentHint, and no concrete traits like state changes or side effects are described.

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 too brief, prioritizing style over substance. It fails to convey essential information, making it underspecified rather than efficiently concise.

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

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

Despite having an output schema, the description does not hint at return values or how to use the format parameter. This leaves the agent without context for practical use.

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

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

Schema coverage is 100%, so the description need not elaborate on parameters. However, it entirely ignores the 'format' parameter, missing an opportunity to explain its effect.

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

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

The description uses metaphorical language ('aged for smoothness') instead of stating the tool's function clearly. It does not specify that it returns a fixed number from yesterday, leaving the purpose ambiguous.

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 to use vs. sibling tools. The description does not provide context for appropriate usage or mention alternative tools.

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