Idf Events

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

Adds context beyond annotations: details on API key cost (BYO key, pay Anthropic), return structure (per-model {score, confidence, signals, raw_response}), and default model selection. 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?

Three dense sentences with no wasted words. Action verb first, followed by key details and use cases. Perfectly sized for quick agent comprehension.

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

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

Covers all necessary aspects: purpose, parameters, return structure, use cases, and cost implications. No output schema, but description adequately explains expected results.

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

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

Schema coverage is 100%, but description enhances semantics: 'Omit for just workers-ai' for models, 'Passed straight through' for _apiKey, example for context. Adds value beyond schema.

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

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

The description uses specific verbs ('Probe', 'score') and identifies the resource (LLMs, visibility). It clearly distinguishes from sibling tools like 'ask_pipeworx' which are for domain-specific queries.

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

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

Explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and default model behavior. Lacks explicit when-not-to-use or direct alternatives, but context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behaviors. The description adds valuable context about routing to 5,529 tools, filling arguments automatically, returning citation URIs, and being a fast default entry point. This goes beyond annotations without contradicting them, though it could mention error cases or limits.

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 every sentence earns its place: priority directive, scope, examples, alternatives, and context. It is front-loaded with the key 'PREFER OVER WEB SEARCH' message, and the structure guides the reader from when to use to when not to use.

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

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

For a complex tool with no output schema, the description fully covers what it does, when to use it, how it behaves, and alternatives. It includes numerous examples, mentions citation URIs, and explains its relationship to sibling tools, making it self-sufficient for an agent to select and 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?

Schema description coverage is 100%: all six parameters are aliases for 'question', each individually documented. The description adds examples of questions but no deeper parameter semantics beyond what the schema already provides. Baseline 3 is appropriate since schema handles the heavy lifting.

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

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

The description clearly identifies the tool as a question-answering agent that routes to curated sources and returns structured answers with citations. It explicitly distinguishes itself from siblings by positioning ask_pipeworx as the default entry point and naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases.

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

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

Provides explicit guidance: prefer over web search, start here for most questions, and step up to ask_pipeworx_grounded or deep_research only when needed. Gives concrete examples of appropriate queries and notes it works on every tier with one fast call, making the usage context 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?

Beyond the read-only and idempotent annotations, the description discloses the experimental beta nature, the current inactive candidate state (matching ask_pipeworx exactly), and that it is a full working router with no fallback. This adds useful contextual behavior not covered 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?

Description is succinct and front-loaded with the tool's identity, followed by current status, usage instructions, and a reassurance that it's a full router. Every sentence serves a purpose with no 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?

With no output schema, the description compensates by referencing the same response shape as ask_pipeworx. Combined with annotations and full schema coverage, it provides sufficient context for an agent to decide when to use this experimental variant.

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 question and its aliases. The description adds minimal parameter meaning, only noting 'same arguments' and referencing ask_pipeworx usage, which is redundant with the schema but reinforces compatibility.

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 it is a beta version of ask_pipeworx, identical in tools, arguments, and response shape, and distinguishes itself by highlighting the experimental routing improvements. It is a specific verb+resource+scope that clearly differentiates from the stable sibling.

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

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

It gives explicit guidance to use it 'exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. It doesn't explicitly state when-not-to-use or name an alternative, but the stable sibling is apparent from 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?

Beyond the readOnly/idempotent annotations, the description reveals detailed behavioral traits: extraction uses 'ONLY what the tool result contains', success returns evidence and refusal reasons are enumerated. It also discloses the extra LLM call cost, which annotations cannot convey.

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-loads purpose, then details behavior and return format, then usage guidance and cost tradeoff. Every sentence provides value and avoids redundancy, making it appropriately detailed for the tool's 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?

No output schema exists, but the description fully explains return values and refusal reasons, including possible refusal_reason enums. It also covers when to use, cost implications, and relationship to the sibling tool, making it a complete standalone reference.

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 all parameters documented as aliases for the question, so the description adds no additional parameter-level meaning. The description mentions 'fills arguments' but that's generic routing context, not specific parameter guidance. Baseline 3 applies given full 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 the tool is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (extract) and resource (tool results). It distinguishes itself from 'ask_pipeworx' by emphasizing grounded extraction and explicit refusals, making its purpose unmistakable.

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

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

It provides explicit use cases: 'whenever an answer will be quoted, cited, or acted on' and lists examples (financial verdicts, legal claims, etc.). It also gives an explicit alternative preference: 'prefer ask_pipeworx for casual lookups', including a cost tradeoff.

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

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

The description extensively discloses behavior: read-only operation, fan-out to multiple data sources, safety mechanisms (low-confidence resolution, closed markets, wide spreads), and response structure. No annotation contradictions.

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

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

The description is very long and contains extensive information. While well-structured with sections, it could be more concise without losing essential details.

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

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

Given the tool's complexity and lack of output schema, the description is extremely complete: covering input, process, output, edge cases, and safety, leaving no 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 coverage is 100%, and the description adds significant meaning: explains market input formats, depth options, and include_raw use cases 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: researching Polymarket bets by pulling Pipeworx data. It specifies the verb 'research' and the resource, and distinguishes from siblings like polymarket_arbitrage.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y') with examples, but does not explicitly state when not to use the tool or list alternatives. Clear context, no exclusions.

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

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

The description adds rich behavioral context beyond annotations: it details data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. This fully discloses what the tool does and how it behaves without contradicting the readOnlyHint or other 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 examples and priorities, but it is slightly lengthy (around 300 characters). Every sentence earns its place, but a minor trim could improve conciseness 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's complexity (two entity types, multiple data sources, sorting, citations), the description is remarkably complete. It covers usage, data source details, and output characteristics even without an output schema, making it self-sufficient for an AI agent.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains that for company type, values should be tickers/CIKs, and for drug type, names. It also clarifies what data is pulled for each type, which is beyond the schema. This greatly aids correct parameter usage.

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

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

The description uses clear action verbs like 'side-by-side comparison' and specifies the resource (companies or drugs). It distinguishes itself from sibling tools like entity_profile by explicitly noting it replaces 8-15 sequential lookups, making the purpose unmistakable.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing strong when-to-use guidance. It also lists trigger phrases ('compare X and Y', 'rank these companies') and contrasts with alternatives, making the usage context extremely 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?

Adds extensive behavioral context beyond the annotations: account/paid plan requirements, parallel tool routing, findings packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] behavior (never invented), depth-specific hop iterations, contradictions[], semantic excerpting, and expected latency. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

While long, every sentence serves a critical purpose: prerequisites, alternative guidance, core behavior, limitations, depth semantics, citation guarantees, and performance expectations. It is front-loaded with the most actionable information (account required and alternative tool) and avoids wasted words despite its detail.

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

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

Given the tool's complexity and lack of an output schema, the description is exceptionally complete: it explains the return format (findings packet with evidence/confidence/source/citations), the gaps[] mechanism, contradictions[], the hop field and citation_uri, and even time expectations. It covers limitations (not open-web search, poor for breaking news) and prerequisites, leaving little ambiguity for the agent.

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

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

Although the schema already covers parameters (100% coverage), the description enriches meaning: it explains depth values beyond the enum (e.g., "standard" re-angles unanswered gaps, "thorough" chases best leads), clarifies that broad/multi-part questions are acceptable, and describes the question's decomposition behavior. This adds value beyond the schema.

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

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

The description clearly states the tool performs "Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources" and "Decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL". It distinguishes itself from siblings with explicit notes like "this is NOT open-web search" and contrasts with ask_pipeworx for single lookups and breaking news.

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

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

Provides explicit when-to-use and when-not-to-use guidance: "Best for broad/multi-part questions over structured data", "For a single lookup use ask_pipeworx", "For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx", and even states the account prerequisite with an alternative if not signed in.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results include full schemas with examples and are ready to call directly – disclosing return format and behavior beyond what annotations provide. No contradictions.

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

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

Front-loaded with main purpose, but slightly long due to listing many domains. Every sentence adds value, but could be tightened without losing information.

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

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

Given no output schema, the description explains return format (top-N tools with names, descriptions, schemas). All parameters documented. Complete for discovery task.

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

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

Schema has 100% coverage with descriptions for all 6 parameters. The description clarifies that 'task', 'q', 'search', 'description' are all aliases for 'query', adding meaning beyond individual 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 starts with 'Find tools by describing the data or task' which is a specific verb+resource. It lists numerous domains and distinguishes this tool from siblings by focusing on tool discovery rather than performing specific tasks.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields including pipeworx URIs, and mentions a known soft-failure for patents. This goes well 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 dense paragraph but well-structured: starts with example queries, then states the tool's superiority, lists data sources and return fields, ends with limitations. It is concise for the amount of information, though slightly 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 complexity of the tool (multiple data sources, return values, constraints), the description is highly complete. It explains what data is returned (CIK, filings with URIs, fundamentals, patents, news, LEI), fallback mechanisms (GNews), limitations (patents soft-fail, names not supported), and the need for resolve_entity.

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 value by providing example values ('AAPL', '0000320193'), clarifying that the value can be ticker or CIK, and reiterating that names are not supported. Baseline is 3 due to high coverage; extra examples push it to 4.

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

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

The description clearly states the tool's verb (provide a full cross-source profile), specific resource (US public company), and scope (holistic view). It distinguishes from siblings by explicitly preferring over chaining single-pack SEC/XBRL/news lookups and directing name-only queries to 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?

The description explicitly says when to use: when the user asks for a holistic view, 'tell me about X', etc. It advises against chaining lookups and provides an alternative tool (resolve_entity) for names. Limitations (names not supported, patents soft-fail) are clearly stated.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by stating events are sorted by start date and that titles/descriptions are in French, which are not covered by annotations. No contradiction.

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

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

Three sentences with no wasted words: first sentence states purpose and region, second lists filters, third adds sort and language. Information is front-loaded and 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?

The description covers region, filters, sort, and language. Without an output schema, it hints at returned fields by mentioning titles/descriptions. It could mention pagination defaults or output fields explicitly, but it is reasonably complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches meaning by grouping filter types (keyword, city, free admission, date window) and noting the sort order, which adds context beyond the schema's individual parameter descriptions. It does not mention limit/offset explicitly, but the examples help.

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

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

The description clearly states the tool finds upcoming events in the Île-de-France region with specific filters, using the verb 'Find' and specifying the resource 'upcoming events'. It distinguishes itself from sibling tools, which are unrelated (e.g., ai_visibility_check, ask_pipeworx).

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: region, filter options, sort order, and language of content. It lacks explicit alternatives or when-not-to-use guidance, but given the absence of similar sibling tools, it is sufficient.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but no new behavioral traits beyond annotations. No contradiction.

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

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

Two sentences, front-loaded with action, no wasted words. Highly concise and 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?

Covers purpose, usage context, and pairing with siblings. Lacks mention of return values or error handling, but given simplicity and annotation coverage, it is nearly complete.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description does not add additional meaning or usage details beyond the schema.

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

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

Clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. Mentions sibling tools remember and recall but does not explicitly differentiate from them beyond usage context.

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

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

Explicitly lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Does not include when-not-to-use or 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds that it fetches the page, extracts title/description/links, and outputs standard markdown format. This adds useful context but does not disclose potential issues like rate limits or error handling, so 4.

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 plus a short use-case list, tightly written with no fluff. Front-loaded with the action and output, every sentence earns its place. Excellent 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 simple tool (2 params, no output schema, good annotations), the description covers functionality, use cases, and output format. Minor gaps: no mention of error handling, prerequisites (internet access), or robots.txt compliance, but still sufficient for the complexity level.

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

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

Schema description coverage is 100%, with both parameters well-described in the schema. The main description does not add new meaning beyond the schema (e.g., max_links default is in schema, not description). Baseline is 3, as description adds no additional parameter insight.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, with specific steps (fetches, extracts, emits). It distinguishes itself from sibling tools like ai_visibility_check by focusing on producing a specific markdown file, but does not explicitly differentiate, so 4.

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

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

The description lists concrete use cases: getting a client's site indexed, drafting for own project, auditing competitors. It provides clear context but lacks explicit when-not-to-use or alternative tool references, scoring 4.

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 listing the returned fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying default behavior (active only). Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. No contradiction.

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

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

Two short, front-loaded sentences with no wasted words. Every sentence provides essential information: action, return fields, and use case.

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

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

Given the tool's simplicity (one optional boolean param, no output schema), the description covers all necessary aspects: what it does, what it returns, when to use it. Annotations also cover safety and 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?

The schema describes the single parameter include_inactive with 100% coverage. The description does not add extra meaning beyond mentioning 'active subscriptions', which aligns with the default. 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 verb 'List', the resource 'subscriptions', and the scope 'caller's active'. It distinguishes from sibling tools like subscribe/unsubscribe by returning existing subscriptions. The return fields are explicitly listed.

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: 'to review what you're monitoring before adding more or to find an id to cancel'. This helps the agent decide between list, subscribe, and unsubscribe.

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

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

Annotations are all false hints, so the description carries the full burden. It discloses rate limits (5 per identifier per day), free/quota behavior, daily digest reading, and the claim_token workflow for anonymous submissions. These are meaningful behavioral details not visible in the schema or 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 dense paragraph but every sentence adds value: usage, exclusions, workflow, rate limits, and incentive. It could benefit from bullet points, but there is no fluff; it's appropriately detailed for a tool that needs to prevent misuse.

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 4-parameter tool with nested objects and no output schema, the description covers the essential workflow including the claim_token return mechanism and rate limits. A minor gap: it doesn't explain what a successful submission returns if the user has an account, but overall it provides enough context for correct 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%, so baseline is 3. The description adds value by explaining the claim_token workflow with an explicit example (pipeworx_feedback({claim_token:"pwfb_…"})) and clarifying how to frame issues in terms of Pipeworx tools. This goes beyond the schema's parameter descriptions, though it doesn't deeply elaborate on type/context/message.

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: to tell the Pipeworx team about broken, missing, or desired functionality. It uses specific verbs and resources (e.g., 'Tell the Pipeworx team something is broken') and distinguishes itself from sibling tools by focusing on feedback submission rather than querying or 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?

Provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise) and importantly states when NOT to use it: for tools from other MCP servers, directing users to file with that server instead. This is exceptional alternative/ exclusion 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 mark the tool as read-only and idempotent. The description adds valuable behavioral context: it is self-aggregating, derived from CF analytics, contains no PII, and is cached 5min-1h depending on window. This goes beyond the annotations to describe data origin and freshness.

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 four sentences, each providing distinct value. The first sentence states the core function, followed by use cases and implementation details. No unnecessary words 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?

Given the tool's simplicity (one optional param) and comprehensive annotations, the description is complete. It covers what is returned, caching behavior, data lineage, and appropriate use cases. No output schema is needed as the return format is adequately described.

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?

There is one optional parameter (window) with an enum and a schema description that already explains the options. The tool description reinforces the behavioral difference between shorter and longer windows, adding marginal value beyond the schema. With 100% schema coverage, this is 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 returns top tools, top packs, and total call volume over a selectable window. It includes concrete use cases (discovering hot data, confirming canonical tools) and distinguishes itself from sibling tools that are query/answer or discovery 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?

Three explicit use cases are provided (discovering hot sources, confirming popular tool, aligning with use case). While it does not explicitly mention when not to use, the use cases give clear context for appropriate invocation. It lacks direct comparison to sibling alternatives but the use cases effectively imply differentiation.

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 (read-only, idempotent), description discloses fill check with CLOB depth, placeholder filtering, and similarity threshold. 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?

Dense but well-structured with clear sections. While long, it earns its length given complexity. Not overly 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?

Thoroughly explains return values (opportunities, partition check, fill check) and edge cases (placeholder slugs, low similarity). Covers all needed context 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% with descriptions, but description adds examples, accepted formats, and detailed behavior for each mode, enhancing 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?

Description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between modes (event, topic) and explains their specific purposes, avoiding tautology.

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

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

Provides explicit guidance on when to use each parameter and recommends event mode for specific markets. Lacks explicit when-not or sibling comparisons, but usage 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, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: caching policy ('Cached 1h at the KV level keyed on all knobs'), detailed model families, slippage handling, and output fields like edge_pp_net and 24h-move warning. 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 dense but well-structured: starts with purpose, then breaks into three model families, response structure, knobs, and diagnostics. Every sentence adds unique information, and the content is front-loaded. It efficiently packs a lot of detail without unnecessary verbosity.

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

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

With no output schema, the description fully explains the response structure: by_segment, fed_candidates/fed_note, diagnostics, and per-opportunity fields. All 9 parameters are explained with usage context. The tool's complexity (3 model families, knobs, caching) is fully covered, making it complete for an AI agent to use effectively.

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

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

All 9 parameters have schema descriptions (100% coverage), but the tool description adds substantial value beyond the schema: e.g., min_kelly explains 'Skips opportunities that are too small to bet sensibly,' slippage_pp gives practical advice ('Bump for very thin partitions'), and min_partition_leg_kelly clarifies how it differs from min_kelly. This goes well 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 explicitly states the tool 'scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The verb 'scan' and resource 'Polymarket markets' are clear, and the tool is distinguished from siblings like polymarket_arbitrage by focusing on Pipeworx data 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 states it's 'built for "what should I bet on today"' and highlights that agents 'discover opportunities without paging hundreds of markets.' It provides guidance on when to use tradeable-edge knobs and explains diagnostics for understanding empty segments, but doesn't explicitly contrast with sibling tools.

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

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

Annotations already provide read-only, open-world, idempotent, and non-destructive hints. The description adds valuable behavioral context (response fields, limits like 60-day TTL, daily snapshots) without contradicting annotations.

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

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

Description is well-structured, front-loading purpose, then detailing response fields and limits. Every sentence adds value, but it's slightly verbose for the parameter details.

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

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

For a tool with 2 optional parameters, no output schema, and comprehensive annotations, the description is complete. It explains response fields (tracked, expired, snapshot_dates) and limitations (60-day TTL, daily closes).

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 (days, window) with descriptions. The description adds meaning: defaults (14 for days, '1wk' for window), clamping (2-30 days), and effect (days on lookback, window on snapshot family).

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

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

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

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

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

The description explains when to use the tool (to determine edge age and decay) and contrasts fresh vs old edges. It implicitly distinguishes from polymarket_edges but lacks explicit 'when not to use' or direct comparisons to other siblings.

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

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

Annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) already convey safety. The description adds depth: checks live CLOB depth, returns verdicts like clean/degraded/cannot_fill, explains risk of partial fills converting arb to directional position, and details return fields. 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 long but well-structured: first sentence captures core purpose, then breaks into modes, then usage guidance. Every sentence adds value, but some repetition (e.g., explaining parameters in both description and schema) could be trimmed. Nonetheless, it's informative and efficient for the complexity.

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

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

No output schema, so description must compensate. It lists return fields (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, realizable_sum, etc. for basket), explains both modes thoroughly, and even warns about partial fill risks. 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 coverage is 100%, so baseline is 3. The description adds meaning beyond schema: clarifies size_usd as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional' for basket, explains default side for basket mode as 'auto from partition sum', and describes side enum behavior. Adds significant context.

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 the verb 'check' plus resource 'edge' is specific. Differentiates from siblings like polymarket_arbitrage and polymarket_edges by focusing on fill risk verification.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides reasoning (theoretical overround not capturable, partial fills cause directional risk) and excludes alternatives implicitly by naming them.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds detailed safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) that reveal failure modes and limitations not apparent from annotations alone.

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 sections for modes, response, and safety fields. It is somewhat lengthy but each sentence adds unique information. 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?

Despite lacking an output schema, the description thoroughly explains return values (leg prices, top_spreads_pp) and all safety fields. It covers edge cases like temporal misalignment and non-equivalent bet shapes, 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'topic' macro shortcuts (e.g., 'fed' -> pre-mapped events) and providing example formats for explicit tickers, which go beyond the bare 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 specifies two operating modes ('topic' shortcuts and explicit tickers) and distinguishes itself from similar tools like 'polymarket_arbitrage'.

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

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

Explicitly describes two modes and when each is appropriate. Includes warnings about compatibility and real spreads being rare, guiding the agent on when results may be meaningful.

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 and idempotentHint=true, so the description doesn't need to restate safety. It adds context beyond annotations: scoping to user identifier, listing behavior when key is omitted, and the pair relationships. However, it doesn't mention any rate limits or performance characteristics, but for a read-only key-value retrieval that's acceptable. Overall, very good transparency given annotation coverage.

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

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

Three sentences, front-loaded with the primary action, then usage advice, then scoping and sibling pairing. No filler or redundant information. Every sentence is necessary and informative.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description fully covers how to invoke it (with or without key), what it returns (value or list of keys), scoping, and how it fits with related tools. Annotations and schema already provide safety and parameter details. Nothing essential is missing.

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

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

Input schema has 100% coverage for the single optional parameter 'key' with a clear description. The tool description adds value by explaining the parameter's role in both retrieval and listing modes, and provides examples of typical key values (ticker, address, notes). This goes beyond the schema's minimal description, despite the schema itself being clear.

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 previously saved value or lists all keys. It uses specific verbs ('retrieve', 'list') and specific resource ('memory key'). It distinguishes itself from siblings 'remember' (save) and 'forget' (delete) by naming them directly. Examples like 'user's target ticker, an address, prior research notes' make the purpose concrete.

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: 'to look up context the agent stored earlier — without re-deriving it from scratch.' It explains the effect of omitting the key (list all saved keys) and pairs with sibling tools for save/delete operations. No ambiguity about when to use this tool versus alternatives.

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

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

The description contradicts annotations: annotations declare readOnlyHint=true, implying no state modification, but the description explains that setting mark_read:true flags events as read, which modifies server state. This is a direct 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-loaded with the purpose, and adds useful examples without unnecessary fluff. It is concise but could be slightly trimmed.

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 return fields and key behavior (mark_read, polling), adequately covering the tool's usage for a read-friendly tool. Lacking output schema is mitigated by describing the payload.

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 3. The description adds value beyond schema by giving examples (e.g., 'sec_8k' for type) and explaining the side effect of mark_read (only newer events on next call), enhancing 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 pulls fired events from the subscription feed and returns recent alerts with specific fields. It distinguishes itself from siblings like 'events' by specifying the subscription feed context, though it doesn't explicitly name alternatives.

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 examples of filtering (type, since) and mentions polling is fine, but it does not explicitly state when to use this tool over siblings like 'events' or 'list_subscriptions', or 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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds significant behavioral detail: fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), makes parallel calls, and explains return structure. 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 fairly long but well-structured: starts with example queries, then purpose, source details, parameter usage, and alternative tool. Every sentence adds value, though the example list at the start could be slightly trimmed. 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 complexity (multi-source, parallel calls, fallbacks, soft-fails) and no output schema, the description is remarkably complete. It explains return format (changes grouped by source, total_changes count, citation URIs), addresses limitations (type only company, USPTO caveat), and suggests when to use entity_profile. Nothing essential is missing.

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 useful examples and context beyond schema: explains `since` ISO and relative formats with suggestions ('30d', '1m'), provides ticker/CIK examples for `value`, and states `type` is limited to 'company'. This extra guidance raises the score.

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 a change feed (filings, news, patents) for a company in a time window. It provides example queries ('What's new with X', 'latest on Y') and distinguishes from sibling entity_profile by noting it is for static profiles instead.

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

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

The description explicitly says when to use this tool (for temporal 'what's new' questions) and contrasts with entity_profile for static profile queries. It also implies the tool is for companies only (type enum is 'company'). No when-not-to-use is needed given the clear alternative.

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

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

Adds valuable behavioral details beyond annotations: memory scoping by identifier, persistent vs 24-hour retention, and pairing instructions. No contradiction with annotations (readOnlyHint false, idempotentHint true, destructiveHint false).

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 focused sentences, each earning its place: purpose, usage guidance, and behavioral details. No redundancy or fluff.

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

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

Given no output schema, the description sufficiently covers storage behavior, pairing, scoping, and retention policies. Complete for a simple key-value 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 has 100% coverage, so baseline is 3. The description enriches both key and value with examples and context (e.g., 'subject_property', 'any text'), adding sufficient value above 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: to save data for later reuse across conversations or sessions. It provides specific examples (resolved ticker, target address) 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 states when to use the tool (discover something worth carrying forward) and pairs it with recall and forget for retrieval and deletion. It also differentiates persistence based on authentication.

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

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

The description goes beyond annotations by explaining the cascading internal lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, and the handling of unresolved identifiers (explicitly stated under `unresolved`). This adds rich behavioral context about reliability and output completeness that annotations (read-only, idempotent, open-world) do not fully cover.

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

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

The description is longer than average but well-structured with examples, a 'SUPPORTED TYPES' section, and a critical note about degradation. Every sentence contributes value, though some examples are redundant. The front-loading of example queries effectively communicates the tool's purpose immediately.

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, multiple identifier systems, fallback behavior) and the absence of an output schema, the description is exceptionally complete. It covers what is returned (CIK, ticker, LEI, FIGI, RxCUI), how sources are labeled, and how unresolved identifiers are handled. This is more than sufficient for an agent to select and invoke the tool correctly.

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

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

Although the schema already documents both parameters with 100% coverage, the description significantly enriches parameter meaning. It specifies exact accepted inputs for company (ticker, CIK, or name) and drug (brand/generic name), and gives concrete examples ('AAPL', 'ozempic'). It also explains what each entity type returns, going beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's function: it resolves user-spoken names to canonical/official identifiers that other tools require. Specific verbs like 'resolve' and 'look up' are paired with the resource (identifiers for company/drug types). It distinguishes from siblings like entity_profile by focusing on ID resolution rather than profile 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 usage guidance is provided: 'Use FIRST whenever you have a name but need an ID.' It also explains that using resolve_entity replaces 2-3 manual lookups, giving clear context for when to invoke this tool versus alternative approaches. No explicit exclusions, but the directive is strong and unambiguous.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds details about the probe process (using ai_visibility_check), ranking by score, and output fields (score, confidence, signal density), providing 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?

Three succinct sentences with front-loaded purpose, no redundant information, and clear progression from action to output.

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 specifies the output structure (ranked list with score, confidence, signal density). Useful for a scanning tool; might benefit from mentioning input validation or rate limits, but annotations cover idempotent/read-only sufficientl.

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 descriptions cover all parameters (100% coverage). Description adds semantic value by explaining the role of the first entity as the 'subject' and the purpose of the context parameter for disambiguation.

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 side-by-side, using specific verbs ('compare', 'probe', 'ranks') and distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (more generic).

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

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

Provides explicit use case (competitive AI-marketing audits) with an example question. Does not explicitly state when not to use, but context from sibling tools implies alternatives.

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

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

Annotations already indicate safe read-only and idempotent operations. The description adds critical behavioral detail: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. 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 a single dense paragraph that front-loads the core purpose. While it could benefit from bullet points for readability, it is not overly verbose and 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?

Despite lacking an output schema, the description thoroughly explains the return format (summary block fields, per-advisory detail, links, alternative versions) and error behavior (timeout handling). This is fully sufficient 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 description coverage is 100% for both parameters. The description adds value by clarifying that scoped packages are accepted and that version defaults to latest when omitted. This enhances understanding 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 it performs a composite check for npm package evaluation covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by specifying it is for the NPM ecosystem only and contrasting with other ecosystems via deps.dev.

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

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

Explicitly tells when to use: whenever an agent asks about package safety, popularity, size, or cost. It also specifies what NOT to use it for (PyPI, Maven, Cargo, Go) and provides an alternative: use deps.dev:version 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals embedding model (BGE-base-en), windowing (500-char overlapping windows), similarity (cosine), and truncation behavior (200K char cap with flag). This adds substantial 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?

Four sentences, tightly written: 1) defines purpose, 2) use case, 3) pairing with sibling, 4) technical details. No redundancy; front-loaded with the core 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?

Even without an output schema, the description covers input (text+query), output (passages with offsets and scores), use case, pairing, technical constraints (cap, truncation), and limits. It is complete for an agent to understand the tool's behavior.

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 elaborates on usage (e.g., example queries for query param) but does not add significant meaning beyond the schema's 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 'Semantic search INSIDE a fetched record', specifying a specific verb (search inside) and resource (fetched record). It distinguishes from siblings by mentioning ask_pipeworx_grounded as a pairing tool, clarifying the tool's niche.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded' to ground over passages. Does not explicitly state when not to use, but contextually implies alternatives.

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

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

The description provides extensive behavioral context beyond annotations: it requires a Pipeworx OAuth account, details delivery channels (feed always on, optional email/SMS/webhook), rate limits (10/day for SMS), verification requirements for phone, webhook signing secret and auto-disable after 10 failing runs. Annotations are consistent (no contradiction), and the description adds significant value.

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 packed with essential information. It is front-loaded with the core purpose. Every sentence earns its place, but it could be slightly more concise for a 1.5-sentence summary. Still, it is well-structured and informative.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description is thorough: it covers all subscription types, parameter details, delivery options, restrictions, and return value. It is entirely adequate for an agent to use the tool correctly without needing external documentation.

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 goes beyond the schema by providing detailed examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id). It also explains delivery sub-parameters (email, sms, webhook) with usage restrictions. This adds significant 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 verb 'create', the resource 'proactive monitoring subscription', and the action 'to a live-data event stream'. It also mentions the return value 'Returns the new subscription id', which distinguishes 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?

The description explicitly states when to use it ('Create a proactive monitoring subscription') and provides context for the types of event streams. It does not explicitly state when not to use it or mention alternatives, but the use case is clear and the description is sufficient for an agent to decide. A slight deduction for lacking explicit exclusions.

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

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

Description adds context beyond rich annotations: it explains output structure (category-bucketed examples with tool shapes), customization via 'topic', and that data is drawn from a live catalog. Consistent with readOnlyHint, openWorldHint, etc.

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

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

Description is relatively long but front-loaded with common query phrasings and each sentence adds distinct value. Could be slightly tighter, but for the complexity of the tool, length is appropriate.

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

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

With rich annotations and one simple parameter, the description fully covers purpose, usage, output structure, and customization. No output schema needed; description explains what is returned well.

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

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

Schema coverage is 100%, but description adds value by explaining that omitting 'topic' returns a cross-category spread and provides example values like 'finance' and 'pharma'. This goes beyond the schema's list of enumerated values.

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 explicitly states the tool is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like 'discover_tools' and 'ask_pipeworx' by specifying its unique function.

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear when-to-use and implied when-not-to-use. References alternatives like meta-tools.

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

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

The description adds behavioral context beyond annotations, such as ownership enforcement and deactivation (not deletion) with historical events retained. Annotations already provide idempotency and non-destructive hints, so the description complements them well.

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 front-load the core action, then add critical conditions. Every sentence is essential, and there is no redundancy or fluff.

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

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

For a simple tool with one parameter and no output schema, the description covers the effect (deactivation) and historical implications. It lacks explicit return value description but is otherwise 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?

With 100% schema description coverage, the baseline is 3. The description does not add further parameter meaning beyond 'by id', but it does not contradict either. No additional value is 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 action (cancel) and resource (subscription by id). It distinguishes from siblings like subscribe and list_subscriptions by specifying ownership enforcement and deactivation behavior, making the purpose unmistakable.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), which guides when the tool is applicable. However, it does not mention alternatives or 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?

Annotations already mark readOnlyHint and idempotentHint, but the description adds essential behavioral nuance: could_not_verify means the check did not happen and must not be used as evidence, unsupported means no source covers the claim, and the return includes a verdict, citation, and reasoning. It also discloses distinct execution paths and the tolerance override mechanism, going well beyond 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 front-loaded with purpose and usage guidance, followed by pathway details and caller caveats. It is somewhat long but each sentence contributes useful information; minor redundancy exists in the grounded-pipeline phrase ('routed to the right live source, answered with verbatim evidence, then judged'), which could be tightened without losing meaning. Overall structure is logical and purpose-driven.

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

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

With no output schema, the description fully explains return values: verdict types, grounded/structured actual value with a pipeworx:// citation, and reasoning. It also covers error semantics (could_not_verify and unsupported) and notes the performance benefit of replacing multiple calls. For a tool of this complexity, the description is complete enough that an agent can invoke it and interpret results 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 provides 100% coverage with clear descriptions for both claim and tolerance_pct, including examples, so the description does not need to add parameter-level detail. The description only implicitly references tolerance via 'exact percent-delta math' and 'tolerance implied by wording', which does not supplement the schema's existing clarity. Baseline 3 is appropriate since the schema is already comprehensive.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, using explicit verbs like 'verify', 'fact check', and 'confirm or refute'. It distinguishes itself from siblings by explaining that it consolidates multiple pipeline steps (NL parsing → entity resolution → data lookup → comparison) into a single call, and by differentiating the handling of company-financial claims versus other factual claims.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides routing logic: company-financial claims go through SEC EDGAR + XBRL fast path, while any other claim falls through to the grounded pipeline, giving clear when-to-use guidance. The note about replacing 4–6 sequential calls frames this as the consolidated alternative, implicitly excluding older multi-step approaches.

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