Eu Parliament

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

Annotations indicate safe read-only, open-world, idempotent operation. Description adds beyond: explains probing mechanism, default free model, optional Anthropic with BYO key, and return format (per-model score/confidence/signals/raw_response + combined). 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?

Description is compact (3 sentences) with front-loaded action, then default behavior, optional key, return summary, and usage examples. Every sentence adds necessary information without repetition.

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

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

No output schema, so description must cover return values. It does: per-model {score, confidence, signals, raw_response} + combined view. It covers all 4 parameters. Slightly lacking details on 'signals' structure, but sufficient given complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by specifying default model, clarifying _apiKey usage ('you pay Anthropic directly'), and explaining context disambiguation. This extra context justifies a 4.

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

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

Description uses specific verb 'probe' and resource 'LLMs' with clear outcome 'score visibility (0-100) per model'. It distinguishes from siblings like 'compare_entities' and 'scan_competitor_ai_presence' by focusing on AI awareness rather than comparison or scanning.

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

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

Description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model and when to provide _apiKey. However, it does not explicitly contrast with sibling tools or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond annotations: it explains the routing mechanism to 3,436 tools, the return of structured answers with pipeworx:// citation URIs, and the preference over web search. No contradiction with annotations.

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

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

The description is relatively long but densely informative. It front-loads the key point ('PREFER OVER WEB SEARCH') and organizes use cases in a readable list. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Given the tool's complexity and absence of an output schema, the description is quite complete. It covers the tool's role as a question router, the type of data sources, the answer format, and provides numerous examples. It adequately compensates for 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% with all parameters described, including multiple aliases. The description provides examples of valid questions, which adds context, but does not significantly enhance the semantic understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: routing questions to 3,436 tools across 780 verified sources to return structured answers with citations. It distinguishes itself from web search by listing specific domains (SEC filings, FDA data, etc.) and provides concrete examples.

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

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

The description clearly indicates when to use the tool: for factual questions about real-world entities, events, or numbers. It contrasts with web search and provides many query types. However, it does not explicitly state when not to use it (e.g., for conversational or subjective queries).

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

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

Annotations declare readOnly, openWorld, idempotent. Description adds return structure, explicit refusal reasons, and extra LLM call cost.

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

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

Description is dense and front-loaded with purpose; each sentence adds value. Could be slightly more concise but efficient overall.

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

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

Given no output schema, description fully specifies return format and failure modes. Annotations cover safety. Complete for a parameter-light tool.

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

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

Schema coverage is 100% and description does not add meaning beyond 'Your question in natural language'. Aliases are already documented in schema.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and differentiates from sibling ask_pipeworx by explaining the extraction and structured return format.

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

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

Explicitly states when to use (quoted/cited/acted on answers, must not invent facts) and when to prefer ask_pipeworx (casual lookups), including a cost trade-off.

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

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

The description goes far beyond annotations, detailing fan-out behavior, response shapes, resolver contract (confidence levels, alternatives), parent event extractor, news fallback handling, low-confidence short-circuit, closed market handling, and wide spread tradeability. 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 lengthy but well-structured with sections for classifiers, fan-out examples, response shapes, etc. It is front-loaded with main purpose. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description fully describes return fields: result.market (best_bid, best_ask, etc.), result.analysis (model_probability, edge_pp, 24h-move warning), result.evidence keyed by source, resolver contract, parent_event, news fields with fallback, and status codes for edge cases like low confidence or closed markets.

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

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

Schema description coverage is 100%. The description adds value by explaining market parameter can be slug, URL, or question text; depth enum values with behavior difference; include_raw parameter explains response size impact. This aids correct parameter usage beyond schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from siblings like polymarket_edges which focus on edge detection.

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

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

The description explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It provides clear use cases but does not explicitly mention when not to use it. However, the examples and context imply the appropriate scenarios.

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

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

The description adds significant context beyond the annotations: it explains the data returned (financial metrics for companies, adverse-event counts for drugs), sorting by primary metric, handling of off-calendar fiscal years, and efficiency gains. This complements the readOnly/openWorld/idempotent annotations without contradiction.

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

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

The description is well-structured, front-loading key natural language triggers and use cases. While slightly verbose, each sentence adds value—specifying data sources, sorting behavior, and alternatives. It is efficient for the complexity it covers.

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 informs the agent of what to expect: paired data with citation URIs, sorted results. It covers the two entity types, constraints (2-5 items), and data sources. Some details on output format are missing but acceptable for a comparison tool.

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

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

Schema coverage is 100% but the description enriches the parameters: it clarifies that 'values' should be tickers/CIKs for companies and drug names for drugs, and details the specific data fields retrieved for each type. This goes beyond the schema's basic 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 performs side-by-side comparisons of 2-5 companies or drugs in a single call. It specifies the data sources for each type (SEC EDGAR for companies, FAERS/drug data for drugs) and distinguishes from sequential lookups, which differentiates it from sibling tools like entity_profile.

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

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

It explicitly advises preferring this tool over sequential single-entity lookups when comparing entities, and provides natural language triggers (e.g., 'compare X and Y', 'which is bigger'). It also explains the different behaviors for company vs drug types, giving clear when-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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds behavioral detail: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradictions.

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

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

The description is three sentences, all substantive. It is front-loaded with the core purpose. Could be slightly more concise but no waste.

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 discovery tool with 6 parameters and no output schema, the description fully explains what the tool returns (tools with names, descriptions, schemas) and when to use it, making it complete for the intended use.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds aliases ('Accepts task, q, description, search as aliases') and specifics about limit (default 20, max 50), providing value beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists many domains (SEC filings, financials, etc.), distinguishing it from sibling tools which are specific data tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)' and mentions the tool returns tools ready to call. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds important behavioral details: it fans out across multiple external APIs (SEC, XBRL, USPTO, news, GLEIF), discloses the USPTO PatentsView API sunset and soft-fail behavior, and lists all returned fields. 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 front-loaded with examples and key guidance, which is good. However, it is slightly verbose—some details about the exact return fields could be inferred or condensed. Still, it earns its place with minimal 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 (multi-source aggregation) and the absence of an output schema, the description is remarkably complete. It lists every major data component returned (CIK, filings, fundamentals, patents, news, LEI) and even describes failure modes (USPTO soft-fail). The agent has enough context to use it correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond the schema by specifying that the 'value' can be a ticker like 'AAPL' or a zero-padded CIK, and notes that names are not supported. This helps the agent format the input correctly.

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

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

The description clearly states it provides a full cross-source profile of a US public company, with multiple example queries. It explicitly distinguishes itself from chaining single-pack lookups, making it easy for the agent to know what this tool does and when to prefer it.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies that names are not supported and advises using resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's statement 'Delete' is consistent but does not add new behavioral details beyond what annotations provide. The mention of clearing 'sensitive data' adds some context, but no explanation of side effects, error handling, or permanence of deletion.

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, consisting of two sentences. The first sentence immediately states the purpose, and the second provides usage guidelines. No unnecessary words or redundancy.

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

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

Given the simplicity of the tool (single parameter, no output schema, clear annotations), the description covers everything needed: what it does, when to use it, and how it relates to sibling tools. It is complete for this low-complexity tool.

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

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

The input schema covers 100% of parameters with a clear description for 'key: Memory key to delete'. The tool description does not add further parameter details, so it reaches 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 explicitly states 'Delete a previously stored memory by key', which clearly identifies the action (delete), the resource (memory), and the mechanism (by key). It also distinguishes from sibling tools by mentioning 'Pair with remember and recall.'

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

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

The description directly provides when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also gives guidance on alternatives by pairing with 'remember and recall', making it clear when not to use another tool.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) indicate safe, idempotent operation. Description adds context about fetching, extracting title/description/links, and emitting a standard format. No contradiction; behavior is well-disclosed.

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

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

Two sentences: first describes functionality and output, second lists use cases. Front-loaded, no superfluous words. Every sentence provides value.

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

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

Given no output schema, the description explains the output is a text blob ready for site-root. Parameters are fully covered. Complexity is low; the description provides all necessary context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. Description rephrases the url and max_links descriptions but adds no new constraints or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, naming specific AI crawlers (ChatGPT, Claude, Perplexity) and the output format. It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation.

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

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

Explicit use cases are listed: getting client sites indexed, drafting for own projects, auditing competitor AI visibility. No direct exclusion or alternative tools mentioned, but 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?

Annotations declare readOnlyHint and destructiveHint false; description adds behavioral context by listing returned fields. No contradictions. Adequate for safety profile.

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

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

Two sentences, no superfluous words, front-loaded with main action and returned fields. 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?

Sufficient for a simple list tool with one optional parameter. Mentions usage context and fields. Lacks discussion of edge cases like empty results but not critical.

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. Description does not add extra meaning for the include_inactive parameter beyond implying default behavior. 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 lists the caller's active subscriptions, specifies returned fields, and provides usage context. Distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly recommends using it to review monitoring before adding more or to find an id to cancel. Does not mention alternatives but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds minimal behavioral context (ID lookup) beyond what is provided by 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, front-loaded sentence with no extraneous words, efficiently conveying the tool's 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?

For a simple lookup tool with a single parameter and an output schema, the description, combined with annotations, provides sufficient context for an AI agent to use it correctly.

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

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

Although schema coverage is 0%, the description explicitly ties the tool to retrieving by ID, clarifying the parameter's purpose. This compensates for the lack of 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 'Single MEP by id.' uses a specific verb-resource combination and directly distinguishes from sibling tool 'meps', which is implied to list multiple MEPs.

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

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

The description implies usage when you have a specific ID, contrasting with the sibling 'meps' for listing. However, it lacks explicit when-not-to-use or alternative conditions.

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, so safety is clear. The description adds the default term behavior, which is useful 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 a single, clear sentence with no unnecessary words. It is appropriately front-loaded.

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

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

Given the presence of an output schema and simple list functionality, the description is minimally adequate. It lacks details on ordering, pagination, or result format.

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

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

Schema description coverage is 60%; parameters 'limit' and 'offset' lack descriptions both in schema and tool description. The description adds no additional parameter meaning.

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

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

The description clearly states the action ('List') and the resource ('MEPs'), and adds the default scope ('current term'). It distinguishes from the sibling 'mep' (singular) 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 implies use for listing multiple MEPs vs. singular 'mep' tool, but does not explicitly state when to choose this tool or provide exclusion criteria.

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 set readOnlyHint=false, destructiveHint=false, etc., but the description adds key behavioral details: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' It also mentions the team reads digests daily and signal affects roadmap, providing transparency beyond annotations.

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

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

The description is well-structured and every sentence earns its place. It starts with the main purpose, then specifies when to use, how to format feedback, rate limits, and impact. It is concise yet comprehensive, with no wasted words.

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

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

Given no output schema, the description covers all necessary aspects: purpose, usage criteria, parameter guidance, rate limits, and impact. It is complete for a feedback tool, providing sufficient context for an AI agent to use it correctly.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by elaborating on the enum values for 'type' with concrete examples (e.g., 'bug = something broke or returned wrong data'), and provides context for the 'context' field. It also includes the note about being specific and not pasting user prompts, which enhances parameter understanding.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback types (bug, feature/data_gap, praise) and distinguishes itself from sibling tools, which handle other tasks like AI visibility, research, or entity profiles.

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

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

The description provides explicit guidance on when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also instructs to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts, plus notes rate limits and that it's free.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive hints. The description adds valuable beyond-annotation context: data source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating 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?

Three sentences, each adding unique value. Front-loaded with the main result, followed by use cases and technical details. No fluff or repetition.

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

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

For a read-only tool with one parameter and no output schema, the description is fully adequate. It covers return structure, use cases, caching, and data derivation, leaving no questions about what the tool does or how to use it.

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

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

Schema coverage is 100% with a well-described enum parameter. The description adds practical guidance on window choice (shorter for hot trends, longer for steady-state) and notes the default value, complementing the schema without redundancy.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a recent window, with specific verbs and resource identification. It distinguishes from siblings like discover_tools by focusing on trending usage rather than static discovery.

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 (discovering hot data sources, confirming canonical tools, seeing alignment) and provides context for window selection. It lacks explicit when-not-to-use alternatives, but 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 annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint) already convey safety and idempotency. The description adds no additional behavioral context, which is acceptable but does not improve transparency.

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

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

The description is extremely short (two words) but constitutes under-specification rather than conciseness. It could be expanded to provide essential context without being verbose.

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 four parameters, no required fields, and no output schema explanation, the description is completely inadequate. It does not explain what the tool does, what documents are returned, or how to use it effectively.

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

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

Schema description coverage is only 25% (only 'type' has a description). The description 'Plenary documents' adds no meaning to parameters like 'term', 'limit', or 'offset', leaving them poorly documented.

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 'Plenary documents' is vague and does not clearly state a verb or specific resource. It fails to distinguish this tool from siblings like 'entity_profile' or 'validate_claim'.

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

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

No guidance is provided on when to use this tool or what context is appropriate. No alternatives or exclusions are mentioned, leaving the agent without direction.

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

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

Annotations indicate readOnly, openWorld, and idempotent hints. The description adds detailed behavioral context: how it walks child markets, partition checks, similarity thresholds, placeholder filtering, and response structure. 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 lengthy but well-structured: requirement first, then purpose, mode explanations with examples, and additional filters. Every sentence adds value, though some redundancy exists (e.g., partition check details repeated). Could be slightly more concise.

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

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

No output schema, but the description fully explains the response format (opportunities[] with fields, partition_check in event mode). It covers all constraints, failure conditions, and edge cases, making it complete 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 covers 100% of parameters with descriptions. The description adds extra context beyond schema (e.g., 'Full Polymarket URLs also accepted' for event, and usage elaboration for topic), but the schema already provides clear meaning.

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

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

The description explicitly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' with distinct modes (event vs topic), clearly differentiating from sibling tools like polymarket_edges or polymarket_kalshi_spread.

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

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

The description starts with 'REQUIRES one of event OR topic — call with no args fails', provides examples for both modes, and explains when each should be used. However, it does not explicitly state when not to use 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 already declare readOnlyHint=true, destructiveHint=false. The description adds extensive behavioral context: model families, edge calculation, slippage, Kelly sizing, 24h-move warnings, caching, and diagnostics. No contradictions with annotations.

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

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

The description is verbose and includes technical details that could be streamlined. However, it front-loads the core purpose and uses structured segments (by_segment, knobs, diagnostics), making it navigable despite length.

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

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

Given the complexity (9 parameters, no output schema), the description covers output structure, diagnostics, caching, and tradeable-edge knobs. It explains return segments and caveats (e.g., Fed bets), but could be more concise in some areas.

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. The description adds meaningful context beyond the schema, such as tradeable-edge filters, Kelly usage, and practical considerations like Polymarket's zero fees, enhancing parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the action (scan and return) and resource (top Polymarket markets), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_kalshi_spread by focusing on Pipeworx disagreement.

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 positions the tool for 'what should I bet on today' and details three model families and tradeable-edge knobs, providing clear context. It does not explicitly list alternatives or when not to use, but the context sufficiently guides appropriate usage relative to siblings.

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

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

Goes well beyond annotations by detailing response fields (leg prices, spreads), safety fields (compatibility_warning, temporal_alignment), and edge cases (skipped_cross_type). 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 information-dense but lengthy; it could be more concise while retaining key points. Structured with clear sections, but some sentences are verbose.

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

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

Given the complexity of cross-venue spread computation and no output schema, the description thoroughly covers all essential aspects: modes, response structure, compatibility warnings, temporal alignment, and skipped comparison types.

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 all parameters with descriptions. The description enriches by listing the 10 topic shortcuts and explaining override behavior, adding value beyond the schema.

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

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

The description clearly defines the tool as computing cross-venue spreads between Kalshi and Polymarket. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison for the same resolving question.

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?

Describes two modes (topic shortcuts and explicit tickers) and warns that most shortcuts return compatibility warnings, implying cautious use. However, it does not explicitly compare to alternative tools for arbitrage or entity comparison.

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 scope details (anonymous IP, BYO key hash) and behavior for key omission, beyond annotations (readOnlyHint, idempotentHint, destructiveHint). No contradictions.

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

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

Two sentences with no fluff. Front-loaded with main action. Each sentence adds value.

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

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

Covers return behavior (value or list of keys), scoping, and relation to siblings. No output schema needed; description suffices.

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 parameter 'key'. Description explains it briefly but adds little beyond schema definition. 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 retrieves a saved value or lists keys, distinguishing it from siblings (remember, forget). Verb 'retrieve' and resource 'saved values/keys' are explicit.

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

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

Provides concrete examples (ticker, address, notes) and mentions scoping by identifier. Lacks explicit when-not-to-use, but pairing with remember and forget implies context.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds value by explaining that mark_read flags events as read affecting subsequent calls, and mentions the alternative REST endpoint. No contradictions.

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

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

Information-dense with multiple details in a few sentences. Each sentence adds value (purpose, returned fields, filtering, mark_read, polling alternative). Could be more front-loaded but not verbose.

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

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

No output schema, so description must explain returns—it lists source, citation_uri, payload. With 5 optional params and thoughtful coverage of usage scenarios, it's fairly complete. Could detail pagination/limit behavior more, but 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 descriptions for all 5 params. Description adds concrete examples (e.g., 'sec_8k' for type, ISO timestamp for since) and clarifies mark_read behavior beyond schema. Baseline 3 elevated to 4 for added nuance.

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 'Pull fired events from your subscription feed' with specific verb and resource. It details the returned data (source, citation_uri, raw payload) and distinguishes from siblings like list_subscriptions which manages subscriptions rather than alerts.

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

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

Provides good context: explains filtering by type/since, mark_read behavior, and notes that polling works and same feed is available via a GET endpoint for scripts. Lacks explicit contrast with sibling tools but gives enough guidance for typical 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 mark the tool as readOnly, idempotent, and non-destructive. The description adds behavioral details: parallel fan-out to multiple sources, fallback behavior, soft-fail for USPTO, and return structure (changes grouped by source, total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single paragraph that is dense but well-structured, front-loading common query patterns. While every sentence adds value, it could be slightly more concise or broken into bullet points. Still above average in 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's complexity (multiple sources, parameter formats, no output schema), the description covers return structure, parameter behavior, fallback logic, and source details. It is fully sufficient for an agent to understand usage and expectations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond schema: explains `since` formats (ISO date or relative shorthand like '7d', '30d', '1y'), gives default usage suggestion, and clarifies `value` accepts ticker or CIK. This additional guidance justifies a score above baseline.

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

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

The description clearly states the tool's purpose: a change feed for a company over a time window, fanning out to SEC, GDELT/GNews, and USPTO. It uses specific verbs like 'fans out' and 'returns', and distinguishes from the sibling tool 'entity_profile' by specifying when to use each.

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

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

Explicitly states when to use (for 'what's new' queries) and when not to (use 'entity_profile' for static profiles). Provides context on source fallback logic (GDELT preferred, GNews on fallback) and parameter guidance (e.g., '30d' for typical monitoring).

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 storage details (key-value scoped by identifier, persistence for authenticated vs. anonymous) beyond annotations. No contradictions with idempotentHint or destructiveHint.

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

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

Four sentences, each adding distinct value: purpose, usage scenario, storage behavior, and pairing instructions. 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?

Covers storage duration, scoping, and usage. Missing return value info (e.g., success indication) but overall adequate for a simple store operation.

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

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

Schema coverage is 100% with good descriptions. Description mentions key-value pair but adds little semantic value beyond the schema's existing parameter 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 saves data for reuse and gives specific examples (ticker, address, preference). It explicitly differentiates 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?

Clearly states when to use: upon discovering something worth carrying forward. Instructs pairing with recall and forget, providing complete usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that each call cascades through several endpoints, replacing 2-3 manual lookups, which provides useful behavioral context without contradiction.

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

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

The description is concise (about 150 words) and front-loaded with the most critical information. It uses bullet points effectively to separate supported types without wasted words.

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

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

Despite lacking an output schema, the description comprehensively covers return values for each type, specifies exact fields, and explains internal cascading. It provides complete context for effective tool 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 coverage is 100%. The description enriches parameters with concrete examples (AAPL, 0000320193, ozempic) and explains auto-disambiguation for company, adding meaning beyond the schema's enum and string 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 starts with natural language queries and clearly states it resolves user-spoken names to canonical identifiers. It specifies supported types (company, drug) and what each returns, distinguishing it from siblings like entity_profile or compare_entities.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and describes when to use it. While it doesn't explicitly state when not to use it or mention specific alternatives, it implies it replaces multiple lookups, providing clear context.

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

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

Describes the probing process, ranking, and output fields (score, confidence, signal density). Annotations already indicate read-only, idempotent, and non-destructive behavior; the description adds value by explaining the aggregation logic.

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 well-structured sentences: purpose, mechanism, use case. No redundant information, front-loaded with key action.

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, output format despite no output schema. Mentions reliance on ai_visibility_check. Lacks discussion of limitations like rate limits or error handling, but annotations cover idempotency.

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

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

Schema coverage is 100% with good descriptions. The description adds that the first entity is treated as the 'subject' and the default model is 'workers-ai', which goes beyond the schema. Baseline 3 plus incremental 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?

Clearly states the tool compares AI visibility across multiple entities, ranks them, and identifies the most/least recognized. Distinguishes from sibling ai_visibility_check which likely probes a single 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?

Provides a concrete use case (competitive AI-marketing audits) and implies when to use it. References sibling tool ai_visibility_check as the underlying mechanism, but does not explicitly state when not to use 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: fans out across external services, handles partial failures, timing (first bundlephobia measurement 5-30s), and return field details. No contradiction.

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

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

The description is a single paragraph that is densely informative and front-loaded. Minor improvement could be achieved by structuring into bullet points, but it is concise and each sentence adds value.

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

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

With only 2 parameters and no output schema, the description fully explains the return fields, error behavior (partial failures), and limitations (NPM only in v1). It is complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minimal value beyond that (version defaults to latest, scoped packages accepted). Baseline is 3 given high schema coverage.

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

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

The description clearly states it's a composite check for an npm package consolidating multiple data sources. It uses specific verbs and resources, and distinguishes itself from siblings by specifying its unique combination of features.

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

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

The description explicitly states when to use (agent asks about safety, popularity, size, or cost of adding a package), specifies NPM ecosystem only in v1, and mentions fallback guidance for other ecosystems. It lacks explicit when-not to use, but context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-destructive operation. The description adds significant detail beyond annotations: it explains the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging, and that results include character offsets for verification.

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

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

The description is concise at five sentences, front-loaded with the main purpose. Every sentence adds unique information (use case, pairing, technical details, limits) with no redundancy.

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

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

Given three parameters, no output schema, and an embedding-based search implementation, the description fully covers what the tool does, how it works, when to use it, its limits, and its pairing with a sibling. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the text cap, giving example queries, and clarifying that limit controls top passages. It also explains the output format (offsets and scores) which is not in the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with a specific verb and resource. It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining the pairing and the use case when the record is too large for the prompt.

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

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

The description explicitly tells when to use this tool—when the record is too big to fit in the prompt—and how it pairs with ask_pipeworx_grounded, providing a clear alternative and workflow 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds no behavioral context beyond these annotations. It does not contradict annotations, but also does not elaborate on what the tool does or its effects.

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

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

The description is extremely short but qualifies as under-specification, not conciseness. It fails to provide essential information needed for tool selection.

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

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

Despite having an output schema and annotations, the description lacks any explanation of what the tool returns or its purpose. It is completely inadequate for understanding the tool's functionality.

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 0%. The description 'Session calendar' provides no meaning or context for the two parameters (term, year). The parameters remain completely undocumented in meaning.

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

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

The description 'Session calendar' is a tautology of the tool name. It does not specify what action the tool performs (e.g., list, retrieve, manage) or what kind of data it provides. No differentiation from sibling tools.

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

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

No guidance on when to use this tool versus alternatives. The description lacks any context for appropriate usage scenarios.

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

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

Annotations include readOnlyHint=true, but the description explicitly says 'Create', a write operation. This is a direct contradiction. No mention of idempotency or other behaviors. Poor transparency.

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

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

The description is concise and front-loaded with the main action, but mixes examples, constraints, and delivery details in a slightly unstructured way. Still efficient overall.

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

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

Covers authentication, delivery channels with limits, and return type. Missing output schema is fine. However, does not address idempotency or error cases. Fairly complete for a creation tool.

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

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

Schema coverage is 100%, and the description adds examples (e.g., items defaults to all if omitted), clarifies the delivery subfields, and explains type-specific filters, significantly adding value beyond schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific example (sec_8k) and differentiates it from sibling tools like list_subscriptions and unsubscribe.

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

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

Description says 'Requires a Pipeworx OAuth account' and notes that anonymous and BYO users cannot persist, providing clear usage context. However, it does not explicitly state when not to use the tool or compare to alternatives like search.

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

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

The description contradicts the annotation 'readOnlyHint: true' by stating 'Cancel a subscription,' which is a mutation. This is a serious inconsistency. While the description adds useful details about deactivation and historical events, the contradiction undermines trust and confuses the agent.

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

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

The description is two sentences, front-loading the core action and then providing critical behavioral context. No wasted words; every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership and side-effect details. However, the contradiction with annotations and lack of output info slightly reduce completeness for an agent expecting consistent metadata.

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 only parameter 'id' is fully described in the schema as 'Subscription id (uuid) returned by subscribe.' The description merely mentions 'by id,' adding no extra semantic value. With 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and that the subscription is deactivated rather than deleted, making its purpose unambiguous.

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

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

The description explains when to use the tool (to cancel a subscription) and sets expectations about ownership enforcement. However, it does not explicitly state when not to use it or mention alternative tools for different scenarios, though sibling context partly compensates.

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

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

Annotations already cover safety and idempotency. The description adds useful behavioral context: the verdict types, structured output, citation format, and percent delta. It also reveals the underlying data source (SEC EDGAR+XBRL). This goes beyond annotations to explain what the tool actually does and returns.

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

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

The description is front-loaded with key trigger phrases and a concise summary. While informative, it includes extraneous details like 'Replaces 4–6 sequential calls' which, though valuable, could be considered verbose. Overall, it is well-structured but not maximally concise.

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

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

For a tool with a single parameter and strong annotations, the description covers the core functionality, return values, scope, and data source. It does not mention error conditions or limitations beyond scope, but given the tool's simplicity, it is largely complete.

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

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

The schema already provides a clear description of the 'claim' parameter with examples, achieving 100% coverage. The description repeats similar examples in a different format but does not add new semantic information about the parameter itself, so a baseline score of 3 is appropriate.

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

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

The description explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It provides trigger phrases ('Is it true that...', 'fact check') and clearly indicates this tool is for verifying factual claims. It also distinguishes itself from siblings by noting it replaces 4-6 sequential calls, making its unique value clear.

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 guides when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the supported scope (company-financial claims via SEC EDGAR+XBRL) which implies when not to use (e.g., non-financial claims). However, it does not explicitly list alternative tools or provide exclusions.

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