Montreal Events

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds value by disclosing that Workers AI Llama is free and that probing Anthropic requires the user's own API key with direct billing implications. This goes beyond what annotations provide.

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

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

The description is three sentences long, each earning its place. The first sentence clearly states the core action and output. The second explains the default and paid options. The third describes the return structure. 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 lacking an output schema, the description clearly defines the return shape ('per-model {score, confidence, signals, raw_response} + a combined view'). With 100% parameter coverage and explicit usage guidance, the description is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds meaning by explaining the default model, the role of _apiKey, and the purpose of the context parameter for disambiguation. It also describes the return format, which is not in the schema.

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

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

The description clearly states the tool's action ('Probe one or more LLMs'), the resource ('what they know about a business/brand/product/topic'), and the output ('score visibility (0-100) per model'). It distinguishes from similar siblings like 'scan_competitor_ai_presence' by focusing on a specific entity and providing per-model scoring with a combined view.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the free default model and the requirement for a BYO API key for Anthropic. While it doesn't explicitly exclude alternatives, the context and sibling tools provide enough guidance for when to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds context about routing to multiple tools and returning citation URIs, which enhances 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?

Description is front-loaded with key instruction and includes examples and alternatives. While slightly lengthy, every sentence adds value and it is well-structured.

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

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

Given the tool's complexity, schema coverage, and annotations, the description covers usage, examples, and alternatives. It is fairly complete, though it could mention error handling or limitations.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds that the question is in natural language but doesn't provide additional semantics beyond what the schema already states.

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 routes questions to one of 4,552 tools across verified sources and returns structured answers with citation URIs. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use those instead.

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 'PREFER OVER WEB SEARCH' and provides extensive examples of query types. Gives clear guidance on when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad queries).

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 significant context beyond annotations: describes the internal mechanism (routing to 4,552 tools, extracting only from result), explicit refusal reasons (not_in_source, no_tool_match, etc.), and cost trade-off. Annotations already indicate safe read and idempotency, but description enriches behavioral understanding.

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 clear sections: purpose, mechanism, return format (success and refusal), usage guidance, and cost trade-off. No redundant sentences; each part adds essential information.

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

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

Given complexity (routing, refusal logic, cost) and absence of output schema, description is highly complete. It explains success and failure outputs, when to use, and how it differs from sibling. Minor gaps: exact output field types could be more explicit, but overall sufficient.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question', leaving little for description to add. Description does not elaborate on question format or constraints beyond schema, earning a baseline 3.

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

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

Clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, with explicit distinction from the sibling ask_pipeworx tool for casual lookups. Uses specific verb 'extract answer' and specifies resource as routed tool 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?

Explicitly states when to use (answers that will be quoted/cited/acted on, e.g., financial/legal/medical) and when not (casual lookups, prefer ask_pipeworx due to extra cost). Provides clear context and alternatives.

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

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

Goes far beyond annotations by detailing resolver contract, parent_event extractor, news fallback mechanisms, safety short-circuits, wide-spread tradeability, and resolution-rule risk. Provides deep behavioral context for various scenarios.

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 long but well-structured with labeled sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). Every section adds value; however, the level of detail could be trimmed without losing essential guidance. Fits complexity well.

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?

Exceptionally comprehensive given no output schema. Covers input handling, resolution, edge cases, and response fields thoroughly. Addresses safety, closed markets, and cancellation rules. Leaves very little ambiguity.

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

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

Schema coverage is 100%; description adds context for market parameter (slug/URL/question) and mentions depth's 'quick' and 'thorough' but does not significantly enhance beyond 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 researches Polymarket bets by pulling Pipeworx data in one call, with specific verb and resource. It distinguishes from siblings like polymarket_edges by focusing on one-call research with fan-outs.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Includes examples of fan-out for different bet types, but does not explicitly list alternatives or when not to use.

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

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

The description goes well beyond the annotations (readOnlyHint, etc.) by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting behavior by primary metric, and output format including citation URIs. No contradiction with annotations.

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

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

The description is information-dense but well-structured, starting with common user phrases and then details. Every sentence adds value, though it could be slightly shorter without losing clarity. It's appropriately sized for the complexity.

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

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

Given the tool's complexity (comparing companies/drugs), the description covers input parameters, data sources, handling of edge cases (fiscal years), sorting logic, and output format (paired data + citations). No output schema is present, but the description compensates fully. All necessary context is provided.

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

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

With 100% schema coverage and 2 parameters, the description adds significant meaning: it explains what data each type pulls (10-K financials vs. FAERS/trial counts), provides concrete examples for values, and describes sorting and output. This is far more informative than the schema alone.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 entities (companies or drugs) in a single call. It provides common user phrases like 'compare X and Y' and explicitly distinguishes it from sequential lookups, making purpose very specific and differentiated 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives examples of when to use. It lacks explicit mention of when not to use, but the guidance is strong and clear for the intended use case.

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

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

Adds significant behavioral detail beyond annotations: expected latency (15-60s), output structure (findings packet with evidence, confidence, gaps[]), and that answers are grounded (not invented). No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Description is lengthy but well-structured with critical info front-loaded (account requirement, alternative). Every sentence adds value, though could be slightly more concise for such a complex tool.

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

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

Given the tool's complexity (multi-source, parallel tools, paid plans), the description is thorough. Covers prerequisites, usage, alternatives, limitations, and expected behavior. No output schema is provided, but return format is explained.

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 meaning: depth enum values are explained (quick=3, standard=5, thorough=8) and question accepts broad/multi-part input. This adds 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 identifies the tool's purpose: grounded multi-source research across 1160 structured data sources, with decomposition of questions into facets. It distinguishes from sibling tools like ask_pipeworx (single lookup) and provides specific use cases (broad/multi-part questions).

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 (broad questions over structured data) and when not to (breaking news, use ask_pipeworx). Also mentions account requirements and that 'thorough' depth needs paid plan, with alternative tool if not signed in.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral 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.' This tells the agent exactly what to expect in the response, making the tool's behavior transparent and actionable.

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 (5 sentences) and front-loaded with the core purpose. It efficiently packs domain examples, output structure, and usage guidance without redundancy. Every sentence contributes distinct information, making it easy for an agent to parse quickly.

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 (6 parameters, multiple aliases, no output schema), the description is remarkably complete. It explains the purpose, when to use, what the output looks like, and that results include schemas ready for direct invocation. The absence of an output schema is compensated by the clear description of the return format. The description leaves no significant gaps for an agent to infer.

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

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

The input schema already covers all 6 parameters with descriptions (100% coverage). The description mentions the query parameter's purpose ('Natural language description of what you want to do') and lists aliases, but these duplicate schema information. Since schema coverage is high, the description adds minimal semantic value beyond indicating that aliases are accepted.

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 identifies the specific action (find) and resource (tools), and explicitly distinguishes itself from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This effectively differentiates it from other tools that retrieve specific data.

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

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

The description provides explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also enumerates the domains the tool covers (SEC filings, financials, FDA drugs, etc.), helping the agent understand when to deploy it. While it doesn't list specific alternatives, the instruction to call it first implicitly contrasts it with tools that answer specific questions.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: parallel fan-out across SEC EDGAR, XBRL, USPTO, news, GLEIF; soft-fail for patents; specific return fields; and that it takes ticker or zero-padded CIK. 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 comprehensive and front-loaded with example queries, but slightly verbose. It could be tightened without losing clarity. However, it earns its length by covering important details.

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

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

For a tool with no output schema, the description fully explains all return fields, data sources, fallback behavior, and input constraints. Given the complexity (multiple datasources, soft-fail, parallel call), the description is complete enough 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?

The input schema has 100% description coverage, but the tool description adds meaningful context: 'type' is restricted to 'company' with a note about future entity types; 'value' explains ticker vs CIK format and explicitly warns against using names. This goes 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?

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists what it returns (CIK, filings, fundamentals, patents, news, LEI) and distinguishes from sibling tools like resolve_entity by instructing to use that if only a name is available.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Provides example queries and warns that names are not supported, directing to resolve_entity. Tells when to use and when not to.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details (sorted by start date, content in French) without contradicting annotations, providing useful context beyond the structured fields.

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 short sentences with no fluff. It front-loads the purpose and immediately provides key usage details, making it 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?

While the description covers filtering and sorting, it lacks any mention of the return format or fields (no output schema exists). For a tool with 6 parameters and no output schema, this omission leaves the agent guessing about the structure of results.

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

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

Schema coverage is 100%, baseline 3. The description adds value with example keywords (e.g., 'musique', 'festival') and borough examples, enhancing understanding of how to use the parameters beyond the schema descriptions.

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

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

The description clearly states the tool finds upcoming public events in Montréal with filtering by keyword, borough, and date window. It uses a specific verb and resource, and is distinct from siblings which are unrelated.

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

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

The description implicitly tells when to use (need events in Montréal) and lists filter options. No explicit when-not or alternatives are needed as there are no sibling event tools, but the guidance is clear and context-rich.

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 destructiveHint: true and readOnlyHint: false, indicating a destructive mutation. The description adds the context of clearing sensitive data but does not disclose additional behavioral details beyond the annotations (e.g., whether deleting a non-existent key returns an error). With annotations covering the main behavioral traits, the description adds minimal extra transparency.

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

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

Two sentences: first states the action, second gives usage guidance and mentions related tools. No filler words, front-loaded, every sentence earns its place.

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

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

For a simple one-parameter delete tool with no output schema, the description covers purpose, usage context, and relationship to siblings. It does not explain error behavior or return value, but given the tool's simplicity and the presence of annotations, it is largely 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 the single parameter 'key' is described as 'Memory key to delete' in the schema. The description reinforces that the key identifies the memory to delete but does not add new syntactic or semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Delete a previously stored memory by key.' It specifies the resource (memory) and the operation (delete). It distinguishes itself from sibling tools by mentioning pairing with 'remember' and 'recall,' which are listed as siblings.

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

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

Explicit when-to-use conditions are provided: 'when context is stale, the task is done, or you want to clear sensitive data.' It also suggests complementary actions: 'Pair with remember and recall.' This gives clear context for when to invoke this tool versus 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, idempotentHint, and destructiveHint; description adds that it fetches the page and outputs markdown, which is consistent and provides moderate additional context. No mention of rate limits or auth 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?

Four concise sentences that front-load the purpose, then detail behavior and output. No 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 (2 params, no output schema), the description fully covers purpose, usage, behavior, and output format. It mentions default and max for max_links, which is helpful.

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. Description adds context for 'url' and 'max_links' but doesn't significantly enhance beyond what schema already provides.

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

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

Description uses specific verb 'Generate' and resource 'llms.txt file for any URL', clearly stating the tool's function. It differentiates from siblings by focusing on generating llms.txt, not AI visibility or research.

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

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

Explicitly lists use cases (client indexing, own project, auditing competitor) providing context for when to use. However, lacks explicit when-not-to-use or comparison with alternatives.

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

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

Annotations already indicate safe read-only operation; description adds contextual detail about response fields and active vs inactive filtering, 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 sentences with zero waste: first sentence defines purpose and output, second provides usage guidance. Information is front-loaded.

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

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

For a simple tool with one optional param and no output schema, the description covers purpose, return fields, and usage suggestions 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 has 100% coverage for the single parameter; description implies filtering logic (active vs include_inactive) and adds value by linking to usage ('find an id to cancel').

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 states 'List the caller's active subscriptions' with specific verb and resource, and lists returned fields. Clearly distinguishes from siblings like subscribe/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 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear context for when to use, though doesn't name alternative tools.

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

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

Annotations are minimal (no hints), so the description carries the burden. It discloses rate-limiting (5 per identifier per day), free usage, and how feedback is processed (digests daily, affects roadmap). This is good context, though it could mention error handling or confirmation.

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

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

Four concise sentences, front-loaded with purpose. No fluff, every sentence adds value. The structure is logical: what it does, when to use, how to write, and constraints.

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 (feedback), the description covers usage, constraints, and response handling (digests). It could mention that feedback is not real-time, but the 'digests daily' implies that. No output schema is needed, so 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 extra guidance beyond the schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This helps agents formulate the message correctly, adding 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 starts with a clear verb 'Tell' and resource 'the Pipeworx team', then specifies use cases (bug, feature/data_gap, praise). This uniquely identifies the tool's purpose vs siblings like 'ask_pipeworx' or 'discover_tools', which serve different goals.

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 (bug, feature, data_gap, praise) and provides guidance on what to include (tool/pack context, avoid pasting prompts). Also mentions rate limits and that it doesn't count against quota, which helps in decision-making.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), description adds: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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?

Three sentences plus three bullet points. Front-loaded with core function. Every sentence provides essential information without redundancy or fluff.

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

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

Covers purpose, parameter meaning, use cases, data source, privacy, caching, and return structure (top tools, packs, total calls). No output schema needed; description is sufficient for an AI agent.

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

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

Schema coverage is 100% with a single parameter 'window'. Description adds semantic context beyond the schema by explaining the effect of different window lengths ('surfaces what's hot right now' vs 'steady-state demand').

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 verb 'Returns' and the resources 'top tools, top packs, and total call volume'. It distinguishes itself from sibling tools by focusing on trending/aggregated signal rather than individual queries or searches.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, alignment check). Does not mention when not to use, but provides enough context for an AI agent to decide.

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, destructive, idempotent), the description adds significant context: it explains null arb signals, placeholder filtering, fill check against live CLOB depth, and trade recommendations. 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 structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with purpose. However, it is somewhat verbose and could be condensed.

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

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

Despite no output schema, the description explains the response format (opportunities[], partition_check), fill check behavior, and failure modes. It covers all aspects of the tool's operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial meaning: examples of event slugs and topic queries, behavior differences between modes, semantic anchor, and partition filter 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 that the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three modes (trending_scan, event, topic) and distinguishes from siblings like polymarket_edges.

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

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

Explicit guidance is provided for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Limitations are mentioned but no explicit comparison with 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, idempotent, non-destructive behavior. The description adds caching behavior (1h KV-level), diagnostics for empty segments, and reliability notes on Fed data, exceeding 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?

The description is long but well-structured with sections and bullet points. Some content could be leaner, but given complexity it is appropriately thorough and front-loaded.

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

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

Without an output schema, the description fully specifies the response structure (by_segment, fed_candidates, _diagnostics) and explains logic for each segment, 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%, yet the description adds significant value with examples, default behaviors, and practical guidance (e.g., slippage_pp explains Polymarket fees, min_kelly explains filtering logic).

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, tailored for daily betting decisions. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement 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?

It provides clear context for use (daily betting discovery) and explains filtering knobs for tradeability, but does not explicitly compare with alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint and idempotentHint, but description adds behavior: decay computed on absolute edge, trend categories, expired opportunities, snapshot gaps. 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?

Front-loaded core purpose, then output structure, then limits. Slightly long but every sentence is informative. Could be slightly tighter without losing meaning.

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

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

No output schema, but description extensively explains output format (tracked, expired, snapshot_dates) and field meanings. Fully compensates for lack of structured output, leaving no gaps for an agent.

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

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

Schema coverage is 100% with good descriptions. Description adds meaning: default/range for days, window family concept (24hr, 1wk, 1mo), units. Adds value beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge duration and decay, distinguishing it from sibling tools like polymarket_edges.

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

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

Provides context on when to use (fresh vs old edge difference) and limits (60-day TTL, non-intraday data). However, does not explicitly exclude scenarios or compare alternatives beyond implied.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds detail: walks ladder, returns fill details, verdict, forced directional risk. No contradiction; it supplements annotations with specific behavioral context.

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

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

The description is long but each sentence adds value. It front-loads the core purpose, then details modes, parameters, outputs, and usage warnings. Minor redundancy but still efficient for the complexity.

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

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

The description lists all returned fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict etc.) and explains risks (forced directional risk, partial fills). No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100%. The description adds meaning: explains size_usd interpretation (spend vs target proceeds) differs per mode, side default logic (auto for basket), and the role of markets vs event. This goes well beyond the schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' distinguishing single-market and basket modes. It connects directly to sibling tools like polymarket_arbitrage and polymarket_edges, making its purpose unambiguous.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns about theoretical overround and partial basket fills, providing clear when-to-use and context about risks.

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 significant context beyond annotations: explains compatibility_warning cases, temporal alignment, skipped counters. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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?

Long but every sentence adds value. Front-loaded with purpose and modes. Could be slightly more concise but effective.

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

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

No output schema, but description explains response structure (leg-by-leg prices, top_spreads_pp) and all safety fields thoroughly. Complete for a complex cross-venue spread 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%, but description adds meaning: lists the 10 topic shortcuts, provides examples for explicit tickers, and explains that explicit overrides topic-mapped side.

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 computes cross-venue spread between Kalshi and Polymarket for same resolving question. Uses specific verb 'spread' and distinguishes from siblings like polymarket_arbitrage.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers), warns that pre-mapped topics often return compatibility warnings, and states when to use each. Also notes that real spreads are rarer than 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?

Annotations already provide readOnlyHint=true and destructiveHint=false. Description adds scoping (anonymous IP, BYO key hash, account ID) and relationship to remember/forget, going beyond annotations without contradiction.

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

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

Four sentences, front-loaded with core action, no fluff. Every sentence adds value: action, use case, scoping, pairing. 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?

For a simple read-only lookup tool with one optional param and no output schema, the description is complete. It covers purpose, usage context, scoping, and tool relationships.

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

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

Input schema has 100% coverage with a single optional key param. Description reiterates that omitting key lists all keys, adding minimal value beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states the tool retrieves a value saved via remember or lists all keys when key is omitted. Verbs 'retrieve' and 'list' are specific to the resource, and the description distinguishes from sibling tools remember and forget.

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

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

Explicitly advises using this tool to look up context stored earlier, avoids re-deriving. Scoping to identifier is explained. Pairs with remember and forget, providing clear when-to-use and alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral context such as the effect of mark_read flagging events as read, suitability for polling, and the mention of an alternative endpoint. 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 three sentences, front-loaded with the core action, then details on return fields and filtering, and lastly behavioral notes. No verbose or redundant content.

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

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

For a read-only, idempotent tool with 5 optional parameters and no output schema, the description covers purpose, return fields, filtering, mark_read behavior, and alternative access. It lacks details on pagination or error handling but is reasonably complete.

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

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

Schema coverage is 100%, so parameters are well-documented. The description provides examples (e.g., filter by type 'sec_8k') and clarifies mark_read behavior, adding marginal value over 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 verb 'Pull' and the resource 'fired events from your subscription feed.' It also distinguishes from siblings by specifying it returns alerts with source and citation_uri, which is distinct from other tools like 'list_subscriptions' or 'events'.

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

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

The description does not explicitly guide when to use this tool versus its siblings like 'events' or 'recent_changes'. It only mentions an alternative access method (registry endpoint) but no guidance on tool selection.

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, and non-destructive behavior. The description adds valuable details: parallel fan-out to multiple sources, GDELT→GNews fallback, and USPTO soft-fail. However, it does not discuss rate limits or authentication requirements, which are minor gaps.

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 example queries. Every sentence adds distinct value—usage context, sibling differentiation, parameter details, and return format. No superfluous content.

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

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

The description covers all major aspects: purpose, sources, fallback, parameter semantics, return format (changes grouped by source, count, citation URIs), and relationship to sibling. Given the tool's complexity and lack of output schema, the description is complete and informative.

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 enhances understanding by providing relative time shorthand examples (e.g., '7d', '30d') and clarifying that type is currently limited to 'company'. This adds meaningful 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 function: a change feed for a company over a time window, with specific examples. It lists sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes from the sibling tool entity_profile, which provides a static 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?

The description provides explicit guidance on when to use this tool vs. entity_profile, and includes example queries that illustrate typical use cases. It also explains fallback behavior and soft-fail conditions, giving the agent clear context for invocation.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds persistence details ('authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scope ('scoped by your identifier').

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

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

The description is front-loaded with the core action, followed by usage scenarios and details. Every sentence adds information, with no verbosity or redundancy.

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

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

For a simple tool with two required parameters and no output schema, the description covers purpose, usage context, persistence behavior, and relationship to sibling tools, leaving no ambiguity.

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

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

With 100% schema coverage, the description adds value by providing concrete examples of keys and values ('a resolved ticker, a target address, a user preference, a research subject'), aiding proper 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 action ('Save data') and the resource ('data the agent will need to reuse later'). It distinguishes from siblings by mentioning 'Pair with recall to retrieve later, forget to delete.'

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 when to use ('discover something worth carrying forward') and explicitly names alternatives ('recall', 'forget') for related operations.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: internal cascading through multiple endpoints, auto-disambiguation for company inputs, and specific return values including citation URIs for each type. This fully describes the tool's behavior 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 dense paragraph that efficiently conveys purpose, usage, and return information. It front-loads with query examples. While highly informative, a slight structural improvement (e.g., breaking into bullets for supported types) could enhance readability without adding length.

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 required parameters, no output schema, and the tool's focused role, the description is nearly complete. It explains both input types and expected outputs, including citation URIs. It lacks explicit error handling (e.g., what happens if the entity is not found), but that is not critical for a 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?

Schema coverage is 100%, but the description enriches both parameters: for 'type' it explains what each enum value ('company', 'drug') returns; for 'value' it provides concrete examples (ticker, CIK, name for company; brand/generic for drug) and mentions auto-disambiguation. This adds meaning well beyond the schema's minimal descriptions.

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

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

The description opens with concrete example queries ('What's the ticker for...', 'find the CIK for...') and clearly states the tool's purpose: resolving spoken names to canonical identifiers needed by other tools. It distinguishes itself from siblings like compare_entities or entity_profile by focusing on name-to-ID conversion, making selection unambiguous.

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

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

The description explicitly recommends using this tool 'FIRST whenever you have a name but need an ID.' It details supported types and their outputs, providing clear context for when to invoke it. However, it does not explicitly mention when NOT to use it or list alternative tools for similar tasks among the 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 provide readOnlyHint=true and idempotentHint=true. The description adds context that the tool internally calls ai_visibility_check, ranks results, and returns scores, confidence, and signal density. It does not contradict annotations, and adds value by explaining the probing and ranking process.

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, each serving a distinct purpose: stating the tool's action, explaining the mechanism, and providing a concrete use case with output summary. No redundancy or fluff; front-loaded with the core function.

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

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

For a tool with 4 parameters, 100% schema coverage, and no output schema, the description sufficiently explains inputs, process (probing and ranking), and output format (ranked list with score, confidence, signal density). It also references the underlying tool and gives a practical example, making it complete for an AI 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%, so baseline is 3. The description adds meaning by explaining that 'entities' are brand names with the first treated as subject, and that 'context' disambiguates common names. It also describes how parameters are used in the ranking process, which goes beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and identifies most/least recognized. It uses specific verbs and resources, and distinguishes from siblings like ai_visibility_check and compare_entities by specifying the multi-entity comparison and ranking.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and implies that for single-entity checks one should use ai_visibility_check. However, it does not explicitly state when not to use this tool or mention alternatives beyond the implicit sibling relationship.

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, idempotentHint, destructiveHint. Description adds significant behavioral context: fans out to two services, returns specific fields, partial failures (bundlephobia slow), and graceful degradation. 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 information-dense with no fluff, but could be slightly more concise. It is front-loaded with the main 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?

No output schema; description fully covers return values (summary block, per-advisory, links, alternatives), partial failures, 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% with clear descriptions. Description adds value by noting scoped packages accepted and default to latest version, exceeding the schema's 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 it's a composite check for 'should I add this npm package' covering deps.dev and bundlephobia, with specific fields. It distinguishes from siblings by noting NPM-only 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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives exclusions for other ecosystems and mentions partial failures.

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

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

Beyond annotations (readOnlyHint, etc.), description reveals technical details: embedding model, windowing, truncation cap at 200K chars, offset for verification. No contradiction with annotations.

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

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

Efficiently front-loads purpose, then usage, then technical details. Every sentence adds information; no redundancy or 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, description explains return format (passages with offsets and scores), input cap, and pairing with sibling. Complete for a 3-parameter 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. Description adds value by providing natural-language query examples and context for 'text' (max chars). Slight improvement.

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 semantic search inside a fetched record, with specific examples (SEC 10-K), and distinguishes from sibling ask_pipeworx_grounded by explaining the pairing.

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

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

Explicitly states when to use (record too big for prompt) and pairs with ask_pipeworx_grounded, providing a clear workflow. Though no explicit 'when not to use', the context implies 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?

Beyond annotations (readOnlyHint=false etc.), the description adds important behavioral details: returns id, requires OAuth, delivery constraints (SMS 10/day cap, webhook HMAC signing, auto-disable after 10 failures). This is excellent transparency.

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

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

The description is moderately long but front-loaded with the primary purpose. Every sentence adds value; however, it could be slightly more concise without losing information. Still well-structured.

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

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

Given no output schema, the description only states 'Returns the new subscription id.' It does not detail the full return structure (e.g., webhook_secret) nor describe error conditions. For a creation tool, this is a notable gap.

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

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

With 100% schema coverage, the description adds significant meaning beyond the schema: concrete examples for each type, constraints like 'sponsor or condition required' for clinical_trial, webhook details. The examples greatly aid parameter understanding.

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

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

The description clearly states the verb 'Create', the resource 'proactive monitoring subscription', and the key outcome 'Returns the new subscription id'. It distinguishes from sibling tools like list_subscriptions 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?

The description provides extensive usage context: requirements (Pipeworx OAuth account), supported types with examples, delivery channels with constraints. It lacks explicit 'when not to use' guidance 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, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable context: it returns 'category-bucketed example questions' with 'exact tool + argument shape' and that questions are 'drawn from the live catalog'. This transparency about the return format and dynamic sourcing exceeds 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 moderately long but well-structured with a clear opening, examples of trigger questions, explanation of return content, and invocation instructions. Every sentence adds value. It is slightly verbose due to listing categories, but this aids understanding.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, how to invoke it (with and without arguments), and what the output contains (categorized example questions). Nothing essential is missing for an agent to decide and use it correctly.

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

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

The schema covers the parameter 100%, but the description adds meaning by listing example values ('finance, pharma, economics...') and explaining the behavior when omitted ('call with no arguments for the full spread'). This helps the agent understand the parameter's domain and effect beyond the schema's simple type string.

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

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

The description clearly identifies the tool as the onboarding entry point for new agents, listing the exact questions it answers and distinguishing it from sibling tools by mentioning meta-tools like ask_pipeworx, entity_profile, etc. The verb 'returns example questions' with specific categorization provides a concrete purpose.

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

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

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass a topic versus no arguments. It does not explicitly state when not to use it, but the context is clear and provides good guidance on invocation.

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

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

Adds behavioral context beyond annotations: explains that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts'. No contradiction with annotations (idempotent, non-destructive).

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, each earning their place. Front-loaded with action, followed by ownership and deactivation details. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, deactivation behavior, and links to historical access. 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 a description for 'id'. The tool description reinforces by mentioning 'by id', but adds no new semantic information 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 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

Explicitly mentions ownership enforcement: 'you can only cancel your own subscriptions,' providing a critical usage constraint. Lacks explicit guidance on when not to use or alternatives, 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 declare readOnly, idempotent, openWorld. Description adds context about replacing multiple calls and details return format (verdict, citation, delta). 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 somewhat lengthy but front-loaded with examples. Could be more concise, but 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?

Even without output schema, description details return values. Single parameter is well-documented. Adequate for tool 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 covers 100% of parameter 'claim' with description. Description adds examples but no significant extra meaning 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 indicates tool verifies natural-language claims against authoritative sources, with specific examples (company-financial claims). Does not explicitly differentiate from sibling tools but is sufficiently 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?

States 'use whenever the agent needs to check factual correctness' and provides example queries. Does not explicitly describe 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.