Openagenda

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

The description discloses key behaviors: it probes LLMs, scores visibility per model, uses a default free model, and requires an API key for Anthropic which is passed directly. These details complement the annotations (readOnlyHint, etc.) without contradiction, providing full 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 concise yet informative, using four sentences that front-load the purpose and progressively add details about models, API key, return structure, and use cases. 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?

Despite lacking an output schema, the description thoroughly explains the return format (per-model score, confidence, signals, raw_response plus combined view), covering all necessary aspects. Given the tool's moderate complexity, this is sufficient.

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

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

With 100% schema coverage, the description still adds value by explaining the default model (Workers AI Llama-3.3-70b) and the optional _apiKey for Anthropic, which are not fully described in the schema. It also clarifies the purpose of the 'context' parameter.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic and returns a score 0-100. It specifies the default model and optional Anthropic probing. This distinguishes it from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence' which have different focuses.

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 use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), giving clear guidance on when to use. However, it does not explicitly exclude scenarios or contrast with alternatives like 'scan_competitor_ai_presence', though the unique purpose is implicit.

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 meaningful behavioral context: routing to many tools, filling arguments, returning stable pipeworx:// citation URIs, working on every tier, and being a fast default entry point. This goes beyond the annotations without contradicting them.

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

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

The description is longer than average but well-structured: it front-loads the primary message ('PREFER OVER WEB SEARCH'), explains the mechanism, provides usage triggers, and lists alternatives. Each sentence adds value, with minimal redundancy. A slight trimming would be possible, but the length is justified by the tool's broad scope.

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 the absence of an output schema, the description is thorough. It covers what the tool does, when to use it, how it behaves, what output to expect (structured answer with citations), and when to escalate to alternative tools. This provides a complete picture for an agent to decide when to invoke it.

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

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

The schema description provides 100% coverage for the 'question' parameter, including aliases and examples. The description adds semantic guidance by explaining what constitutes a good question (factual, real-world entities) and offering concrete examples, which helps the agent use the parameter effectively beyond the schema's basic documentation.

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: routes questions to one of 5,462 tools across 1,419 verified sources and returns structured answers with citation URIs. It also distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, making the 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?

The description gives explicit when-to-use guidance, listing trigger phrases like 'what is', 'look up', and 'get the latest', and says 'START HERE for most questions.' It also provides exclusions, instructing when to step up to ask_pipeworx_grounded or deep_research, and specifies types of queries best served by web search instead.

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

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

The description adds valuable context beyond the annotations by disclosing the live experimental nature, current status ('No candidate is active right now'), that it matches ask_pipeworx exactly when idle, and that it 'Falls back to nothing' yet remains a full working router. This complements the readOnly, openWorld, and idempotent hints without contradicting them.

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

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

The description is informative but somewhat longer than necessary, with multiple clauses explaining the beta status, current inactivity, usage guidance, and fallback. However, it is well-structured and front-loaded with the core purpose in the first sentence, and each sentence contributes useful context.

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 an experimental variant of a large router with no output schema, the description covers key aspects: what it is, current state, how to use it, and that response shape matches ask_pipeworx. It is complete enough for an agent to select and invoke it correctly, though it lacks explicit details about potential behavioral changes during active tests.

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 for parameters is 100%, and the schema already explains the question field and aliases. The description only says 'same arguments' as ask_pipeworx, which is a reference but does not add specific new meaning beyond what the schema already provides. Thus the baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with 5,462 tools, and explains it enables experimental routing improvements. It distinguishes itself from the stable ask_pipeworx and other siblings by emphasizing its experimental edge and live candidate testing.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This provides clear context for when to use it, though it does not explicitly state when not to use it or name alternatives beyond ask_pipeworx.

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?

Despite annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds critical behavioral details: the exact return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}), the list of refusal reasons, the direct-citation guarantee, and the extra LLM call cost. It discloses failure modes explicitly. No contradiction with annotations.

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

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

The description is dense but well-structured: it leads with the core value proposition, explains the mechanism, details the output/refusal format, provides usage guidance, and closes with a cost comparison. Every sentence adds meaningful information; no fluff or repetition.

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

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

The description is fully self-contained for an agent. It covers what the tool does, when to use it, what it returns (success and refusal), cost implications, and relationship to siblings. Given no output schema exists, the explicit return contract is particularly valuable.

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 clear 'question' parameter description and all aliases documented. The description adds no additional parameter-level semantics, which is acceptable since the schema fully covers the parameter meaning. No gaps to compensate.

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 a 'hallucination-resistant answer mode' and explains it extracts answers using only the tool result content. It explicitly distinguishes itself from ask_pipeworx ('same routing as ask_pipeworx') while positioning its unique grounded extraction behavior, making it clearly distinct from its primary sibling.

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 when to use this tool: 'whenever an answer will be quoted, cited, or acted on' and provides concrete examples (financial verdicts, legal claims, medical lookups). It also gives an explicit alternative: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off (one extra LLM call).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, which are consistent. The description goes far beyond, detailing resolution, classification, fan-out, evidence packet, market_match_confidence, parent_event extraction, news fallback fields, safety for low-confidence matches, closed markets, wide spreads, and cancellation rules. 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 lengthy but well-structured with clear section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It is front-loaded with purpose and usage. While some detail could be trimmed, every sentence serves a purpose. For a complex tool, the trade-off between conciseness and completeness is appropriate.

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

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

Despite having no output schema and moderate complexity (3 parameters), the description covers all necessary context: fan-out logic, response structure, edge cases (low confidence, closed markets, wide spreads), resolution rules, and news fallback. An AI agent has enough information 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 three parameters (market, depth, include_raw). The description adds significant value: for 'market', it explains formats (slug, URL, question text); for 'depth', it gives quick vs thorough detail; for 'include_raw', it explains default behavior and trade-offs. This enhances understanding beyond the schema.

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

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

The description states exactly what the tool does: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It uses a specific verb (research), identifies the resource (Polymarket bet), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on data gathering and analysis. The purpose is clear and unique.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear usage scenarios. It does not explicitly state when not to use or compare with alternatives, but the context is sufficient for an AI agent to infer appropriate use cases. The examples and classifiers further guide usage.

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 detailed behavioral traits beyond annotations: for company type, it pulls latest 10-K data from SEC EDGAR/XBRL with proper handling of off-calendar fiscal years; for drug type, it pulls FAERS, FDA approval counts, and trial counts. It also mentions sorted results and citation URIs, adding significant context to the read-only and idempotent annotations.

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

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

The description is well-structured and informative, with example queries upfront. However, it is slightly verbose with redundant phrases like 'in ONE parallel call' and 'replaces 8–15 sequential lookups', which could be condensed without losing clarity.

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

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

Given the absence of an output schema, the description provides comprehensive context: data sources for each entity type, sorting behavior, citation URIs, and efficiency gains. It fully equips an agent to understand what the tool does and what to expect.

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 has 100% description coverage with clear parameter meanings. The description adds minimal extra semantics beyond context (e.g., tickers vs names for company/drug) but does not elaborate on constraints or formats 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 performs side-by-side comparisons of 2–5 companies or drugs, with example queries like 'compare X and Y', and distinguishes itself from siblings by specifying it should replace sequential single-entity 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?

The description explicitly says to prefer this over sequential single-pack lookups when comparing entities, and provides example query patterns (e.g., 'compare X and Y', 'which is bigger'). It clearly defines the use case and alternative approach.

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

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

The description discloses extensive behavioral traits beyond the annotations: account requirements, return format (gaps[], contradictory findings, hop field), non-invention of answers, citation resolvability, semantic excerpting, and latency ranges. It does not contradict the readOnly/openWorld/idempotent hints; rather, it enriches them with concrete operational context.

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

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

The description is long but densely packed with non-redundant information, front-loading account requirements and the core distinction from open-web search. Some minor repetition occurs (paid plan mentioned both in description and schema), and the length is at the edge, but every section contributes to correct selection and invocation. A slight structural tightening would earn a 5.

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

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

For a complex tool with no output schema, the description comprehensively explains what the tool returns: findings packet structure, citations, gaps[], contradictions[], hop field, and latency expectations. It also covers prerequisites and alternatives, making it complete for an agent to decide when and how to invoke it.

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

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

Although the schema covers both parameters fully, the description adds critical semantic context beyond the schema descriptions: it explains the practical impact of depth levels (gap recovery, contradiction scanning, paid tier), confirms that broad questions are acceptable, and links depth to latency. This enriches the schema without redundancy.

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

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

The description clearly identifies the tool as a grounded multi-source research engine over Pipeworx's structured data sources, decomposing questions into facets and returning a findings packet. It explicitly differentiates from siblings by stating it is NOT open-web search and contrasts with ask_pipeworx for single lookups and news, making its purpose unmistakable.

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

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

The description provides explicit usage guidance: when to use deep_research (broad/multi-part questions over structured data), when to use ask_pipeworx instead (single lookups, breaking/current news), and prerequisites (account required, thorough needs paid plan). It also explains depth-level behavior and alternatives, covering both fit and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining that results are 'ready to call directly, no second schema lookup needed,' which is not captured in annotations.

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

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

The description is front-loaded with the core purpose and is about 100 words. It includes a helpful list of example domains. While slightly lengthy, every sentence adds value; no redundancy.

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

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

Given the lack of output schema, the description sufficiently covers what the tool does, when to use it, and what it returns (names, descriptions, schemas). It provides enough context for selection and invocation.

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

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

Schema coverage is 100%, so the schema documents all 6 parameters. The description adds context by listing acceptable aliases (task, q, search, description) and clarifying that 'query' influences relevance. This goes beyond the schema.

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

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

Clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the verb 'find/discover' and the resource 'tools', and details what is returned (top-N, schemas, examples). This distinguishes it from sibling tools that are task-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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear usage context. Could be improved by explicitly stating not to use when you need a direct answer, but the guidance is effective.

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 behavioral context beyond annotations: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), details return fields, notes that patents soft-fails after May 2025, and emphasizes it's a single parallel call. Annotations already indicate readOnly, openWorld, idempotent, non-destructive; description enriches 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?

Description is long but front-loaded with example queries, making it easy to scan. Every sentence contributes unique information. Could be slightly more concise without losing clarity, but overall well-structured.

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

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

Despite no output schema, the description fully documents all return fields (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers source dependencies, sunset notices, and fallback behavior, making it self-contained for agent decision-making.

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

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

With 100% schema coverage, the description still adds value by explaining parameter usage: value accepts ticker or zero-padded CIK, explicitly states names not supported, and type only supports 'company'. Examples like 'AAPL' and '0000320193' clarify format.

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

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

Description clearly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. Examples like 'Tell me about X' and specific return fields (CIK, filings, fundamentals) make the purpose unmistakable. It also contrasts with chaining single-pack lookups, distinguishing it from sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view.' Also warns that names are not supported and directs to use resolve_entity first. This provides clear when-to-use and when-not-to guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. Description adds that results default to upcoming events, and return specific fields with language preference (English where available, else French). This provides useful behavioral context beyond annotations.

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

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

Two sentences, no wasted words. Front-loaded with purpose and essential details (source uid, defaults, optional filters, return fields). Every sentence contributes.

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 lists return fields (title, dates, venue, coordinates, keywords), which is adequate. Mentions language preference. Could optionally note pagination via 'size', but it's handled in schema.

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

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

Input schema has 100% coverage with descriptions for all 5 parameters. Description adds value by stating default behavior: 'from' defaults to today (upcoming), 'size' defaults to 20, and 'query' is a keyword filter. These clarify schema semantics.

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

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

Description clearly states it lists events from a single OpenAgenda agenda, referencing the source uid from sibling tool 'search_agendas'. It specifies defaults (upcoming events) and optional filters, and lists return fields. This distinguishes it clearly from sibling tools like search_agendas.

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 instructs to get the uid from search_agendas, which is a sibling tool. It implies when to use (when you have an agenda uid) and describes optional filters. Lacks explicit when-not-to-use scenarios, but the context is sufficient.

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

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

Annotations already flag destructiveHint=true. Description reinforces 'delete' and adds context about clearing sensitive data, which is helpful. No contradictions. However, it doesn't disclose whether deletion is reversible or what happens if key doesn't exist.

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 defines function, second gives usage contexts. No fluff, perfectly 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 single-parameter destructive tool with full annotation coverage, the description provides sufficient context including when and with what to use. No return value information needed as no output schema exists.

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 both parameter name and description fully. Description doesn't add extra semantics beyond the schema's 'Memory key to delete'. The parameter semantics are clear from 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?

Clearly states verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings remember and recall by describing its delete action. The pairing mention reinforces its purpose.

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

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

Explicitly lists three usage scenarios: stale context, task completion, clearing sensitive data. Also advises to pair with remember and recall, providing guidance on when not to use in isolation.

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 behavioral details (fetches page, extracts title/description/key links, emits markdown) without contradicting annotations.

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

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

The description is concise (three sentences), front-loaded with the core action, and every sentence adds value. No redundant or vague phrasing.

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

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

Given the low parameter count and presence of annotations, the description covers purpose, usage, parameter details, and output format adequately. Could mention the output is plain text, but 'single text blob' and 'standard llms.txt markdown format' suffice.

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 context beyond schema: parameter descriptions are supplemented with examples (e.g., 'https://example.com' or a specific landing page) and defaults for max_links (default 25, max 50).

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

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

The description clearly states the tool generates an llms.txt file for a given URL, listing specific steps (fetches, extracts, emits). It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence which focus on analysis rather than generation.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing), providing clear context. It does not explicitly state when not to use, but the sibling tools are distinct enough that no confusion arises.

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, so the description adds extra value by specifying that only the caller's subscriptions are returned and listing the fields. 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?

Two sentences, front-loaded with the main purpose, no redundant information. Every word 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 simple tool (one optional boolean parameter, no output schema), the description lists return fields and usage context, making it complete enough for the 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 the single parameter well-described. The description does not add additional meaning beyond what the 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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 use this tool before adding more subscriptions or to find an ID for cancellation, providing clear context and exclusions.

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

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

The description discloses important behavioral traits: rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, team reads digests daily, and signal affects roadmap. It also advises not to paste the end-user's prompt. All annotations are false, so there is no contradiction; the description enriches beyond annotations with actionable constraints.

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 paragraph with dense, purposeful content. It starts with the core purpose, then flows through usage cases, exclusions, tips, and constraints. Every sentence earns its place—no fluff or redundancy. The structure is logically ordered and scannable.

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 (3 params, enum, nested object) and absence of output schema, the description covers all necessary context: what to report, how to frame it, scope limitations, rate limits, quota impact, and what the team does with feedback. It is fully self-contained for an agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter guidance: it instructs to describe issues in terms of Pipeworx tools/packs and not to paste the end-user's prompt, which directly informs the 'message' parameter. It also clarifies how 'context' should be used (which tool, pack, or vertical). This goes beyond the schema's field 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the resource (Pipeworx team) and the action (send feedback), and distinguishes itself from siblings by noting it is ONLY for tools served by this Pipeworx connection, contrasting with other MCP servers.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an explicit exclusion: if the tool came from a different MCP server, file it there instead. This fully covers when and when-not to use.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. 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?

Concise at ~70 words, well-structured with numbered use cases. Every sentence adds information; no fluff or repetition.

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

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

No output schema, so description should clarify response format. It mentions 'top tools, top packs, and total call volume' but does not specify structure (e.g., array of objects with counts). Adequate but could be more precise.

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 full enum description. The description adds guidance on how window choice affects results (hot vs steady-state), providing additional semantic value beyond the schema.

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

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

The description clearly states the tool returns trending data: top tools, packs, and call volume over a recent window. It differentiates from sibling tools like discover_tools by focusing on popularity metrics.

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

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

Three explicit use cases are provided (discovering hot sources, confirming canonical tools, alignment check). However, it does not explicitly state when not to use this tool or suggest alternatives beyond the listed use cases.

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

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

Annotations already mark the tool as read-only, idempotent, non-destructive. The description adds rich behavioral details: how arbitrage detection works, semantic anchor logic, partition filter, fill check with live book, and edge cases like placeholder filtering. 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 well-structured with clear sections and bold headers, but somewhat verbose in explaining every nuance. Could be slightly more concise without losing essential information. Overall good organization 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 no output schema, the description thoroughly explains the return structure (opportunities[], partition_check details, fill check). It covers edge cases, warns about overround only at last-trade, and provides enough context for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, baseline 3. The description adds substantial meaning beyond the schema by explaining the logic behind each parameter, providing examples, and detailing the processing for 'event' and 'topic'. Very helpful for correct invocation.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (default trending scan, event mode, topic mode) and specifics like semantic anchor and fill check, leaving 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?

Provides explicit guidance: call with no args for trending scan, pass event for specific market, pass topic for cross-event scanning. It explains when to use each and warns against trading when fill check shows realizable_edge_pp ≤ 0. Also references polymarket_fill_risk for custom sizing.

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 is extremely detailed, explaining model families, edge calculations, caching (1h KV), response structure, diagnostics, and knob behavior. The annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent and fully supplemented by this rich 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 front-loaded with purpose and is comprehensive, but it is lengthy and includes detailed technical specifics (e.g., per-sport alpha values, exact logic for concentrated longshots). While appropriate for the complexity, it could be slightly more concise without losing 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?

For a tool with 9 parameters, no output schema, and a complex response structure, the description is exceptionally complete. It covers the response top-level, diagnostics, caching, and how filters interact, ensuring an agent has sufficient context to use the tool effectively.

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

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

All 9 parameters are well-defined in the input schema (100% coverage). The tool description adds contextual value by explaining how knobs like min_liquidity and max_spread_pp act as 'tradeable-edge filters' and by providing narrative on parameter interaction. This goes beyond bare schema definitions.

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

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

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

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

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

The description provides strong context for when to use the tool (discovery of betting opportunities) and mentions that Fed bets are excluded from ranking. However, it does not explicitly state when not to use it versus specific alternatives like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant context: history depth is bounded by 60-day TTL, decay uses daily closes not intraday, snapshot gaps mean no scan. Response fields (tracked, expired, snapshot_dates) are fully explained, with no contradictions.

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

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

The description is detailed and front-loaded with purpose, but it is a single dense paragraph. Response fields are explained inline; using bullet points or clear sections would improve readability. Every sentence adds value, but structure could be better.

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 thoroughly explains the return structure (tracked, expired, snapshot_dates) with subfields and meaning. Parameters are simple and fully described. The tool is well-specified for its 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 both parameters (days, window) with descriptions. The description adds extra value by listing valid window families (24hr, 1wk, 1mo) and clarifying that days is clamped 2-30, going beyond the schema. Coverage is 100%, so baseline is 3; this extra detail earns 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 provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings like polymarket_edges by focusing on historical tracking and trend analysis.

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

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

The description explains when to use the tool (to assess edge age and decay) and contrasts fresh vs old wide edges. However, it does not explicitly mention when not to use or directly name alternative tools, though the context implies polymarket_edges for current edges.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds significant operational context: it checks realizable vs theoretical edge, walks the order book ladder, returns verdicts and risk flags (thin legs, forced directional risk). This goes beyond annotations but could mention any performance or reliability constraints.

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

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

The description is lengthy but well-structured: begins with core purpose, then details each mode, return fields, and usage guidance. Every sentence adds value, though some repetition occurs (e.g., default auto for basket side). For the tool's complexity, it is appropriately 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?

Given the complexity, full parameter schema coverage, and annotations, the description provides a thorough understanding of inputs, behaviors, and use cases. It lacks explicit error handling or timeouts, but the verdicts cover failure modes. It 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?

Schema coverage is 100%, but the description adds extensive meaning: it explains the dual mode (market/event), side semantics in both contexts, size_usd interpretation (spend vs target proceeds vs settlement notional), and default values. It clarifies mutual exclusivity of market and event, which is not in 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 checks realizable vs theoretical edge against live order book depth, and distinguishes two modes (single-market and basket). It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making the 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?

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround not capturable, partial basket fills convert arb to directional), making it clear when to prefer 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses key behavioral traits: compatibility_warning for shape mismatches, temporal_alignment for date resolution differences, detailed skip counters (cross-type, cross-subtype), and explicit caveats about tradeability. This far exceeds the minimal 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 verbose with multiple paragraphs and some redundancy (e.g., 'pre-mapped ≠ tradeable' repeated). However, it is front-loaded with the core purpose and well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS), which aids skimming. Every sentence earns its place but could be tighter.

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 absence of an output schema and the tool's complexity (cross-venue spread with edge cases), the description fully explains response fields (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment, skip counters) and covers all safety/error conditions. 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%, but the description adds meaning: it explains the topic parameter's shortcut list (10 pre-mapped macros) and the override behavior of kalshi_event_ticker/polymarket_event_slug. While helpful, some of this context is already in the schema descriptions; the addition is moderate.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', using a specific verb and resource pair that distinguishes it from sibling tools like polymarket_arbitrage (single-venue) or other market analysis 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 explains two modes (topic shortcuts or explicit tickers) and warns that most pre-mapped topics return compatibility warnings today, providing explicit when-not-to-use guidance. However, it does not directly compare with alternative tools (e.g., polymarket_arbitrage for intra-venue analysis), which would solidify the score to 5.

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

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

Description aligns with annotations (readOnly, idempotent, non-destructive) and adds context about scoping to identifier, exceeding 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?

Two concise sentences, front-loaded with action, 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?

Covers all needed aspects: purpose, usage, behavior, parameters. Adequately complete for a simple retrieval 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%, and the description adds meaning by explaining the dual behavior (omit key to list all).

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 (saved keys/values), distinguishing it from siblings like remember and forget.

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

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

Explicitly describes when to use the tool (look up stored context) and pairs with remember/forget, though no explicit when-not-to-use is given.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by explaining the mark_read flag's effect on subsequent calls and that polling is fine, aligning with 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?

The description is reasonably concise for the information it conveys, starting with the core purpose. Some redundancy could be trimmed, but overall it is well-structured and informative.

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 sufficiently outlines return fields (source, citation_uri, raw payload) and behavior (mark_read, polling). It also provides an alternative access method, making the tool self-contained 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%, but the description enriches each parameter: e.g., type exemplified with 'sec_8k', since described as ISO timestamp, mark_read explained in terms of feed state. This adds significant clarity beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: pulling fired events from a subscription feed, returning specific fields. It differentiates from siblings by focusing on alerts from the feed, but does not explicitly contrast with tools like 'events' or '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?

Provides usage context (filtering by type/since, mark_read behavior, polling suitability) and mentions an alternative endpoint for scripts. However, it does not explicitly guide when to use this tool over sibling tools, leaving some ambiguity.

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

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

Annotations declare read-only, idempotent, and non-destructive. Description adds details on fan-out to multiple sources, fallback logic, soft-failures, and output structure 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?

Concise, front-loaded with examples, all sentences add value. No wasted words.

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

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

Despite no output schema, description explains return structure (grouped changes, total_changes, citation URIs) and covers all complexity including fallbacks and soft-failures.

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 meaning by explaining since formats, suggesting '30d', and clarifying value as ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company, with example queries. It explicitly distinguishes from sibling tool entity_profile.

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

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

Provides explicit guidance on when to use this tool vs. entity_profile, fallback behavior for data sources, and parameter usage with typical defaults.

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

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

Discloses key scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) sessions. Annotations confirm idempotent and non-destructive, with no contradictions.

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

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

Four sentences: purpose first, then usage guidance, then behavioral details, then pairing. Every sentence adds value; no superfluous words.

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

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

Covers all key aspects: purpose, when to use, data scope, persistence, and companion tools. No missing information given the 2-param schema and annotations.

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

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

Schema covers both parameters with descriptions; description adds concrete usage examples (e.g., 'subject_property', 'target_ticker') and value types, enhancing 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 starts with a specific verb 'Save data' and clearly states the resource (data for reuse across conversations/sessions). It distinguishes from sibling tools like recall and forget by naming them directly.

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 ('when you discover something worth carrying forward'), lists example scenarios, and directs to pair with recall/forget for retrieval/deletion.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about internal cascading lookups and the specific return objects (ticker/CIK, RxCUI/ingredient/brand) with citation URIs, going 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 front-loaded with user-phrase examples and well-structured into sections for each entity type. While slightly long, every sentence provides essential usage details and 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?

With no output schema, the description fully explains return values for both entity types, including citation URIs and accepted input forms. It also covers disambiguation behavior and the tool's purpose in the broader workflow, making it complete 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 field descriptions, so baseline is 3. The description adds extra meaning by giving concrete examples for each type (e.g., ticker, CIK, brand names) and explaining auto-disambiguation and return formats, making parameter usage clearer.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with explicit examples and detailed supported types. It distinguishes itself as the go-to name-to-ID lookup tool, distinct from sibling tools that don't serve this purpose.

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

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

The description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies that it replaces 2-3 manual lookups, giving strong context for when to invoke this tool over 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 false. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list, which is useful context but does not introduce new behavioral traits 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 two sentences with no wasted words. The first sentence describes the core action, the second adds details and a use case example. Information is front-loaded and easy 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?

Given the tool has no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density per entity). It mentions that it uses another tool and provides context about ordering. Minor gap: does not specify sorting direction (descending by score), 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 description coverage is 100%. The description adds semantic value by specifying that the 'entities' array must have 2-8 entries, the first is treated as the subject, and that 'context' is optional shared context. It also clarifies the 'models' parameter defaults to workers-ai and that anthropic requires an API key.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and produces a ranked list. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility context.

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 concrete use case for competitive AI-marketing audits and implies when to use (comparing multiple entities). It doesn't explicitly state when not to use or mention alternatives, but the context is clear enough for an 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?

Discloses partial failures and timing ('bundlephobia's first measurement on a new version can take 5-30s'), and that sources_failed will list timeouts. Annotations already indicate read-only, idempotent, non-destructive, and open-world, and the description adds valuable behavioral context beyond annotations.

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

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

The description is detailed yet concise, front-loaded with the core purpose. Every sentence adds value without redundancy, covering purpose, usage, ecosystem limitations, and return format 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?

No output schema exists, but the description fully explains return structure (summary block fields, per-advisory details, links, alternative versions) and handles edge cases like partial failures, making it complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that scoped packages are accepted and version defaults to latest, providing extra 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 it's a composite check for 'should I add this npm package' using deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and the tool's unique combined functionality distinguishes it from sibling tools.

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

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

Explicitly tells when to use ('whenever an agent asks 'is X safe / popular / small''), and provides exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), guiding when not to use and mentioning 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: 'Most agendas are French,' which informs geographic bias. No contradictions with annotations.

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

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

The description is extremely concise: two sentences that are front-loaded with the core purpose, include an example, and specify output details. 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?

Given the absence of an output schema, the description adequately specifies the return values (uid, slug, title) and provides workflow context. The mention of French bias adds completeness. No major gaps for a search 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?

The input schema has 100% coverage with detailed descriptions for all three parameters. The description does not add additional semantic information beyond what the schema already provides, meeting the baseline expectation.

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 action (Find), the resource (OpenAgenda agendas), and the criteria (by keyword), with concrete examples. It distinguishes from sibling tools by focusing on agenda search as opposed to events retrieval or other search 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 provides actionable guidance: 'Pass the uid to the events tool.' It implies a workflow but does not explicitly state when to avoid this tool or mention alternatives. Still, it offers clear contextual use.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Two sentences, no wasted words. Could be slightly more structured (e.g., separate sections), but front-loads the core action and key differentiator.

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

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

Despite no output schema, the description explains return type (passages with offsets and similarity scores), limitations (200K char cap), and pairing with another tool. Fully adequate for a search tool with rich annotations.

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

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

Schema coverage is 100% and description adds meaning to each parameter: 'text' gets a max length and example source, 'query' gets example queries, 'limit' gets range and default. This enriches the schema.

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

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

The description uses a specific verb ('Search') and resource ('within a Source'), clearly stating it performs semantic search inside a fetched record. It also distinguishes from sibling tools like 'ask_pipeworx_grounded'.

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

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

Explicitly advises when to use: when a record is too big for the prompt, saving context and enabling verification via character offsets. Also pairs with 'ask_pipeworx_grounded' for post-search grounded generation.

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 detailing OAuth requirement, subscription type specifics, delivery limitations (10/day SMS cap, webhook auto-disable), and the always-on feed. No contradiction with annotations.

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

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

The description is well-structured with a clear front-loading of purpose and return. It is somewhat verbose with detailed examples but 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 the tool's complexity (3 parameters, nested objects, multiple types) and no output schema, the description covers all necessary context: requirements, types, parameters, delivery channels, limitations. An AI agent can confidently use this tool.

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

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

Schema coverage is 100%, and the description adds significant context: type enum values explanation, params structure with examples per type, and delivery object constraints (phone verification, SMS cap, webhook HMAC signing).

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 creates a proactive monitoring subscription to a live-data event stream and 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 specifies requirements (Pipeworx OAuth account), supported types with parameters, and delivery channels. It lacks explicit guidance on when not to use this tool vs alternatives but provides sufficient 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, openWorldHint, idempotentHint, and destructiveHint, so the behavioral safety profile is well-covered. The description adds valuable behavioral context like returning 'category-bucketed example questions' and 'exact tool + argument shape,' which helps the agent understand what the tool produces.

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

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

The description is thorough but perhaps slightly longer than necessary. It front-loads the purpose (onboarding entry point) and lists use cases. Every sentence adds value, but could be tightened by removing the inline enumeration of categories.

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 single optional parameter and the presence of comprehensive annotations, the description is complete. It explains the return value (categorized example questions with tool references), when to call, and how to use the topic parameter. No output schema is needed.

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

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

Schema coverage is 100% with one optional parameter fully described. The description adds meaning by providing example values ('finance', 'pharma') and clarifying that omitting the argument gives the full spread, while passing a topic focuses results.

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 that this tool is an onboarding entry point, returning category-bucketed example questions with tool references. It uses specific verbs like 'returns' and 'draws from the live catalog,' clearly distinguishing it from sibling tools like ask_pipeworx or 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?

The description provides explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains when to use the topic parameter versus omitting it, and mentions alternatives by listing meta-tools to learn.

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 it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds value by explaining that ownership is enforced, the row is deactivated (not deleted), and historical events remain available, which aligns with and elaborates on the idempotentHint and openWorldHint annotations.

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

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

The description is three concise sentences with the key action front-loaded. Every sentence adds essential information without redundancy.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description fully covers the purpose, usage constraints, and behavioral outcome. 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 description coverage is 100% and the parameter 'id' is well-described as a UUID returned by subscribe. The description adds minimal extra meaning beyond stating 'by id', which is already clear. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by ID, using the specific verb 'Cancel' and resource 'subscription'. It implicitly distinguishes itself from the sibling tool 'subscribe' by being the inverse operation.

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

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

The description provides clear usage context: ownership enforcement so you cannot cancel others' subscriptions, and that the row is deactivated rather than deleted, preserving historical events. It does not explicitly mention when not to use it, but the constraints are well-stated.

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 significant behavioral context: internal routing logic (fast path vs. grounded pipeline), return value structure (verdict, value, citation, reasoning), and tolerance handling. 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 thorough but well-structured: starts with example queries, then usage guidance, then return. While long, every sentence adds value for a complex tool. Minor room for trimming, 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?

Given the tool's complexity, high schema coverage, and absence of output schema, the description fully covers purpose, usage, behavior, and return values. It provides enough context for correct invocation and is completely differentiated from siblings.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'tolerance_pct' default is implied by wording and capped at 5, and that 'claim' examples illustrate format. This goes slightly 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 validates natural-language factual claims against authoritative sources. It distinguishes from siblings by specifying the two distinct pipelines (company-financial vs. other claims) and explicitly lists example queries.

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

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

Explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' Differentiates behavior for company-financial vs. other claims, and notes it replaces multiple sequential calls.

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