Insee

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

Discloses return format (per-model score, confidence, signals, raw_response plus combined view). Mentions cost implications for Anthropic calls. Consistent with annotations (read-only, idempotent, non-destructive). No contradictions.

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

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

Two efficient sentences with no waste. Front-loaded with action and scope. Examples and important caveats included succinctly.

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

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

Complete for a probing tool with no output schema. Describes return structure, explains optional parameters and their implications. Covers all behavioral and parameter nuances 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?

All parameters have schema descriptions (100% coverage), and the description adds context: entity examples, model defaults and key requirements, context disambiguation. Goes beyond schema to clarify 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 probes LLMs for knowledge about an entity and returns a visibility score. It includes specific verb ('Probe') and resource ('LLMs for what they know'), distinguishing it from sibling tools by focusing on AI 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?

Explains default model (Workers AI) and optional Anthropic probing with BYO key. Mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Does not explicitly exclude alternatives, but provides enough 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it routes questions to 3,774 tools across 895 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. 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 comprehensive but slightly lengthy. It front-loads the key preference message and uses bullet-like listing of domains. Every sentence contributes value, but minor trimming could improve conciseness.

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

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

No output schema exists, but the description explains that the tool returns a structured answer with citation URIs. For a complex tool with many possible outputs, this provides sufficient completeness about the return value and 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 description coverage is 100%, with each parameter having a clear description. The description mentions the 'question' parameter but does not add significant extra semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: to answer questions about current or historical data from a wide array of authoritative sources, preferring it over web search. It lists specific domains like SEC filings, FDA drug data, etc., and distinguishes it from sibling tools by emphasizing structured data with citations.

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 guidance on when to use this tool: for factual questions about real-world entities, events, or numbers, even when web search could also answer. It includes specific trigger phrases ('what is', 'look up', 'find', etc.) and examples, effectively instructing the agent to prefer this over alternatives like web search.

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?

Describes return structure with {answer, evidence, confidence, source, fetched_at, refusal_reason} and lists explicit refusal reasons. Cost of 'one extra LLM call' is disclosed. Does not contradict annotations (readOnlyHint, openWorldHint, etc.).

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 dense and front-loaded with purpose. It efficiently packs routing, return format, and usage guidance into a few sentences. Slightly long but every sentence earns its place.

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

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

Fully explains the tool's behavior, return schema (despite no formal output schema), refusal reasons, and usage context. Completes the picture for a complex tool with a clear boundary when data is insufficient.

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 all parameters are documented as aliases for 'question'. Description adds value by explicitly listing all aliases and stating 'Your question in natural language', clarifying usage 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 is a 'hallucination-resistant answer mode for high-stakes reads' and explains the process of routing, fetching, and extracting answers from tool results. Distinguishes from sibling 'ask_pipeworx' by adding extraction and refusal logic.

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 answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples of high-stakes domains. Also recommends preferring ask_pipeworx for casual lookups due to extra cost.

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 behavior: market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallback, and safety mechanisms. It goes well beyond the annotations (readOnlyHint, idempotentHint), providing comprehensive behavioral context 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?

The description is verbose but well-structured with uppercase section headers, making key information scannable. While every sentence seems useful, it could be more concise; however, front-loading the purpose and examples helps agents quickly grasp the tool's intent.

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, response structure, edge cases), the description is remarkably complete. It covers fan-out logic, response shapes, safety, resolution risk, and news fallback, fully compensating for the lack of an output schema and ensuring agents understand all 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 coverage is 100%, but the description adds significant value beyond parameter names and types: it explains that market can be slug, URL, or question text, gives examples, clarifies depth defaults and behavior, and explains when to set include_raw. This enriches the agent's 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 researches Polymarket bets by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and use cases ('should I bet on X'), distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description provides explicit use cases and examples of when to use the tool. It implies usage for detailed research but does not explicitly state when not to use it or mention alternatives; however, the context from examples and siblings provides sufficient guidance.

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

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

Description adds significant behavioral context beyond annotations: specifies data sources (SEC EDGAR for companies, FAERS for drugs), exact metrics (revenue, net income, etc.), handling of off-calendar fiscal years, and return of citation URIs. 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?

Description is information-dense with front-loaded example queries. Slightly verbose but each sentence adds value. Good structure 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 outlines the return content (paired data + citation URIs) and covers key aspects for a complex comparison tool. Missing exact output structure but sufficient given 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 already describes both parameters (type, values) with 100% coverage. Description adds value by clarifying array constraints (2-5 items) and providing concrete examples (e.g., 'AAPL','MSFT' for companies).

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

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

Description clearly states it performs side-by-side comparisons of 2-5 entities (companies or drugs) with specific example queries. Distinguishes itself from siblings that do single-entity lookups, e.g., entity_profile.

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

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

Explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 lookups, providing clear when-to-use guidance. Does not explicitly mention when not to use, but context implies the 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?

The description goes beyond annotations by explaining the decomposition process, parallel execution, and the exact structure of the output (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, explicit gaps[]. It also guarantees that the tool never invents facts. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description complements them without contradiction.

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

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

The description is well-structured: it starts with a concise purpose statement, then elaborates on functionality, usage guidelines, and prerequisites. It is not overly verbose; each sentence contributes useful information. Slight improvement could be trimming redundant phrases, but overall it is efficient.

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

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

Given the tool's complexity (multi-source research, parallel execution, many tools), the description is remarkably complete. It covers purpose, process, output format, usage guidelines, prerequisites, and even mentions latency. Even without an output schema, the description clearly explains what the tool returns, making it self-contained.

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

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

Schema coverage is 100% and each parameter already has a clear description. The description adds minimal new information about parameters beyond rephrasing the depth options (quick=3, standard=5, thorough=8) and confirming that the question can be broad. A score of 3 is appropriate as the description adds value but the schema already does most of the work.

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 defines the tool as 'grounded multi-source research in one call', detailing decomposition and parallel execution across 3,774 tools and 895 sources. It distinguishes itself from sibling 'ask_pipeworx' by specifying that this tool handles broad or multi-part questions while the sibling is for single lookups.

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

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

Explicitly states when to use: 'Use for broad or multi-part questions' and provides example use cases. It also tells when not to use: 'use ask_pipeworx for single lookups'. Additionally, it mentions prerequisites (Pipeworx account, paid plan for 'thorough' depth) and expected latency (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?

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description reinforces by stating it returns tools and schemas. The description adds valuable context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No 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 two sentences, front-loaded with the core purpose, and efficiently includes key details (categories, return format) without extraneous text. Every sentence earns its place.

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

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

Given the tool's simplicity (query input, no output schema), the description fully explains what it returns (tool names, descriptions, schemas) and the key benefit (ready to call directly). It covers the primary use case and is complete for an agent to understand and invoke the tool.

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

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

Schema coverage is 100% with all 6 parameters documented. The description adds minimal value beyond the schema, only providing examples of what the query could be (e.g., 'analyze housing market trends'). Baseline is 3 for high coverage, and the description does not substantially enrich parameter meaning.

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 explicitly mentions browsing, searching, looking up, and discovering tools, and provides a comprehensive list of example categories (SEC filings, financials, etc.), making the purpose very specific and distinguishable 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 advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear guidance on when to use it, but does not explicitly state when not to use it or provide direct alternatives, though the context implies it's for discovery before choosing a specific tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). Description adds rich context: fans out across multiple sources, returns specific fields (cik, filings, fundamentals, etc.), notes soft-fail for patents, and unsupported types. 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?

Description is front-loaded with examples and clear behavior. Slightly wordy but every sentence serves a purpose. Could be trimmed slightly without losing 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, description outlines return shape (cik, filings, fundamentals, patents, news, LEI) and sources adequately. Missing explicit mention of pagination or rate limits, but acceptable for 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 meaning: explains type is only 'company' for now, value can be ticker or zero-padded CIK, names not supported, plus examples. Adds substantial value beyond schema.

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

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

Description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X' and distinguishes from chaining single-pack lookups. The verb 'profile' and resource 'entity' are well-defined.

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 to prefer this tool over chaining single-pack lookups when a holistic view is needed, and advises using resolve_entity if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true). Description confirms deletion and adds context about clearing sensitive data. Does not address behavior for missing keys, but overall acceptable.

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: first states purpose, second gives usage guidelines. No wasted words, front-loaded with actionable 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 tool with one required parameter and no output schema, the description covers purpose, usage, and pairing. Lacks detail on behavior if key doesn't exist, but given simplicity and annotations, it is nearly 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 only one parameter 'key' described as 'Memory key to delete'. The description does not add any additional meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool deletes a memory by key, using the verb 'Delete'. It distinguishes from siblings like 'remember' and 'recall' by naming them and implying the opposite action.

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: stale context, task done, or clearing sensitive data. Also advises pairing with 'remember' and 'recall'. Does not explicitly mention 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?

Beyond annotations (readOnly, openWorld, idempotent, not destructive), the description details the process: fetches page, extracts title/description/key links, outputs standard markdown. It discloses all behavioral traits relevant to an AI agent.

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, front-loaded paragraph with no redundancy. Every sentence adds value: what, how, output, use cases. No fluff.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description fully covers input, process, output, and purpose. 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?

Schema coverage is 100%, so the description adds no new parameter-specific information beyond the schema's own descriptions. However, it contextualizes the output format, which indirectly aids understanding. 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 function: generate an llms.txt file for a given URL, targeting specific AI crawlers. It distinguishes itself from sibling tools by focusing on the llms.txt generation task, not on broader AI visibility or competitor scanning.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. It stops short of excluding alternatives or advising when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not required to restate safety. However, it adds useful context about the data source (official SIRENE registry) and the preference over web search. 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 concise, front-loaded with the main purpose, and covers key points (use cases, input format, example) in three sentences. No redundant information.

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

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

Given the simple input (a single identifier string) and safety annotations, the description is nearly complete. It explains what it does, when to use it, and what to provide. It does not detail output format, but with openWorldHint and readOnlyHint, that 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. The description reinforces parameter details (explains SIREN vs SIRET, provides example) but does not add significant new meaning beyond what is already in 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 specifies the verb ('Look up'), resource ('French company or establishment in INSEE's official SIRENE business registry'), and explicitly lists use cases (e.g., 'who is French company X', 'details for SIREN/SIRET', legal name, address). It differentiates from sibling tools by stating 'PREFER OVER WEB SEARCH', setting clear boundaries.

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

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

The description gives explicit guidance on when to use the tool ('PREFER OVER WEB SEARCH for...') and what input to provide (9-digit SIREN or 14-digit SIRET). It provides an example (Danone) but does not explicitly state when not to use it, though the context implies it is only for French entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and active/inactive behavior, providing useful context beyond annotations.

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

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

Two concise sentences: first states purpose and output, second gives usage guidance. No wasted words.

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

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

For a simple tool with one optional param, no output schema, and strong annotations, the description provides complete context including output fields and usage 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 covers the single parameter with 100% description coverage. Description does not add additional meaning beyond the schema's 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?

Clearly states verb (list), resource (subscriptions), and scope (caller's active). Distinguishes from siblings 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 advises using it to review monitoring before adding more subscriptions or to find an id for cancellation. Does not 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?

Description discloses rate limit (5 per identifier per day), that it's free and doesn't count against quota, and that team reads digests daily. Annotations provide no behavioral info, so description carries the burden effectively.

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

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

Description is front-loaded with purpose and usage, every sentence adds value. No waste; it's detailed yet 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?

For a simple feedback tool with no output schema, description covers purpose, usage, format guidance, and limitations. It is sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by re-emphasizing enum categories and giving formatting advice (describe in terms of tools/packs). Context parameter is explained similarly to schema.

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

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

Description clearly states the tool is for sending feedback (bugs, features, data gaps, praise) to the Pipeworx team. It specifies distinct scenarios and differentiates from sibling tools that are informational or query-based.

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 (for bugs, features, data gaps, praise) and what not to do (don't paste end-user prompt). Provides clear context for each scenario.

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, openWorldHint, and destructiveHint false. The description adds value by disclosing the data source (CF analytics-engine), privacy (no PII), data shape (pack, tool, count), and caching behavior (5min-1h). No contradictions.

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

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

Two concise paragraphs: first sentence states main purpose, then bullet points of use cases, then source and caching. Front-loaded and 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?

Though no output schema, the description explains return values (top tools, packs, total call volume) and provides source/caching info. Could detail response structure more, but sufficient for a simple tool.

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

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

Schema coverage is 100% with good parameter description. The tool description explains what short vs long windows surface and mentions return values, adding context 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 returns trending data (top tools, packs, call volume) based on recent agent usage. It distinguishes from siblings by focusing on aggregated signals rather than specific queries or entities.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs). It does not mention when not to use or alternatives, but provides clear context for appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context beyond annotations, including the fill check against live CLOB depth, skipped_low_similarity, and partition filter behavior. 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 and front-loaded with the most critical note about required parameters. Every sentence adds value, and the use of sections (REQUIRES, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) organizes the information efficiently.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response fields (opportunities[], partition_check, fill_check) and covers edge cases like placeholder filtering and low similarity. It provides a complete picture.

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%, but the description adds extensive meaning for both parameters: what a slug looks like, how each mode works, and what the tool does with the input. This goes well beyond the schema, providing examples and algorithmic details.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two distinct modes (event and topic) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with specific algorithms.

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 requires one of `event` or `topic`, warns against calling with no args, and provides detailed guidance on when to use each mode with examples. It also includes caveats like the semantic anchor for cross-event mode and the fill check, giving clear usage context.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, etc., confirming safety. Description adds extensive behavioral context: caching at KV level keyed on knobs, response structure with diagnostics, model family details, edge calculation, slippage assumptions, Fed bets exclusion with rationale. 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 very long and dense, mixing purpose, model details, parameter explanations, and response structure. While comprehensive, it lacks conciseness and could benefit from better structuring (e.g., bullet points, sections). It's more of a documentation blob than a focused tool description.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments and edge cases), the description is remarkably complete. It explains response top-level with segments, diagnostics for empty results, tradeable-edge knobs, and even the Fed bets exclusion rationale. Leaves little ambiguity for an agent.

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

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

Schema description coverage is 100%, so baseline 3 applies. Description adds some extra context for parameters like slippage_pp (zero fees but bid/ask depth) and min_partition_leg_kelly (explaining why min_kelly doesn't filter partitions), but overall the schema already provides clear descriptions. Not significantly above 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 scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, with a specific use case of 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and single-platform opportunities.

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

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

The description implies usage for discovering betting opportunities without paging hundreds of markets and explains tradeable-edge knobs, but does not explicitly state when to prefer this over siblings (e.g., polymarket_arbitrage for cross-platform spreads, polymarket_fill_risk for execution risk). Lacks 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 discloses the response structure (tracked[], expired[], snapshot_dates[]), limits (60-day TTL, start date), and that decay numbers are from daily closes, not intraday. This adds significant value beyond the annotations, which already indicate safe read-only behavior.

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

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

The description is detailed but front-loaded with the core question. Every sentence adds value, though it could be slightly more structured by separating the response format from usage hints. Still, for a tool with complex output, it is efficient.

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

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

Given the two parameters, no output schema, and comprehensive annotations, the description is complete. It explains the response format, limits, data source, and edge cases (gaps in data, TTL). No additional information is needed for correct 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?

Both parameters have schema descriptions, and the description adds meaning: explains days as lookback with default (14) and max (30), and window as snapshot family with default (1wk). It also clarifies clamping of days (2-30), providing useful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge longevity and distinguishes itself from siblings by focusing on historical tracking rather than current edges.

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

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

The description provides clear context for when to use the tool (to understand edge history and decay) and gives an example contrasting fresh vs. old edges. It implies when not to use (for current edge data) but does not explicitly name 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 indicate readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it is a simulation that checks fill risk without executing trades, describes return fields (top_of_book, vwap, slippage, etc.), and explains risks like 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 verbose but front-loaded with the core purpose. It lacks structural formatting like bullet points or sections, which could improve readability. However, given the complexity of two modes, the density is acceptable and each 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?

Despite no output schema, the description thoroughly explains return fields for both modes, including verdict, capture_ratio, thin_legs, forced_directional_risk, etc. It covers all necessary context for an agent to understand what the tool returns and the risks involved.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it explains single-market vs basket modes, default side logic, interpretation of size_usd for buys vs sells, and clamp ranges. This enriches the parameter understanding beyond the raw 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 as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly references when to use it relative to sibling tools polymarket_arbitrage and polymarket_edges, achieving high distinction.

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 guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns about partial basket fills and unhedged directional risk. While it doesn't explicitly state when not to use, the context is clear and actionable.

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

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

Goes beyond annotations by detailing response fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning cases, temporal_alignment, skipped counters), and edge cases. No contradiction with annotations.

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

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

Well-structured with sections for modes, response, and safety fields. Every sentence adds value, though slightly verbose for a simple comparison tool. Could be condensed but 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?

Compensates for lack of output schema by fully describing the response structure and safety fields. Covers edge cases, compatibility warnings, and temporal alignment. Comprehensive for a complex arbitrage tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context: topic is a pre-mapped shortcut with explicit list, and explicit tickers override. Provides examples and explains mode switching.

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 provides cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes two modes (topic shortcuts and explicit tickers) and explains the response structure. Specific verb+resource, no tautology.

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?

Explains when to use (comparing same outcome prices across venues) and when not (via compatibility_warning and temporal_alignment flags). Sets expectations that most pre-mapped topics are not yet tradeable. Lacks explicit mention of alternatives like polymarket_arbitrage but context signals list them.

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

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

Annotations provide safety hints; description adds scoping (by identifier) and the effect of omitting the key, which are beyond the annotations.

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

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

Three sentences, front-loaded with main action, no wasted words, each 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 low complexity (1 param, no output schema), the description covers scoping, listing behavior, and relationship to other tools; return format is implied but not explicit.

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 already explains the key behavior; description adds scoping info but not much new about the parameter itself.

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 (retrieve/list) and resource (values saved via remember), and distinguishes from sibling tools (remember, 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?

It explains when to use (look up stored context) and mentions pairing with remember and forget, but does not explicitly state when not to use.

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

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

Adds context beyond annotations: describes alert content, effect of mark_read, and alternative access method. No contradiction with annotations (readOnlyHint=true).

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 purposeful. Front-loaded with purpose, then details, then usage tips. No verbose or redundant text.

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

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

Covers input parameters, return format, and behavioral traits. Lacks only pagination details, but that is in schema. Complete for a simple read-only tool.

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

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

All 5 parameters explained in context: type filter, limit with range/default, since with ISO format, mark_read with side effects, unread_only for filtering. Adds value beyond 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?

Clear verb+resource: 'Pull fired events from your subscription feed.' Describes what each alert carries, but does not explicitly differentiate from siblings like list_subscriptions or subscribe.

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?

States filtering options (type, since) and mark_read behavior. Mentions polling is fine and an alternative REST endpoint, but lacks explicit when-not-to-use or contrast with siblings.

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

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

Annotations indicate readOnly, openWorld, idempotent, and non-destructive. The description adds value by detailing the multi-source fan-out, fallback from GDELT to GNews, and the soft-fail for USPTO. This goes beyond the annotations.

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

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

The description is a single well-organized paragraph, front-loaded with example queries. It efficiently covers purpose, sources, fallbacks, parameter guidance, and alternative tool. Slightly long but every part 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?

Despite no output schema, the description covers return structure (changes grouped by source, total_changes count, citation URIs), parameter details, fallback logic, and alternative tool. Complete for a tool of this complexity.

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

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

Schema has 100% description coverage. The description adds semantic guidance: for 'since' it gives examples and typical monitoring value; for 'type' it confirms only 'company' is supported; for 'value' it explains ticker or CIK formats.

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

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

The description clearly states it provides a change feed for a company over a time window, using concrete examples of user queries. It also distinguishes itself from the sibling 'entity_profile' by specifying when to use that alternative.

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

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

The description gives explicit guidance on when to use this tool (for recent changes over a window) and when not to (use entity_profile for static profile). It also explains fallback behavior between sources and provides typical values for the 'since' parameter.

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 key-value nature, identifier scoping, persistence differences (authenticated vs anonymous sessions), and pairing. Annotations omit these details.

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

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

Single paragraph, front-loaded with purpose, followed by usage, scoping, and pairing. Each sentence adds value; no wasted words. Could be slightly more concise but highly efficient.

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

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

Given simple tool (2 params, no output schema, annotations cover idempotency), description fully covers persistence, scoping, and pairing. No gaps for this complexity level.

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 deeper meaning beyond examples in key parameter description, but that part is in schema, not description. Description restates key-value pair concept.

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, distinguishing from siblings by explicitly mentioning pairing with recall and forget. The verb 'save' and noun 'data' are specific.

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 clear context for when to use (discover something worth carrying forward) and scoping (by identifier). References siblings (recall, forget) but doesn't explicitly state when not to use, though the pairing implies alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by revealing internal behavior: "Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups." It also details the exact return structure for each entity type, which is beyond annotation scope.

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 examples and a clear 'Use FIRST' guideline. It efficiently covers both entity types with specific return fields. While it's somewhat long, every sentence adds necessary context, and the structure is logical.

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 2 well-documented parameters, no output schema, and rich annotations, the description covers the input-output relationship, internal behavior, and use cases. It doesn't discuss errors or edge cases, but for a resolution tool with good annotations, this level is adequate.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description enriches this by providing concrete examples (e.g., "AAPL", "ozempic"), mentions auto-disambiguation for company names, and explains what each type returns, giving the agent a clearer mental model of how to use the parameters.

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

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

The description explicitly states the tool's purpose: "resolve a user-spoken NAME to the canonical/official identifier other tools require as input." It gives concrete example queries and immediately distinguishes itself from sibling tools by advising "Use FIRST whenever you have a name but need an ID."

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

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

The description clearly says when to use this tool ("Use FIRST whenever you have a name but need an ID") and implies it replaces multiple manual lookups. While it doesn't explicitly say when not to use it, the context makes it straightforward. It could be improved by mentioning alternatives for when an ID is already known.

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. Description adds behavioral detail: probes each entity, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, signal density. No contradictions.

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

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

Description is concise (4 sentences) and front-loaded with the primary purpose. Every sentence adds value: purpose, mechanism, use case, output format. No wasted words.

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

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

Despite no output schema, the description fully explains the return format (ranked list with score, confidence, signal density) and the process (probes with ai_visibility_check, ranks). Error scenarios or prerequisites are covered by parameter 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 description coverage is 100% with clear parameter descriptions. The tool description adds contextual framing (e.g., 'your brand + N competitors') but does not significantly enhance parameter understanding beyond the schema.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using a specific verb ('compare') and resource. It distinguishes itself from sibling tool 'ai_visibility_check' by being a multi-entity comparison that ranks results.

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

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

Provides a clear use case ('competitive AI-marketing audits') and explicitly mentions the underlying tool 'ai_visibility_check' as the mechanism, implying when to use this over the single-entity version. Lacks explicit 'when not to use' but context is strong.

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

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

The description adds significant behavioral context beyond the annotations. It explains the composite nature, partial failure handling (e.g., bundlephobia timeout with sources_failed), timing for first measurement, and the exact returned fields. Annotations already indicate readOnly, idempotent, non-destructive, and the description aligns perfectly.

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 every sentence provides actionable information. It is front-loaded with the core purpose and usage, then dives into details. While efficient, it could be slightly more structured (e.g., bullet points) for easier scanning.

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 (two APIs, partial failures, timing issues, specific return data), the description covers all necessary aspects. It describes the output summary block fields, per-advisory detail, links, alternative versions, and failure behavior. No output schema exists, but the description compensates 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by noting scoped packages are accepted and version defaults to latest. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: a composite check to decide whether to add an npm package. It specifies the data sources (deps.dev, bundlephobia) and the specific queries (license, advisories, version history, bundle size, etc.). This distinguishes it from sibling tools which cover different domains (e.g., bet_research, polymarket, etc.).

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 the tool: when an agent asks about package safety, popularity, size, or cost. It also clarifies limitations (NPM only in v1, other ecosystems should use deps.dev:version directly), providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: truncation at 200K chars, technical details about BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and that truncated inputs are flagged. This goes beyond the annotation coverage.

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

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

Description is concise yet comprehensive: three sentences cover purpose, usage context, and technical details. Every sentence adds value; no wasted words. 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?

Despite no output schema, the description fully covers what the tool returns: top-N passages with character offsets and similarity scores. It also includes technical constraints (200K char limit, embedding model, window size). Complete for the complexity of the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains that `text` is a fetched record, `query` is natural-language with examples, and `limit` defaults to 5 with max 20. This helps the agent use the parameters correctly.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' using natural-language query. It identifies the resource (a fetched record) and the action (search). It distinguishes from siblings like ask_pipeworx_grounded by explaining the pairing pattern.

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 describes how it saves context. It also mentions pairing with ask_pipeworx_grounded, providing clear when-to-use guidance and an alternative workflow.

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, idempotentHint=true, destructiveHint=false, which align with creating a subscription. The description adds behavioral context beyond annotations: account requirement, return of subscription ID, delivery constraints (SMS cap, webhook signing secret one-time return, auto-disable after 10 webhook failures), and type-specific filter requirements.

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: opening with purpose, then account requirement, then type list with examples, then delivery channels. It is somewhat long but each sentence adds unique value. The front-loading of purpose is 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?

The description covers purpose, prerequisites, type-specific parameters, delivery options, return value, and key limitations (SMS cap, webhook auto-disable). It lacks explicit error handling details or rate limits beyond SMS, but for a creation tool with no output schema, it is highly 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?

Despite 100% schema coverage, the description adds significant value by explaining all three parameters in natural language with concrete examples (e.g., 'items:["5.02"]' for sec_8k, 'topic:"fed"' for polymarket_edge) and constraints (e.g., 'sponsor or condition required' for clinical_trial). It also details delivery sub-parameters like webhook signing and SMS verification.

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 clear verb 'Create' and resource 'proactive monitoring subscription', and distinguishes from sibling tools by specifying the subscription creation context (e.g., live-data event stream, account requirement). It also implies differentiation from tools like 'recent_alerts' or '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?

The description specifies when to use the tool (to set up proactive monitoring), prerequisites (Pipeworx OAuth account), and provides detailed examples for each subscription type. It also mentions limitations like SMS daily cap and phone verification, but does not explicitly list alternative tools for when the subscription is not needed.

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 as safe. The description adds behavioral context by explaining that the tool returns example questions with exact tool shapes, that it is non-destructive, and that it can be called with or without arguments. This goes beyond the annotations and fully describes the tool's behavior.

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

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

The description is front-loaded with a list of example user queries, followed by the purpose, return value, usage instructions, and a call-to-action. Every sentence adds value; there is no unnecessary information. It is concise yet comprehensive, fitting the context of an onboarding tool perfectly.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers what the agent needs: when to use it, what it returns (category-bucketed examples with tool shapes), and how to invoke it. No information is missing for effective deployment.

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 covers the single parameter 'topic' with a description that lists possible values. The description merely echoes this, adding no new semantic meaning. With 100% schema coverage, the baseline score of 3 is appropriate, as the description does not enhance understanding 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's purpose: it is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns', 'use this FIRST') and distinguishes itself from sibling tools by focusing on suggesting questions rather than performing actions. The description leaves no ambiguity about what the tool does.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also specifies when to pass the 'topic' argument and when to omit it. The description clearly sets the context for when the tool is appropriate, fulfilling the usage guidelines dimension fully.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds that the row is deactivated (not deleted) and that historical events remain available, providing important behavioral nuance 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, concise and front-loaded with action and key constraints. Every sentence adds value without redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers all necessary behavioral aspects: ownership, deactivation, and historical data persistence. It also links to a related tool (recent_alerts) for full 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?

The schema fully describes the only parameter (id as a uuid returned by subscribe). The description does not repeat that but adds context by referencing subscribe, which is helpful but not extensive. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the action ('cancel a subscription'), the resource ('subscription by id'), and includes specific context like ownership enforcement and the difference from deletion. It distinguishes 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?

The description explicitly notes that only own subscriptions can be cancelled, which guides usage. It does not provide explicit alternatives for when not to use, but the ownership constraint and the reference to 'recent_alerts' for historical events help clarify 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 declare readOnlyHint and idempotentHint true, so the agent knows the tool is safe and non-destructive. The description adds valuable behavioral details: it returns specific verdict types (confirmed, approximately_correct, etc.), includes a structured form, actual value with citation, and percent delta. It also notes that it replaces 4-6 sequential calls, but does not disclose behavior for out-of-scope claims. 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 somewhat lengthy (8+ lines) but each sentence adds value: it front-loads purpose, then usage, scope, output details, and efficiency gains. It is well-structured and avoids redundancy, though it could be slightly more concise without losing information.

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

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

Given the tool's single parameter and no output schema, the description provides sufficient context: it explains what the tool does, when to use it, what outputs to expect (verdict types, structured form, etc.), and its efficiency advantage. Annotations cover safety. It is fairly complete for the agent's decision-making, though it could mention the source (SEC EDGAR) more prominently.

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 the single parameter. The description provides example claim formats, which adds some meaning beyond the schema, but the schema's description already covers the parameter's purpose. Therefore, the additional value is modest, warranting a baseline score of 3.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It gives specific verbs like 'fact check', 'verify', 'confirm or refute', and explicitly mentions the resource (claims). The scope is defined (company-financial claims) and it distinguishes itself from sibling tools by being a dedicated fact-checker, not a general search or research tool.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This provides clear context for when to use. However, it does not explicitly state when not to use or suggest alternative tools for out-of-scope claims, though the scope is defined. It implicitly guides by limiting to company-financial claims.

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