Google_calendar

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses cost implications ('you pay Anthropic directly'), default model choice, and return structure (per-model fields + combined view). 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?

A single paragraph of 4 efficient sentences, front-loaded with the core action and outcome. Every sentence adds necessary context without redundancy or filler.

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

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

Despite no output schema, the description covers return structure. Parameters are fully explained. Use cases and pricing are included. The tool is simple (4 params, 1 required), and the description provides sufficient context for an AI agent to invoke correctly.

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

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

All 4 parameters have schema descriptions (100% coverage). The description adds value by explaining the default model behavior, how apiKey is used (passthrough), and that 'models' can be omitted. This goes beyond the schema to clarify invocation logic.

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

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

The description clearly states a specific verb ('probe'), resource ('LLMs'), and outcome ('score visibility 0-100'), making the tool's purpose unambiguous. It also lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that differentiate it from siblings like 'deep_research' or '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 explains when to use the optional apiKey ('if anthropic is in models') and highlights the default free model. It implies usage contexts (marketing audits) but does not explicitly state when NOT to use this tool or compare with siblings like 'scan_competitor_ai_presence'.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining that the tool routes questions to one of 5,564 tools, returns stable pipeworx:// citation URIs, works on every tier, and is fast. It does not contradict annotations. However, it could be more explicit about behavior on ambiguous or unsupported queries, though this is not a major gap given the annotations.

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

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

The description is longer than average but well-structured: it starts with a strong directive ('PREFER OVER WEB SEARCH'), lists domains, provides usage guidelines and exclusions, gives examples, and explains when to step up to siblings. Every sentence earns its place. Some minor trimming of the domain list could improve conciseness, but it effectively communicates the tool's breadth without being wasteful.

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 broad scope, no output schema, and strong annotations, the description covers essential aspects: what it does, when to use, what it returns (structured with citations), how it works (routes to many sources), and example inputs. It does not detail error handling or pagination, but the annotations and examples provide sufficient context for an agent to use the tool correctly. The description feels complete for its complexity.

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

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

Schema coverage is 100% with all 6 parameters (aliases for 'question') described. The description enhances this by explaining the type of input expected: 'Your question or request in natural language' and providing a rich set of examples covering diverse domains. It also clarifies that the tool accepts multiple aliases, which is already in schema but reinforced with context. The description adds meaningful guidance beyond the schema's attribute 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: it answers factual questions using a vast array of verified sources and provides structured answers with citations. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as heavier alternatives, and explicitly says 'PREFER OVER WEB SEARCH' for a wide range of domains. The verb 'routes' and resource '5,564 tools across 1462 verified sources' make the action and scope unambiguous.

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

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

The description gives explicit when-to-use guidance: 'START HERE for most questions — this is the default entry point' and 'PREFER OVER WEB SEARCH'. It also provides when-not-to-use and alternatives: use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions, and notes that breaking news is already covered. It includes concrete examples of appropriate queries and a list of trigger phrases like 'what is', 'look up', 'find', etc.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well-covered. The description adds valuable context beyond annotations: that it's experimental with candidate testing, that no candidate is active (matching stable version), and that results feed into merge decisions. The only minor gap is no explicit mention of potential instability or timeout behavior, but given the annotation coverage, this is a 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 dense sentences plus a clarifying third sentence, totaling under 70 words. Every clause adds value: beta nature, tool count, argument/response identity, candidate mechanism, current equivalence, usage directive, and fallback clarification. No wasted words; front-loaded with key distinctions.

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 (5,564 tools, experimental routing) and lack of output schema, the description provides solid context: the agent knows this is a fully functional router with optional candidate logic, that it matches the stable version when no candidate is active, and its evaluation purpose. A slight gap is no mention of how to detect candidate activity status (e.g., via tool output or separate endpoint), but the description is otherwise complete for selection and usage.

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

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

Schema description coverage is 100% and the schema already documents 5 aliases for 'question'. The description reinforces this by noting 'same arguments', but doesn't add new param-level semantics. However, since coverage is high, the baseline is 3; the description earns a 4 because it clarifies routing behavior for the single required param context, ensuring the agent knows how input is processed (natural language query routed to any of 5,564 tools).

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 this is a beta router tool that accesses 5,564 tools with the same arguments and response shape as ask_pipeworx, and explicitly distinguishes itself from its sibling ask_pipeworx by noting candidate routing improvements and current equivalence (no active candidate). The verb 'ask' and resource 'pipeworx' are well-defined, and the beta nature is precisely scoped.

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

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

The description explicitly tells when to use this tool over alternatives: 'Use it exactly like ask_pipeworx when you want the newest routing'. It contrasts with the stable router by explaining its role in testing ('results are compared against the stable router to decide what merges'). It also clarifies it's a full working router, not a partial fallback, which is critical for agent decision-making.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety and repeatability profile is clear. The description adds important behavioral context: it explains the extra LLM call cost, the success output format with evidence and confidence fields, and the structured refusal reasons. However, it doesn't detail potential side effects, performance, or rate limiting beyond the cost note. The openWorldHint is not contradicted, but given the richness of annotations, the description's added value is moderate.

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 compact and front-loaded: it opens with the core value proposition, then immediately contrasts with the sibling tool, explains the process, and ends with usage guidance. Every sentence serves a distinct purpose with no redundancy.

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

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

Given the tool's high complexity (routing across thousands of sources, with structured refusal reasons), the description covers the key behavioral contract: success format, failure modes, cost tradeoff, and usage boundaries. There is no output schema to document return values, so the description compensates well by listing the exact response shape. A minor gap is the lack of detail on what 'data_truncated' entails, but overall it's thorough 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% — the schema already documents the 'question' parameter and its 5 aliases. The description does not add any new semantic detail beyond what the schema provides. According to the baseline rule for >80% coverage, a score of 3 is appropriate.

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

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

The description uses a specific verb ('Extracts') and resource ('tool result'), clearly distinguishing this tool from its primary sibling ask_pipeworx by emphasizing its hallucination-resistant, grounded answer mode for high-stakes reads. The contrast with ask_pipeworx is directly stated, differentiating the two tools.

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

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

The description provides explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on...agent must not invent facts'), provides concrete use case categories (financial verdicts, legal claims, etc.), and explicitly advises preferring ask_pipeworx for casual lookups, illustrating excellent alternatives and exclusion criteria.

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

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

The description extensively discloses behavior beyond annotations. It explains market_match_confidence (high/medium/low/none), fan-out examples, response shapes, parent_event extraction, news fallback fields, resolution-rule risk, and safety guards (short-circuit on low confidence or closed markets). Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint; the description adds substantial context without contradiction.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded key information. Every sentence adds value, covering many edge cases. While not perfectly concise, the density of useful information justifies the length.

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

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

Despite having no output schema, the description fully covers return structures (result.market with fields, result.analysis with model probability and edge warning, result.evidence keyed by source, market_match_confidence with alternatives and suggestions). It also details error-handling for low-confidence matches, closed markets, and wide spreads. This makes the tool's behavior predictable and actionable for an AI agent.

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

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

Schema coverage is 100%, and the description adds meaning beyond the schema. For the required 'market' parameter, it explains the three allowed formats (slug, URL, question text) with examples. For 'depth', it clarifies quick vs thorough behavior. For 'include_raw', it describes when to use true vs false (summarized for size, raw for reprocessing). The description enriches parameter understanding significantly.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and high-level actions (resolve, classify, fan out, return evidence). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on research rather than edge calculation or 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: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It details when the tool short-circuits (low-confidence matches, closed markets) and mentions tradeability warnings. However, it does not explicitly state when not to use or contrast with similar sibling tools, which keeps it from a perfect score.

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

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

Adds significant behavioral context beyond annotations: parallel execution, correct handling of off-calendar fiscal years, sorted results, and return of citation URIs. No contradictions with annotations.

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

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

Two concise sentences with front-loaded example queries. Every phrase adds value; no wasted words.

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

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

Despite no output schema, the description explains return format and sorting. Covers key behavioral aspects for a 2-param tool with strong annotations.

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

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

With 100% schema coverage, the description adds examples, constraints, and context for each parameter, including that results are sorted by primary metric for 'largest' queries.

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 performs side-by-side comparison of 2-5 companies or drugs, listing specific data sources and example queries. Distinguishes from sibling tools like entity_profile by emphasizing parallel comparisons.

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

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

Explicitly recommends using this tool over sequential lookups for comparisons, stating it replaces 8-15 calls. However, does not explicitly state when not to use it or name alternatives for single-entity queries.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, indicating a safe, non-mutating operation. The description goes far beyond annotations by detailing parallel execution of tools, gap recovery, contradiction detection, citation resolvability, semantic excerpting, and expected response times (15-90s). No contradictions with annotations.

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

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

The description is detailed but well-organized, front-loading critical setup info (account requirement) and sibling tool recommendation. It uses clear sectioning with semicolons and parentheticals to pack information efficiently. Slightly long at ~30 sentences, but every sentence adds distinct value, justifying its length given 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?

For a complex tool with two parameters, no output schema, and rich annotations, the description compensates fully. It explains the research process, result structure (findings packet with evidence, confidence, gaps, citations), depth behaviors, response times, and when not to use it. No output schema is needed given the detailed return description.

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

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

Schema coverage is 100% so the schema already documents both parameters well. The description adds significant value by explaining the depth enumeration values (quick, standard, thorough) with concrete behavior differences (number of hops, gap recovery, contradictions scan, paid tier). It also clarifies that the question parameter accepts broad/multi-part queries. The description could have included a brief note on typical question formatting but is already very helpful.

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

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

The description clearly states that the tool conducts grounded multi-source research across Pipeworx's 1462 structured data sources, decomposes questions into facets, and returns evidence with citations. It explicitly distinguishes itself from siblings like ask_pipeworx (single lookup) and mentions it is not open-web search, making its purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: it recommends ask_pipeworx for single lookups and for breaking/current news, and suggests using this tool for broad/multi-part questions over structured data. It also notes account requirements and the behavior of different depth modes, including fallback recommendations 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, idempotentHint, destructiveHint. The description adds that results are ready to call directly without a second schema lookup, which is useful behavioral context.

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

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

The description is front-loaded with the core purpose and provides a concise list of domains. Could be slightly shorter, but the information density is good.

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

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

Despite no output schema, the description explains what is returned (names, descriptions, schemas) and that results are top-N most relevant. Covers key aspects for a discovery 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 for each parameter. The description provides natural language examples and clarifies that query accepts multiple aliases, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains the output format, distinguishing it from sibling tools which are for 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 says 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear context for when to use, though does not explicitly mention when not to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: fans out across multiple sources, soft-fails on patents (USPTO API sunset), and returns specific fields. No contradiction. Slightly less explicit about error handling or rate limits, but still good.

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

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

Description is lengthy but well-structured with example queries upfront. Every sentence provides value (usage guidance, parameter details, output description). Could be slightly trimmed without losing information, but overall effective.

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

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

Given no output schema, the description thoroughly details what is returned (cik, company_name, recent_filings with URIs, fundamentals, patents status, news, LEI). It also notes limitations (patents API sunset) and data sources. Fully covers expected behavior for a holistic profile 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?

Input schema has 2 params (type, value) with 100% description coverage. Description adds concrete examples ('AAPL', '0000320193'), explains that names are unsupported and to use resolve_entity first, and clarifies zero-padded CIK format. This adds substantial 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 it returns a 'full cross-source profile of a US public company in ONE parallel call,' listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields. This distinguishes it from siblings like 'resolve_entity' and 'compare_entities'.

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

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

Explicitly states to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Over a dozen example user queries are provided. It also specifies when not to use: if only a name exists, use 'resolve_entity' first.

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 destructiveHint=true; description confirms deletion and adds context about clearing sensitive data. No contradiction, but no additional behavioral details beyond annotations.

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

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

Two sentences: first states purpose, second gives usage guidance. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers when and how to use it, especially with annotations present.

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

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

Schema coverage is 100% with clear description for 'key'. The tool description does not add further meaning beyond what schema provides.

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

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

The description clearly states the verb 'Delete' and resource 'previously stored memory by key'. It distinguishes from siblings by explicitly mentioning 'Pair with remember and recall'.

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

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

The description explicitly lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with siblings.

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

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

Annotations already indicate a non-read-only, non-destructive, idempotent write operation. The description adds that the tool returns the created event ID, which is behaviorally relevant. No contradictions with annotations.

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

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

Two sentences, with no wasted words. The purpose is front-loaded, and all essential information is conveyed efficiently.

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

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

For a creation tool with an output schema (implied), the description appropriately mentions the returned event ID. It briefly covers parameters, though it omits mention of all-day events or timezone handling (covered by schema). Still largely complete.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters. The description summarizes key parameters but does not add significant meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the action 'create' and the resource 'calendar event', listing key parameters (summary, start/end, optional fields). It distinguishes this tool from sibling tools like gcal_get_event and gcal_search_events by focusing on creation.

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

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

The description does not explicitly state when to use this tool versus alternatives. While the purpose is clear, there is no guidance on prerequisites (e.g., calendar existence, attendee validity) 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 read-only, idempotent, non-destructive behavior. Description adds what fields are returned (summary, times, attendees, etc.), providing useful context beyond annotations.

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

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

Single effective sentence followed by example, no wasted words, and front-loaded with purpose.

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

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

With annotations and output schema present, description provides sufficient context: it names return fields and gives usage example. 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% with clear descriptions. The description adds no extra parameter details beyond examples, so baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves full details of a specific event by ID, distinguishing it from listing or searching events among siblings.

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

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

Implies use when event ID is known, but does not explicitly state when not to use or list alternatives, though inference from siblings is possible.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns specific fields, which is helpful but not critical beyond annotations.

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

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

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

Tool has no parameters and an output schema. Description fully explains what it does and what it returns, sufficient for an agent to understand and use it.

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

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

No parameters, so schema coverage is 100%. Description has nothing extra to add, baseline 4 applies.

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?

States specific verb 'list' and resource 'accessible calendars', and enumerates returned fields (IDs, names, time zones, access level). Clearly distinguishes from sibling tools that create or modify events.

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

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

Explicitly says 'Use to identify which calendar to query or modify', giving context for when to use. No direct comparison to alternatives, but the purpose is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds value by specifying the return content (event summaries, start/end times, attendees, locations), which is not in annotations.

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

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

The description is two sentences long, front-loaded with the core action ('List calendar events'), and every sentence provides essential information without redundancy.

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

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

Given the presence of an output schema, the description adequately complements it by listing the key return fields. It does not cover ordering or pagination, which are in the schema, but overall provides sufficient context for a basic list 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 the schema fully documents parameters. The description mentions 'optional date filtering' which maps to time_min and time_max, but does not add new semantic detail beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states 'List calendar events' with optional date filtering, using a specific verb and resource. It distinguishes itself from sibling tools like gcal_create_event and gcal_search_events by focusing on listing, but does not 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 mentions 'Use to view upcoming or past events', providing some context for when to use the tool. However, it lacks explicit guidance on when not to use it or how it differs from gcal_search_events, which also lists events.

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 the tool as read-only and idempotent. The description adds that it returns 'matching event details and times' but does not cover pagination behavior or rate limits, which are standard for search APIs.

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

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

Two concise sentences that front-load the core purpose and use case. No extraneous 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 100% schema coverage, existing annotations, and an output schema (implied), the description provides sufficient context for a search tool. It could mention that search is across all specified fields, but the current level is adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add further detail beyond the schema, as it only mentions the 'query' capability without elaborating on time bounds, calendar_id, or max_results.

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

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

The description clearly states the tool searches events by keyword across multiple fields (summaries, descriptions, locations, attendees) and returns details/times. This distinguishes it from siblings like gcal_list_events which filter by time or calendar.

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

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

The description gives a clear use case ('find events by topic or participant') but does not explicitly contrast with alternatives like gcal_list_events or gcal_get_event for when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' 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, well-structured paragraph. It front-loads the core purpose, then explains behavior, then lists specific use cases. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description clearly states the output format: 'single text blob ready to drop at site-root/llms.txt'. It covers input, process, and output comprehensively for the tool's scope.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; it mentions 'max number of link entries' but does not provide additional syntax or format details. Adequate but not enhanced.

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 specifies the verb 'Generate', the resource 'llms.txt file', and the context 'for any URL'. It clearly distinguishes this tool from all siblings, as no other sibling generates llms.txt files.

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 enumerates explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not explicitly state when not to use or provide alternatives, but the provided use cases offer clear context for deployment.

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 returns specific fields and default behavior (active vs include_inactive).

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

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

Two concise sentences with no fluff. Purpose and usage are front-loaded.

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

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

For a simple list tool with one optional boolean and no output schema, the description fully covers what the agent needs to know.

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

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

Schema already describes the one parameter with 100% coverage. Description adds context about caller's subscriptions and implicitly relates to the parameter.

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

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

Clearly states it lists the caller's active subscriptions and specifies returned fields. Distinguishes from siblings like subscribe 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?

Explicitly says to use it for reviewing monitored subscriptions before adding more or to find an ID to cancel, 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 are all false and add minimal safety context, so the description carries the burden. It discloses the claim_token return workflow, daily rate limit of 5 per identifier, free/no-quota behavior, and that the team reads digests daily. This goes well beyond the annotations, though it doesn't explicitly state whether filing creates a persistent record on the user's behalf.

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

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

The description is long but every sentence earns its place: core action, when-to-use mapping, boundary conditions, not-sure heuristic, claim_token workflow, rate limit, and quota note. It is front-loaded with the main purpose and uses paragraph breaks logically. It could be tightened slightly without losing clarity, so not a perfect 5.

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

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

For a 4-parameter tool with nested context and no output schema, the description is remarkably complete. It covers the full lifecycle (file → get token → check resolution), explains response contents in the claim_token path, sets expectations for rate limits and quota, and gives concrete examples of parameter usage. An agent has enough context to invoke this correctly without needing any 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially for claim_token (how to obtain it and use it to read resolution status) and for type (maps 'bug', 'feature', etc. to concrete situations). This lifts it above the 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly separates this from sibling research/discovery tools by naming its feedback-reporting role and naming the team it addresses.

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

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

The description provides explicit when-to-use categories (bug, feature/data_gap, praise), strong exclusions (only for Pipeworx tools, not other MCP servers), and even a disambiguation hint ('Pipeworx tool names are the ones this connection lists'). No other tool gets this level of decision guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds value by disclosing data source (CF analytics-engine), privacy (no PII), the data structure (pack, tool, count), and caching behavior (5min-1h). No contradiction.

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

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

Concise at three sentences plus a list. Front-loaded with primary function, then use cases, then technical details. Every sentence adds value; no redundancy.

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

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

Without an output schema, the description does not detail the exact return format (e.g., structure of top tools and packs). However, it mentions the components (tools, packs, total call volume) and the simplicity of the tool (1 optional param) makes this less critical. Mostly complete.

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

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

The single parameter 'window' has a schema description covering enum values. The description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This exceeds baseline for 100% schema coverage.

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

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

The description clearly states it returns top tools, packs, and call volume over a recent window. It uses a specific verb and resource, but does not explicitly distinguish itself from sibling tools like ask_pipeworx or discover_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 concrete use cases are given (discovering hot sources, confirming canonical tools, checking alignment). It does not mention when not to use or cite alternative tools, but provides clear context for when this tool is valuable.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details on algorithms, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and fill check against live CLOB depth. 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?

Well-structured with clear mode breakdown, bullet points, and labeled sections. Comprehensive but slightly verbose; some redundancy could be 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?

Given no output schema, the description fully explains the response structure: opportunities[] with fields, partition_check in event mode, and fill_check output. Covers all behaviors and edge cases.

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

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

Schema description coverage is 100%. Description adds significant meaning: for event, explains it walks child markets and checks ordering; for topic, explains cross-event scanning and gives seed question examples. Goes 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?

Clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes two modes (event and topic) and explains their functions. Differentiates from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly says 'Call with NO args for trending_scan' and when to use event vs topic. Provides examples of event slugs and topic questions. Warns when not to trade (realizable_edge_pp <= 0). Recommends polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint etc. Description adds value by disclosing caching behavior (Cached 1h at KV level), diagnostics for empty segments, and treatment of Fed bets. No contradictions with annotations.

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

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

The description is very long and detailed, but well-structured with sections, bullet points, and front-loaded purpose. It could be more concise; some technical details might overwhelm. However, every sentence adds value for the target AI agent.

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 9 parameters, 100% schema coverage, no output schema, the description is extremely comprehensive. It explains return structure (by_segment, fed_candidates, _diagnostics), model families, edge cases, and caching. Fills all 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%, so baseline is 3. Description enriches each parameter with context: e.g., min_kelly explains 'half-Kelly fraction', slippage_pp mentions Polymarket fee structure and adjustment tips, min_partition_leg_kelly clarifies its specific use. Adds significant meaning beyond schema.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on edge discovery. Specific verb 'scan' and resource 'Polymarket markets' with a clear goal.

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 it's built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets. Provides guidance on tradeable-edge knobs and filters, but does not explicitly mention when not to use or compare to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and non-mutating. The description adds substantial detail beyond annotations: it explains data source (daily snapshots), computation of trend/decay, limits (60-day TTL, daily closes, not intraday). 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 every sentence adds value. It is front-loaded with the core question. The structure is somewhat dense with inline response format, but overall efficient. Could be slightly more structured (e.g., bullet points for response fields) but not wasteful.

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 is provided, yet the description thoroughly specifies the response structure: tracked[], expired[], snapshot_dates[], including field meanings (trend, decay_pp_per_day, lifespan_days). It also notes limitations (60-day TTL, snapshot gaps). This makes the tool's behavior 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?

Input schema covers 100% of parameters with basic descriptions. The description adds meaningful context: 'days' is explained as lookback with default and max, 'window' as snapshot family with default. It also clarifies the meaning of values (e.g., negative edge_pp_net = SELL YES). 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's purpose: edge persistence and decay telemetry. It answers the specific question 'how long has this edge existed and is it shrinking?' and uses concrete examples (fresh vs 3-week-old edge). It distinguishes from siblings like polymarket_edges by focusing on historical time-series analysis.

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

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

The description implies usage context (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. No explicit when-to-use or when-not-to-use guidance.

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

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

The description details the tool's behavior: walks the ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, etc. It also explains basket mode returns including forced directional risk. Annotations already provide readOnlyHint, openWorldHint, idempotentHint, so the description adds operational specifics without contradiction. A score of 4 is appropriate as it adds significant behavioral context but is not exhaustive.

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

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

The description is long but well-structured, using bold for key terms and separate paragraphs for single-market and basket modes. It front-loads the essential purpose and requirements. While every sentence adds value, it could be slightly more concise, but overall it is appropriate for the complexity of the tool.

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

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

Despite no output schema, the description comprehensively lists all return fields for both single-market and basket modes, including risk indicators like thin_legs and forced_directional_risk. It also discusses the behavioral implications of partial fills and directional risk, providing a complete mental model for the agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining how size_usd is interpreted differently in single-market vs basket modes, the default side logic for basket (auto based on partition sum), and the clamping range (10–1,000,000). This justifies a score of 4.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly names the specific use case of checking edge capturability before acting on arbitrage or edge signals, differentiating it from sibling tools like polymarket_arbitrage and 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 provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable, partial fills cause directional risk) and even warns against using it for small trades by implication, making the when-to-use and when-not-to-use highly clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds substantial behavioral context: two operational modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and caveats about bet shape equivalence and temporal alignment. No contradictions with annotations.

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

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

The description is relatively long but well-structured, starting with core purpose and then detailing modes, response, and safety fields. Front-loaded with the key action. Some sentences could be trimmed (e.g., explanation of why spreads exist), but the density of information is appropriate 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?

Given the absence of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and how to interpret them. It also covers both usage modes. No gaps remain for an agent to 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?

All three parameters have descriptions in the input schema (100% coverage). The description adds meaning beyond the schema by explaining that `topic` is a pre-mapped shortcut for a set of 10 topics, and that explicit tickers override the topic-mapped side. It also lists the valid topic 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?

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the verb (calculating spread) and resource (cross-venue spread). It distinguishes from sibling polymarket tools by explicitly mentioning the cross-venue nature.

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 two modes (topic vs explicit tickers) and explains when the tool will report incompatibility. It warns that 'pre-mapped ≠ tradeable' and explains the safety fields. However, it does not explicitly state conditions under which to avoid using the tool beyond the implicit warnings.

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

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

Discloses scoping behavior ('Scoped to your identifier') which is not in annotations. Annotations already indicate readOnly, idempotent, non-destructive. 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, front-loaded with primary action, then usage guidance, then scoping. No extraneous words.

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

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

Covers retrieval and listing with optional parameter. No output schema, but description sufficiently explains the tool's purpose. Minor omission: shape of returned value not described, but acceptable given simplicity.

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

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

Adds meaning beyond schema: explains that omitting key lists all saved keys. Schema coverage is 100% but description enhances understanding of optional parameter behavior.

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?

Uses clear verb ('Retrieve' or 'list') and resource ('saved keys/values'), distinguishes from siblings 'remember' and 'forget' by explicitly mentioning pairing. Dual functionality is well explained.

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

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

Provides concrete examples of when to use (target ticker, address, research notes) and states the benefit (avoid re-deriving). Lacks explicit when-not-to-use or comparison to 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?

The description contradicts the annotations. Annotations declare readOnlyHint=true, implying the tool does not modify state. However, the description explicitly states that setting mark_read:true will 'flag returned events read so the next call only shows newer ones,' which is a state change. This is a direct contradiction, warranting the lowest score per evaluation rules.

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 highly concise, consisting of three sentences with no extraneous information. The first sentence front-loads the core purpose, followed by key details and an alternative access note. Every sentence serves a clear purpose, making it efficient for an AI agent to parse.

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

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

The description covers the tool's output fields, filtering options, stateful behavior (mark_read), and provides an alternative access method. With no output schema, it explains return content adequately. It could elaborate on limit behavior or error conditions, but it remains reasonably complete given 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?

All five parameters are described in the schema (100% coverage). The description adds value by explaining typical usage: 'Filter by type (e.g. "sec_8k") and/or since (ISO timestamp)' and 'Set mark_read:true to flag returned events read.' This enhances understanding beyond the schema descriptions, justifying a score above baseline.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), action (pull), and return fields (source, citation_uri, raw event payload). It distinguishes itself from sibling tools like list_subscriptions by focusing on fired events and provides an alternative access method, making the purpose unambiguous.

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

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

The description explains usage context: filtering by type and since, setting mark_read for read tracking, and notes that polling works fine. It also provides an alternative access endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus siblings, such as for subscription management tasks, missing some 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 declare readOnlyHint and idempotentHint true. Description adds rich behavioral context: multi-source fan-out (SEC, GDELT, GNews, USPTO), fallback mechanism, API sunset warning, and return structure. No contradictions.

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

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

Description is fairly detailed but front-loaded with common usage examples. Every sentence adds value, though slightly verbose (e.g., mentioning soft-fail details). Could be trimmed slightly 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?

No output schema, but description sufficiently explains return structure (changes[] grouped by source, total_changes count, URIs). Covers multi-source behavior, fallback, and limitations. Adequate for moderate complexity tool.

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

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

Schema covers 100% of parameters. Description adds value beyond schema with examples for 'since' (ISO date, relative shorthand, recommendation), explains 'value' accepts ticker or CIK, and clarifies 'type' only supports 'company'.

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

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

Description clearly identifies the tool as a change feed for a company over a time window, using specific verbs ('get recent changes') and resource ('company change feed'). It distinguishes from sibling tool 'entity_profile' which provides a static profile.

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

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

Provides explicit usage examples and recommends when to use 'entity_profile' instead. However, it does not state when NOT to use this tool (e.g., for real-time news), though the sibling list suggests alternatives like 'ask_pipeworx'.

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

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

Discloses scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. Adds value beyond annotations (idempotentHint, destructiveHint) without contradiction.

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

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

Four sentences, front-loaded with purpose and usage guidance. No redundant information.

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

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

Covers retention, scoping, and pairing with related tools. No output schema needed for a store operation; description is complete.

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

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

Schema coverage is 100% with clear descriptions. Description adds context on typical key patterns (e.g., 'subject_property') and that value accepts any text, slightly 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 it saves data for reuse across conversations/sessions. Provides specific examples and distinguishes from siblings like '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 says when to use: when discovering something worth carrying forward. Mentions pairing with 'recall' and 'forget' as alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it mentions internal cascading through multiple lookup endpoints, graceful degradation of LEI/FIGI enrichment, and that unresolved identifiers are explicitly listed under `unresolved` rather than omitted. This goes well beyond the annotations.

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

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

The description is long but information-dense, with clear structure: examples, supported types, and behavior details. It is front-loaded with the core purpose and examples. A slightly more concise edit could be made without losing value, but the length is justified given 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?

The description covers two entity types, multiple identifier sources, edge cases (ISIN mapping, DEGRADED enrichment), and explicitly defines what the output includes (canonical IDs, source labels, unresolved fields). It is complete for the tool's complexity and there is no output schema requiring additional explanation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant extra meaning for the `value` parameter, explaining that company input can be ticker, CIK, ISIN, or name, and that ISINs map to legal entities via GLEIF. It also enriches the type enum with use cases and example formats, surpassing the bare 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 opens with concrete examples and clearly states the core purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It enumerates supported types and distinguishes itself from sibling tools like entity_profile by focusing on identifier resolution rather than profiling.

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: 'Use FIRST whenever you have a name but need an ID.' It also details what input forms are accepted for each type. However, it does not explicitly state when not to use this tool or directly name alternative tools, so it falls short of the 'when-not/alternatives' bar.

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 as true, and destructiveHint as false. The description adds process details (probes each entity, ranks, returns scores) without contradicting annotations. It could mention auth requirements more explicitly but the _apiKey param covers it.

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 long, front-loaded with the main action, includes a concrete example, and does not contain any redundant or superfluous 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?

Despite lacking an output schema, the description explains the return value as a 'ranked list with score, confidence, signal density per entity.' It also mentions constraints (2-8 entities) and the tool's dependency on ai_visibility_check, providing a complete mental model for the agent.

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

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

Schema has 100% description coverage for all 4 parameters. The description adds meaning beyond schema by explaining that the first entity is treated as the 'subject' for narrative, clarifying optional model and _apiKey usage, and providing context for the entities parameter.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It provides an example use case and distinguishes from the sibling ai_visibility_check by being a composite tool for multiple entities.

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

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

Description explicitly says 'Useful for competitive AI-marketing audits' and gives an example question. It implies the tool is for multi-entity comparison, but does not explicitly state when not to use it or mention alternatives like using ai_visibility_check for a single entity.

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

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

The description adds significant behavioral context beyond annotations, including partial failure handling (graceful degradation, sources_failed list), timing details (bundlephobia first measurement takes 5-30s), and what is returned (summary block, per-advisory detail). 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 paragraph that is front-loaded with the main purpose and uses concise language. While it contains multiple details, each sentence adds value without redundancy.

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

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

Given no output schema, the description thoroughly explains the return structure (summary block, details, links, alternatives) and covers edge cases like partial failures. It is complete for an agent to understand what to expect.

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

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

The input schema already describes both parameters with 100% coverage, including scoped packages and default version behavior. The description adds no new semantic meaning beyond what is in the schema, meeting the baseline.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, covering license, advisories, version history, bundle size, and tree-shaking. It uses specific verbs like 'scan' and 'check' and explicitly defines the resource ('npm package').

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

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

The description explicitly tells when to use the tool: when an agent asks about safety, popularity, or size of a package. It also provides an alternative for other ecosystems ('deps.dev:version directly'), effectively differentiating usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds significant behavioral context: embedding model (BGE-base-en), window size (500-char overlapping), truncation behavior (200K chars capped, flagged), and offsets for each passage. No contradictions.

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

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

Description is about 5 sentences long, front-loaded with the purpose. Each sentence adds necessary detail without fluff. Could be slightly more concise but overall well-structured.

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

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

Given the tool's complexity and no output schema, the description thoroughly explains the return format (top-N passages with offsets and scores), search mechanism, truncation behavior, and usage context. Covers all essential aspects.

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 clear parameter descriptions. The description adds valuable context like example queries for the 'query' parameter, default value for 'limit' (5), and max length for 'text'. This goes beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' and distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded. The resource (a record) and verb (search) are specific.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests an alternative: 'Pairs with ask_pipeworx_grounded'. Provides 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses critical behavioral traits: the need for an OAuth account, persistence limitations, auto-disabling of webhook after 10 failures, and SMS daily cap. No annotation contradiction detected.

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 effectively front-loads the primary purpose. However, it could be slightly improved with bullet points for readability without losing informativeness.

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

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

Given no output schema, the description fully covers purpose, prerequisites, parameters with examples, delivery constraints, and return value (subscription id). It addresses all aspects needed for correct invocation.

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

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

With 100% schema description coverage, the description adds substantial value by providing concrete examples for each subscription type and delivery channel, including HMAC signing details for webhooks. This goes far 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 uses a specific verb ('Create') and resource ('proactive monitoring subscription'), immediately stating the tool's purpose. It also lists supported subscription types and delivery channels, clearly distinguishing 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 the prerequisite (Pipeworx OAuth account) and provides detailed examples for each subscription type (e.g., sec_8k with items codes, polymarket_edge with topic). It lacks an explicit 'when not to use' statement but still offers strong contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context about return format (category-bucketed examples with tool/argument shapes), which is useful but not critical behavioral info.

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 somewhat lengthy but front-loaded with common queries and well-structured. Every sentence adds value, but could be trimmed slightly without loss.

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

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

Given the simple input (one optional string) and no output schema, the description fully explains the tool's behavior, return structure, and use cases. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant value by explaining that omitting the topic gives a cross-category spread and passing a topic focuses the results, with concrete examples of valid topics.

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: returns category-bucketed example questions for onboarding, distinguishing itself from siblings like ask_pipeworx and discover_tools by being the first tool to call when unfamiliar with the agent's capabilities.

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

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

Explicitly says to use this FIRST when the agent doesn't know what Pipeworx can do, and to learn how to call meta-tools. Provides guidance on filtering by topic or omitting for full spread.

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

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

Beyond annotations, the description discloses ownership enforcement, that the row is deactivated (not deleted), and that historical events persist via recent_alerts, adding valuable behavioral context.

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

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

The description is two concise sentences with zero waste, front-loading the action and key constraints.

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

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

For a simple tool with one parameter and no output schema, the description fully covers behavior, ownership, and data lifecycle, referencing the relevant sibling tool 'recent_alerts'.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description does not add further meaning to the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and distinguishes it from the sibling 'subscribe' tool by specifying ownership enforcement and deactivation behavior.

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

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

The description implies usage for canceling own subscriptions and notes that historical events remain available via recent_alerts, but does not explicitly state when not to use this tool or provide alternatives (e.g., 'forget').

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/openWorld/idempotent annotations, the description reveals critical behavior: the two distinct verification pipelines, the full verdict vocabulary, the distinction between could_not_verify (a failure, not evidence) and unsupported, and the inclusion of citations and reasoning. This context is not inferable from annotations and prevents caller misuse.

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

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

The description is detailed but every sentence adds value. It front-loads user-phrase triggers, then explains the dual pipelines, verdicts, caller caveats, and the composite nature of the tool. Structure is logical and efficient for the complexity involved.

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

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

Without an output schema, the description thoroughly explains return values (verdict, actual value, citation, reasoning) and error semantics. It covers both company-financial and general claims, the tolerance override, and important caller warnings, making the tool's behavior fully comprehensible in context.

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

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

Schema coverage is 100%, and the description adds substantial semantic depth: tolerance_pct overrides the implied tolerance, has a 0.5–50 range, default is capped at 5, and setting 1–2 is recommended for hallucination detection. This goes far beyond the schema's syntax.

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

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

The description opens with concrete query phrases and a clear definition: 'natural-language claim verification against authoritative sources.' It distinguishes the tool from general Q&A siblings by stating 'Use whenever the agent needs to check whether something a user said is factually correct.'

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 when to use (claim verification) and provides detailed routing rules: company-financial claims go through the SEC/XBRL fast path, all other claims fall through to the grounded pipeline. It does not explicitly name sibling alternatives or state when not to use it, but the guidance is strong and covers scoped use cases.

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