Data Toulouse

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

The description discloses key behaviors: it probes LLMs, scores visibility (0-100), returns per-model data (score, confidence, signals, raw_response) and a combined view. It notes that Anthropic queries require a BYO key and direct payment. Annotations already provide readOnlyHint and destructiveHint=false, so the description adds depth about the scoring scale and cost implications. It does not mention rate limits or error handling, but is otherwise transparent.

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 (about 100 words) and well-structured. The first sentence immediately states the action, input, and output. Subsequent sentences add details on models, API key, return format, and use cases. Every sentence contributes specific 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?

Given no output schema, the description adequately explains the return structure (per-model fields + combined view). It covers input parameters, default behavior, and use cases. It lacks details on error scenarios (e.g., model unavailability) but is sufficient for an AI agent to understand and invoke the tool correctly. The sibling tools provide context but are not referenced in the description.

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 4 parameters are described in the schema (100% coverage). The description adds value by providing examples for 'entity' (e.g., 'Pipeworx', 'OpenInvoice') and explaining the purpose of 'context' (disambiguate common names). It clarifies that '_apiKey' is only needed if 'anthropic' is in models and that it's passed through to api.anthropic.com. This enriches 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: probing one or more LLMs for knowledge about a business/brand/product/topic and scoring visibility (0-100) per model. It specifies the default model (Workers AI Llama-3.3-70b free) and the condition for using Anthropic (requires _apiKey). This distinguishes it from siblings like 'scan_competitor_ai_presence' by focusing on general entity visibility rather than just competitors.

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 guidelines on when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring). It explains the default model and how to enable Anthropic via _apiKey. However, it does not explicitly state when not to use the tool or mention alternative tools, though the context signals and sibling list imply alternatives exist.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context: the tool routes to 4,862 tools, fills arguments, returns citation URIs, works on every tier, and is fast. It doesn't disclose limitations like unknown quality for very niche topics, but with annotations, the added context is substantial.

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

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

The description is relatively long but each sentence serves a purpose: preference, routing, examples, sibling differentiation. It is front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. Could be slightly more concise, but effective 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 complexity (6 params, many siblings, no output schema), the description is fairly complete. It explains the internal routing, output format (structured answer with citation URIs), and provides usage examples. It lacks detailed return structure but compensates with examples and clarity on when to use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions that parameters are aliases for the question and accepts natural language, which adds slight value beyond the schema. No additional constraints or formatting details are provided.

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: answering questions about current or historical data from many authoritative sources. It uses specific verbs like 'routes the question' and 'returns structured answer', and distinguishes from sibling tools like web search, ask_pipeworx_grounded, and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides clear when-to-use and when-not-to-use guidance. It names alternatives (ask_pipeworx_grounded, deep_research) and gives specific examples of questions to route here.

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 readOnly, openWorld, idempotent. Description adds refusal reasons, response structure (answer, evidence, etc.), and extra cost, surpassing annotation-only info 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?

Front-loaded with key purpose and usage; each sentence adds value. Slightly long but justified given the complexity.

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

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

Despite no output schema, description fully details return shape (answer, evidence, etc.) and possible refusal reasons. Comprehensive for a complex tool with many routing steps.

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

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

Schema coverage is 100% but description clarifies that all six parameters are aliases for 'question,' adding semantic meaning beyond the schema's individual 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?

Clearly states it's a 'Hallucination-resistant answer mode for high-stakes reads,' explains the process (routing, fetching, extraction), and distinguishes from ask_pipeworx by noting extra cost and use case.

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

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

Explicitly says 'Use whenever an answer will be quoted, cited, or acted on... Prefer ask_pipeworx for casual lookups,' providing clear guidance on when to use this tool versus its sibling.

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

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

Annotations indicate readOnly, idempotent, and not destructive. The description adds extensive behavioral details: low-confidence short-circuits, closed market handling, wide-spread tradeability, resolution-rule risk, resolver contract semantics, parent-event extraction, and news fallback behavior. 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 verbose but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose and provides comprehensive details. Could be slightly more concise, but every part adds value.

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

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

Given the tool's complexity (diverse classifiers, fan-out logic, multiple edge cases, resolver details, news fallbacks, and output shape), the description is remarkably complete. It covers safety, illiquidity, closed markets, cancellation rules, and parent events. No output schema exists, but response shapes are documented.

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 three parameters (depth, market, include_raw) have schema descriptions. The description adds significant context: market explains valid inputs (slug, URL, question), depth explains quick vs thorough, include_raw explains response size trade-offs. 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?

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question) and output (evidence packet + comparison). The purpose is distinct from sibling tools like polymarket_arbitrage or polymarket_edges, though not explicitly contrasted.

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 usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and classifiers. It does not explicitly state when not to use or list alternatives, but the guidance is clear and contextually rich.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: it uses SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, sorts results by primary metric, and returns citation URIs. No contradictions.

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

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

The description is concise for the amount of information conveyed. It front-loads example queries and key instruction, then details data sources. Minor redundancy in example list, but overall efficient.

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

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

Given the tool's complexity (two entity types, external data sources, no output schema), the description is remarkably complete. It covers data pulled, sorting behavior, and citation format, making it fully actionable without additional context.

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

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

Schema coverage is 100%, so parameters are documented. However, the description adds meaning by explaining what data each type pulls (e.g., revenue, net income for company; adverse events for drug) and gives example values. This exceeds just restating the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It gives specific verbs like 'compare', 'versus', 'rank', and explicitly contrasts with sequential lookups, making the purpose unmistakable and distinct from siblings.

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

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

The description provides explicit guidance on when to use this tool ('ALWAYS PREFER over sequential single-pack lookups') and includes example queries. It also clarifies data sources per entity type, ensuring appropriate use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds value by specifying exactly what metadata is returned (fields/schema, themes, record count) and the functional relationship to the query tool, going 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 a single, well-structured sentence that front-loads the core purpose ('Get metadata') followed by specifics and usage guidance. Every part earns its place with no redundancy or unnecessary words.

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

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

Given the tool's simplicity (one required parameter, 100% schema coverage, robust annotations), the description covers all essential aspects: what it does, what it returns, when to use it, and how to get the input. No gaps are evident for an agent to invoke it correctly.

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

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

The input schema fully describes the single parameter 'dataset_id' as 'Dataset id from search_datasets.' The description reinforces this by telling the agent to get the ID from sibling tool 'search_datasets', adding practical guidance beyond the schema definition.

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

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

The description clearly specifies the verb 'Get metadata', the resource 'Toulouse Métropole Open Data dataset', and details what metadata includes (fields/schema, themes, record count). It also distinguishes from siblings by explicitly stating 'call before query to learn the column names', which sets it apart from the query tool.

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

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

The description explicitly advises to call before query to learn column names, providing clear context for when to use this tool. It implies that query is the alternative for after obtaining schema, though it does not explicitly list when not to use it. This 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description details that results are grounded, not open-web, returns gaps[], hop field, citation_uri, timing (15-60s, up to 90s for thorough), contradictions[] for thorough, and that findings are never invented. This provides 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 relatively long but well-structured, with clear sections for account requirements, core functionality, usage guidance, depth details, and timing. Every sentence adds value, though it could be slightly more concise without losing key points.

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 (2 params, no output schema), the description thoroughly covers behavior, usage, limitations, alternatives, depth levels, and output structure (findings packet with evidence, confidence, source, citations, gaps, contradictions, hop). Complete for effective agent invocation.

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

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

Input schema covers both parameters with 100% coverage. The description adds extra value by explaining depth levels in detail (quick=3, standard=5 with gap recovery, thorough=8 with leads and contradictions) and specifying that question is in natural language. Slight extra nuance 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 performs grounded multi-source research across Pipeworx's 1272 structured data sources, decomposing questions into facets and returning a findings packet. It distinguishes from siblings like ask_pipeworx, specifying that this tool is for broad/multi-part questions over structured data, not single lookups or open-web search.

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

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

The description explicitly provides when-to-use scenarios (broad/multi-part structured data questions) and when-not-to-use (single lookup or breaking news, directing to ask_pipeworx). It also mentions account requirements and that 'thorough' depth requires a paid plan.

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 value beyond annotations by disclosing that results include 'names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly.' This provides behavioral context not covered by readOnlyHint and idempotentHint.

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

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

Description is three sentences, front-loaded with purpose and usage guidance, then return value. Every sentence is informative and efficient. No unnecessary words.

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

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

Despite no output schema, the description explains return content (top-N tools with full details). It covers what the agent can expect, satisfying completeness for a discovery tool with well-documented parameters.

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

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

Schema coverage is 100%, providing baseline. The description adds meaning by specifying that 'query' accepts natural language and listing aliases (task, q, description, search). It also includes examples in the schema. This improves understanding beyond schema alone.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides a specific verb ('find') and resource ('tools'), and lists many example domains. It distinguishes itself from sibling tools by positioning as a discovery mechanism.

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 includes explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set.' It implies when to use but does not explicitly state when not to use or provide alternatives, which is acceptable given the tool's role.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. Description adds specifics: fans out across multiple sources, returns detailed fields, mentions soft-fail for patents. 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?

Single dense paragraph with examples and guidance. Front-loaded with use cases. Efficient but could benefit from slight structuring (e.g., bullet points for return fields).

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

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

No output schema, but description thoroughly lists return fields (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and notes soft-fail. Covers all key aspects for a complex tool.

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

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

Schema coverage is 100%, so parameters are fully documented. Description adds that 'type' only supports 'company' and 'value' accepts ticker or CIK, and names not supported—this adds value beyond schema.

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

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

Description clearly states it creates a 'full cross-source profile of a US public company in ONE parallel call.' Verb 'profile' and resource 'company' are specific. Distinguishes from siblings like 'compare_entities' and 'resolve_entity'.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' Also advises to use resolve_entity if only a name is provided. Provides clear when-to-use and when-not-to.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and pairing, but the core behavior (deletion) is already captured. No contradiction, but minimal added value beyond annotations.

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

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

Extremely concise: two sentences with no wasted words. Front-loaded with the core purpose, then usage guidelines.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the tool does, when to use it, and how it relates to other tools. Completely adequate.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description's 'by key' is redundant, adding no extra semantic 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 verb 'Delete' and the resource 'a previously stored memory by key', and distinguishes from siblings 'remember' and 'recall'. No ambiguity.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with other tools. However, it does not explicitly state when not to use it, but the guidance is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool 'fetches the page, extracts ... and emits the standard llms.txt markdown format,' reinforcing the read-only, idempotent nature. 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 concise with three sentences, front-loading the main action and then explaining the process and use cases. Every sentence serves a purpose with no wasted words.

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

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

For a simple tool with two parameters and no output schema, the description covers purpose, process, output format, and use cases. It lacks details on error handling or edge cases, but is otherwise complete for typical usage.

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

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

Schema description coverage is 100%, so the schema already provides parameter details. The description offers example values (e.g., 'https://example.com') and mentions default for max_links, but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool generates an llms.txt file for a URL for AI crawlers. It specifies the actions (fetch page, extract title/description/key links, emit standard markdown) and immediately distinguishes its purpose from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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: indexing a client's site, drafting for own project, auditing competitor. This provides clear context on when to use the tool. While it doesn't mention when not to use, the use cases are sufficiently specific.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return field details and scope to caller, but does not disclose additional behavioral traits 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 that are concise and front-loaded: first sentence gives purpose and output, second gives usage guidance. No wasted words.

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

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

For a read-only list tool with one optional parameter and comprehensive annotations, the description covers purpose, output fields, and usage context. No output schema needed because return fields are listed.

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

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

Schema coverage is 100%, so the schema already describes the parameter. Description does not add extra meaning beyond the schema's description.

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

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

Clearly states 'List the caller's active subscriptions' with a specific verb and resource. Differentiates from siblings like subscribe and unsubscribe by implying it's for reviewing active ones.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear usage context. Does not explicitly state when not to use it.

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

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

Adds critical behavioral details beyond annotations: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' Annotations are neutral, and description does not contradict 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?

Single coherent paragraph that front-loads purpose and then lists conditions. It is concise but dense with useful information. Slightly long but justified by the depth.

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

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

Covers purpose, usage, rate limits, and message format. No output schema exists, but return value is trivial. Nested object context is well explained. Adequately complete for a feedback 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 already provides 100% coverage with detailed descriptions for all three parameters. The description adds usage guidance but not new parameter semantics; baseline 3 is appropriate.

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

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

Clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It provides specific categories (bug, feature/data_gap, praise) and distinguishes from sibling tools like ask_pipeworx or query.

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

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

Explicitly tells when to use: for incorrect data, missing tools, or praise. Also includes what not to do: 'don't paste the end-user's prompt.' Provides clear context on describing issues.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the agent knows it's safe. The description adds valuable context: self-aggregating, no PII, derived from CF analytics-engine, and cached 5min-1h. This goes 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 well-structured with a lead sentence, bullet-pointed use cases, and a note on data source and caching. Every sentence is informative and there is 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?

The description explains the return values (top tools, top packs, total call volume) and data origins (CF analytics-engine, no PII, cached). For a simple read tool with no output schema, this is sufficiently complete.

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

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

Schema coverage is 100% with one enumerated parameter. The description adds meaning by explaining that shorter windows surface what's hot now and longer windows show steady-state demand, which helps agents choose the right window.

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

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

The description clearly states the verb ('returns') and the resource (top tools, top packs, total call volume) and distinguishes from siblings by focusing on aggregate usage data from other AI agents, which is unique among the sibling tools.

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

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

The description explicitly lists three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases). It provides clear guidance on when to use the tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral details: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), fill check against live CLOB depth, distinction between theoretical vs realizable edge. No contradictions.

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

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

Description is long but every sentence adds value. Front-loaded with overview, then structured by mode, then technical details. Well-organized for an AI agent to parse and understand quickly.

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

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

No output schema, but description explains response structure (opportunities[], partition_check, fill check) and edge cases. References sibling tool for custom sizing. For a complex tool with 2 optional params, it's fully self-contained.

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

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

Both parameters have schema descriptions (coverage 100%). The tool description adds crucial meaning: gives concrete examples for event slug and topic, explains that full URLs work, and describes how each parameter triggers different analysis modes.

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?

Very clear: states tool finds arbitrage on Polymarket via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) with specific verbs and resources. Differentiates from siblings through detailed explanation.

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 each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Explains why cross-event mode catches patterns single-event misses. Provides examples of valid inputs.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds extensive behavioral detail: caching (1h KV), output structure (by_segment, diagnostics), edge calculations (Kelly, slippage, liquidity filters), and warnings like 24h-move. This exceeds the annotation baseline significantly.

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 front-loaded purpose. However, it is long and includes very technical model details (e.g., per-sport α values) that could be condensed. It earns its length by covering all aspects of a complex tool without fluff.

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

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

With no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and all returned fields (edge_pp_net, kelly_fraction, etc.). It also explains why segments might be empty and how to read diagnostics. This compensates fully for the missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description summarizes parameters and knobs but does not add new semantic meaning beyond the schema's descriptions. It provides usage examples (e.g., setting min_liquidity to 5000) but those are already implied by param 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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case ('what should I bet on today'). It distinguishes from siblings by focusing on model-driven and structural analysis rather than pure arbitrage.

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

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

The description provides context for when to use (discovering edges without paging hundreds of markets) and hints at alternatives via sibling names, but lacks explicit when-not-to-use or direct comparison to siblings like polymarket_arbitrage.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description adds extensive behavioral details: it reads snapshots, computes trend/decay, explains snapshot gaps (cache-miss), and notes that decay numbers come from daily closes, not intraday. 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 dense but well-organized: purpose first, then detailed response format, then limits. It is slightly long but every sentence adds meaningful information. Front-loading could be better (the first sentence is good), but structure is clear.

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 provides a thorough explanation of the entire response structure (tracked[], expired[], snapshot_dates[] with field details) despite no output schema. It covers what is returned, how fields are computed, and limits, making the tool fully understandable.

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

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

Both parameters are documented in the schema with 100% coverage. The description adds defaults, max for days, and clarifies window as 'snapshot family' and the specific options it draws from. This adds value 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: telemetry on edge persistence and decay from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes a fresh wide edge from a 3-week-old one, making it unique among siblings.

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

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

The description explains what the tool answers and includes LIMITS (history depth bounded by 60-day TTL and snapshot start date), providing context for use. However, it does not explicitly contrast with sibling tools like polymarket_edges or polymarket_arbitrage, leaving some inference required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, non-mutating check. The description adds behavioral context: walks the order book, returns specific fields like slippage and verdict, and warns about partial fills converting arbs into unhedged positions. This goes 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 comprehensive but somewhat verbose. It is well-structured with capital-letter headings (SINGLE-MARKET, BASKET) and clear separation of modes. Every sentence adds value, though some trimming could be possible without losing clarity. Still, it earns a high score for efficient communication of complex logic.

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 lists all return fields for both modes (top_of_book, vwap_fill_price, etc.) and explains the verdict. It covers input requirements, default behaviors, and risk warnings (thin legs, forced directional risk). For a tool with two modes and complex return data, this is complete.

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

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

Schema coverage is 100%, with descriptions for all 4 parameters. The description adds additional meaning: defaults (size_usd=1000, side default for basket auto), interpretation of size_usd in basket mode as 'settlement notional', and the requirement that exactly one of market or event must be supplied. 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 clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on their signals.

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

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

The description provides explicit when-to-use guidance: 'REQUIRES one of `market` or `event`' and 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about thin books and partial fills, helping the agent decide when not to use it.

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

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

Annotations already indicate safe read-only, open-world, idempotent behavior. The description adds critical behavioral details: compatibility warnings for non-equivalent bet shapes, temporal alignment, and skipped cross-type/subtype counters. No contradictions with annotations.

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

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

The description is dense but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though it could be slightly more concise. It's front-loaded with the core purpose.

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

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

Given the tool's complexity (cross-venue, multiple safety fields, two modes, no output schema), the description is extraordinarily complete. It explains all return fields (leg-by-leg prices, top spreads, compatibility fields, temporal alignment) and edge cases.

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 each parameter is documented. The description adds significant value by explaining how topic vs explicit parameters work, the override behavior, and what the parameter values mean (e.g., macro shortcuts list). Examples are provided in the schema.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket. It distinguishes itself from sibling tools like polymarket_arbitrage by specifying its unique multi-venue purpose. The two modes (topic and explicit) are clearly defined.

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

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

The description explicitly explains when to use each mode (pre-mapped topics vs explicit pairs) and when not to rely on the results (e.g., when compatibility_warning fires). It warns that real spreads are rarer than the shortcut list suggests and provides guidance on interpreting safety fields.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it uses ODSQL and lists operations, which provides useful behavioral context beyond the annotations.

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

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

The description is a single sentence that front-loads the core purpose and lists operations in a clear, efficient manner. Every word adds value, with no wasted text.

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

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

With 8 parameters and high schema coverage, the description covers the main functionality and parameter interactions. It does not describe return format, but since there is no output schema and annotations cover safety, this is acceptable. Overall fairly complete.

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

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

Schema coverage is 100%, and the description adds extra meaning by explaining relationships (e.g., 'where overrides query') and providing examples (e.g., 'year >= 2020', 'count(*)' for select). This improves usability beyond the schema alone.

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

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

The description clearly states the tool queries Toulouse Métropole Open Data records using ODSQL, specifying operations like filter, aggregate, sort, paginate. This distinguishes it from sibling tools like search_datasets (which finds datasets) and search_within (likely different scope).

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

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

The description implies use for structured ODSQL queries but does not explicitly state when to use this tool versus alternatives like search_datasets or search_within. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds beyond annotations: listing all keys when key is omitted, scoping to identifier, and pairing with other tools. 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?

Three sentences, front-loaded, no wasted words. Every sentence adds value.

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

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

For a single optional parameter tool with good annotations, the description is complete: explains behavior, use cases, scoping, and relationship to 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 covers 100% of parameters, but the description adds meaning by explaining the omission behavior (lists all keys) and scoping context, exceeding the baseline of 3.

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

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

The description clearly states the verb-resource pair: retrieve/list saved values/keys. It distinguishes from siblings (remember, forget) by explicitly mentioning them.

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 ('look up context stored earlier') and provides examples. It mentions pairing with remember/forget but does not explicitly list when not to use or alternatives.

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

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

The description claims that setting mark_read:true flags events read, implying a state change. However, the annotations include readOnlyHint=true, which indicates no state modification. This creates a contradiction, undermining transparency. The description does not clarify the side effect or reconcile with the annotation.

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, with four sentences that front-load the purpose. Each sentence adds value: purpose, return fields, filtering/behavior, and alternative access. No wasted words.

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

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

Given no output schema, the description explains return fields (source, citation_uri, raw payload). It covers most usage contexts, including polling and alternative endpoints. The 'unread_only' parameter is not explicitly described, but the schema covers it. Overall, nearly complete for a read tool with good 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%, so the description should add meaning beyond the schema. It provides examples for 'type' (e.g., 'sec_8k') and explains that 'since' is an ISO timestamp and 'mark_read' flags events read. However, it does not mention 'limit' or 'unread_only', which are described in the schema. The added value is moderate, earning the baseline score of 3.

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

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

The description clearly states the verb ('Pull') and the resource ('fired events from your subscription feed'), specifying that it returns the most recent alerts with details like source and citation_uri. It distinguishes itself from siblings by focusing on alerts rather than subscriptions or changes.

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 guidance on when to use the tool ('Polls work fine') and mentions an alternative access method (GET registry.pipeworx.io/alerts.json). It explains filtering options and mark_read behavior, but does not explicitly compare with sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, etc. Description adds significant behavioral context: fans out to multiple sources, explains fallback logic (GDELT→GNews), notes USPTO soft-fail due to API sunset. 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?

Single paragraph, no wasted words. Front-loaded with example queries and clear structure. All sentences earn their 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 no output schema, description explains return shape (changes grouped by source, total_changes, citation URIs). Covers all sources, fallbacks, and limitations. Complete given tool complexity.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining 'since' shorthand (ISO date, relative formats), ticker vs CIK for value, and that type only supports 'company'.

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

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

Description uses specific verbs and resources ('change feed for a company', 'returns structured changes') and explicitly distinguishes from sibling tool 'entity_profile' which provides static profiles. Clearly states 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?

Explicitly says when to use (for recent changes) and when not to (use entity_profile for static profile). Names the alternative tool directly.

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

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

Annotations already provide idempotentHint and destructiveHint. Description adds persistence details and scoping. No contradictions, but omits explicit mention of overwriting behavior, though implied by idempotent hint.

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

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

Two efficient sentences with no fluff. Front-loaded with purpose and examples. Every sentence contributes value.

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

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

For a simple 2-parameter tool with no output schema, the description covers usage, context, persistence, and integration with siblings, making it fully 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% with examples. Description adds minimal additional meaning beyond the schema, only repeating 'save data'. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, provides concrete examples (resolved ticker, target address, etc.), and distinguishes from siblings recall 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 (discover something worth carrying forward) and pairs with recall/forget. Also covers scoping by identifier and persistence differences (authenticated vs anonymous).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: it internally cascades through multiple endpoints, replaces 2-3 manual lookups, and details what each type returns including citation URIs. No contradictions.

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

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

The description is well-structured: it starts with example queries, states the purpose, then lists supported types with details. Every sentence is informative, though it could be slightly more concise without losing clarity.

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

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

Given the tool has no output schema, the description thoroughly covers return values for both types, input formats, internal cascading behavior, and even citation URIs. For a 2-parameter tool, this is highly complete and leaves no obvious gaps.

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

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

Schema description coverage is 100% with both parameters documented. The description adds value by explaining input formats per type (e.g., 'ticker (AAPL), CIK, or name' for company) and mentioning auto-disambiguation, which goes beyond the schema's enum and 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 resolves user-spoken names to canonical/official identifiers, with examples for 'ticker', 'CIK', 'RxCUI'. It distinguishes from siblings by specifying 'use FIRST whenever you have a name but need an ID', making its purpose and primary use case 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 explicitly tells when to use the tool ('use FIRST whenever you have a name but need an ID') and gives supported types. While it doesn't explicitly state when not to use it or point to alternatives, the context is clear enough for an AI agent to infer appropriate 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds process details (probes each entity with ai_visibility_check, ranks results) and output shape (score, confidence, signal density). No contradictions; adds useful context beyond annotations.

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

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

Four sentences deliver all essential information without redundancy. Front-loaded with verb+resource, then process, then use case, then output. 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 no output schema and moderate complexity (4 params), the description fully explains the tool's purpose, input semantics, internal process, and output format (ranked list with score, confidence, signal density per entity). 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%, so baseline is 3. Description adds extra semantics: clarifies that the first entity in the array is treated as the narrative 'subject', and explains the role of context in disambiguating names. This provides meaningful guidance beyond schema descriptions.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, using specific verbs like 'Compare', 'Probes', and 'Ranks'. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on competitive AI-marketing audits.

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

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

Description provides clear context for use, exemplified by a concrete question about competitive AI visibility. However, it does not explicitly state when not to use or mention alternatives like ai_visibility_check for single-entity checks.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: it fans out to external services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list if it times out. No contradictions.

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

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

The description is well-structured and concise, starting with the main composite check, then detailing return fields, use cases, limitations, and fallback behavior. Every sentence adds necessary information without fluff.

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

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

Given the tool's complexity (multiple sources, partial failures, no output schema), the description is remarkably complete. It explains the return structure (summary block, per-advisory, links, recent alternatives), caveats (NPM only, bundlephobia delay), and graceful degradation. This fully compensates for the lack of an output schema.

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

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

The input schema already describes both parameters well (package name, version with default). The description adds extra value by mentioning that scoped packages (e.g., '@types/node') are accepted, which is not in the schema. Since schema coverage is 100%, baseline is 3; the addition justifies a 4.

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

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

The description clearly states the tool performs a composite check for adding an npm package, fanning out to deps.dev and bundlephobia. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on npm package safety, popularity, and size 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?

The description explicitly spells out use cases: answering questions like 'is X safe / popular / small' or 'what does adding lodash cost me'. It also notes that only the NPM ecosystem is supported in v1 and suggests using deps.dev:version directly for other ecosystems, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying the return fields (dataset_ids, titles, themes, record counts) and downstream usage. 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?

Two sentences, front-loaded with purpose and example categories. Every sentence is meaningful with no waste. Efficient and clear structure.

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

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

Given the simplicity of the tool (3 params, no output schema) and thorough annotations, the description adequately covers purpose, input, and output. It could mention pagination behavior but limit and offset are in schema. Good completeness for a search 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 description coverage is 100%, with each parameter (limit, query, offset) already well-documented in the schema. The description does not add additional semantic meaning beyond the schema, so 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's purpose: searching Toulouse Métropole Open Data datasets by keyword, with examples of categories (mobility, urban services, culture & environment). It distinguishes itself from sibling tools like dataset_info by explaining that it returns dataset_ids that can be passed to query/dataset_info for further details.

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

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

The description provides clear context on using the tool: search by keyword, then use returned dataset_ids with query or dataset_info. It implies a workflow but does not explicitly state when not to use it or mention alternatives beyond the sibling list.

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

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

The description reveals the embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and the 200K char cap with truncation flag. All annotations (readOnly, idempotent, etc.) are consistent. No contradiction. This goes well beyond the annotation hints.

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 about 150 words, front-loaded with the core action, and every sentence adds unique value (use case, technical details, pairing). No redundancy or filler.

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 there is no output schema, the description explains the return format (passages with offsets and scores). The tool is moderately complex, and all key behavioral details (truncation, embedding method) are included. The description is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the parameters are already documented. The description adds example queries and clarifies the 'text' parameter, but does not add substantial new meaning beyond the schema's descriptions. 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 performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes from siblings by referencing ask_pipeworx_grounded and emphasizing the use case of reducing context size.

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 when the record is too big to cram into the prompt — search_within saves context.' It also mentions pairing with ask_pipeworx_grounded. While it doesn't cover when not to use, the guidance is clear and actionable.

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

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

The description adds extensive behavioral details beyond annotations: OAuth requirement, delivery channel options, rate limits (10/day), verification steps, and auto-disabling of webhooks. Annotations already indicate non-readOnly and idempotent, and the description aligns with these.

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 efficient with front-loaded core action, but moderately long. Every sentence adds value, though some details could be condensed. Still well-structured.

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

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

Given the complexity (3 parameters, 5 types, nested objects), the description is highly complete: it covers auth, supported types, param formats, delivery options, limits, and return value ('Returns the new subscription id'). No output schema, but the return is explained.

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

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

Schema coverage is 100%, but the description adds significant value by explaining type-specific parameters with concrete examples (e.g., 'items:["5.02"]' for sec_8k). Delivery channels are also detailed 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 verb ('Create') and resource ('proactive monitoring subscription'), with specific examples of supported types. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description explicitly requires a Pipeworx OAuth account and notes constraints like SMS cap and phone verification. It does not explicitly mention when not to use, but provides sufficient context for correct 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?

Annotations already declare readOnly and idempotent. The description adds rich behavioral context: returns structured examples with exact tool calls, can be focused by topic, and acts as a learning tool for meta-tools.

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

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

The description is relatively long but well-structured with a clear purpose at the start and a list of categories. It earns its length by providing essential context 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 onboarding tool, the description fully explains what it returns, when to use it, how to vary the output, and how it relates to other tools. No gaps given the lack of output schema.

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

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

Schema coverage is 100% and the description adds examples of valid topic values ('finance', 'pharma') and clarifies behavior with and without the argument, going beyond the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions and distinguishes it from siblings like ask_pipeworx and discover_tools by positioning it as the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides guidance on when to pass the topic argument vs omitting it for a full spread.

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

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

Discloses soft-delete behavior (deactivates, not deletes) and links to 'recent_alerts' for historical events. 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?

Two concise sentences with immediate action statement. 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?

Adequate for a single-parameter idempotent tool. Could optionally mention return value or side effects, but not needed given simplicity.

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

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

Only parameter 'id' is described both in schema and description, with additional context that it's returned by 'subscribe'. Schema coverage is 100%, so baseline 3, but extra link adds value.

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

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

Clear action (cancel) and resource (subscription by id). Distinguishes from sibling 'subscribe' by being its inverse. Ownership enforcement is stated.

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

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

Explicitly states ownership enforcement implying only for own subscriptions. Could benefit from mentioning 'list_subscriptions' as a prerequisite, but implied.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds context about using SEC EDGAR + XBRL and the specific verdict types, which is helpful 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 well-organized, starting with trigger phrases, then purpose, usage, technical details, and efficiency gains. Every sentence adds value without redundancy.

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

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

Given the simple input schema (one parameter) and no output schema, the description fully explains the tool's functionality, return values (verdict types, citation, delta), and domain scope. It is sufficient for an agent to use correctly.

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

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

Schema description coverage is 100% with a clear description of the 'claim' parameter. The description adds examples and specifies the supported claim domain (company-financial), providing additional context beyond the schema.

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

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

The description clearly states the tool validates natural-language claims against authoritative sources, with specific examples like 'Is it true that…' and 'fact check'. It distinguishes from siblings by focusing on company-financial claims via SEC EDGAR + XBRL.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' While it doesn't mention when not to use it, the domain specificity (company-financial) implicitly guides appropriate use.

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