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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that the tool routes questions, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and handles live news routing. This adds useful behavioral context about what the agent can expect when invoking the tool.

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 front-loads the key preference over web search and gives a comprehensive domain list, usage triggers, examples, and escalation paths. It is somewhat long and has a slightly awkward transition near 'START HERE for most questions. default entry point, one fast call,' but each section earns its place and the structure is mostly 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?

For a broad factual-question router with no output schema, the description is complete: it covers what the tool does, when to use it, what kinds of questions work, examples, output behavior (structured answer with citations), and how it relates to sibling tools. No critical invocation context is missing.

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

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

Schema coverage is 100% and the description adds meaningful invocation context through question-type triggers, concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K'), and the statement that the tool fills arguments itself. This goes beyond the schema's minimal 'natural language question' description.

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

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

The description states a clear, specific purpose: ask_pipeworx answers factual questions over a broad set of authoritative data sources (SEC, FDA, FRED/BLS, patents, real estate, news, sports, etc.) by routing to one of 5,798 tools and returning structured answers with citation URIs. It also differentiates itself from web search and from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: prefer over web search for current/historical factual questions, use even when web search could answer, and use for trigger phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', 'current'. It also names alternatives and tells when to step up to ask_pipeworx_grounded or deep_research, making sibling selection clear.

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

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

Beyond the annotations, the description reveals that this is an experimental edge with candidate routing improvements possibly enabled live, that the last candidate was retired, and that it currently matches ask_pipeworx. It also explicitly addresses fallback expectations: 'Falls back to nothing — this IS a full working router.' This is rich, honest context beyond what readOnlyHint and idempotentHint provide.

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

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

The description is somewhat longer than necessary, but each sentence contributes a distinct fact: beta status, identical surface area, candidate state, usage condition, and fallback behavior. The beta relationship is front-loaded, and the experimental nature is clearly communicated before the invocation note.

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

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

For an experimental variant of a sibling tool, the description is well positioned: it points to ask_pipeworx for exact usage, states the current state of candidate routing, and reassures that it is fully operational. There is no output schema, and the description stops at saying 'same response shape' without detailing it, but since this is explicitly a variant of a known sibling, the reference is reasonably 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 input schema already documents all six parameters at 100% coverage, including the question parameter and its aliases. The description adds only that the tool takes 'the same arguments' as ask_pipeworx, which is useful for cross-reference but not necessary for understanding semantics. This is a solid baseline case where the schema does the heavy lifting.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by mentioning candidate routing improvements. It could be more explicit about what a universal router does, but the sibling relationship makes the purpose sufficiently clear.

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

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

The description explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives a clear when-to-use condition. It also explains that no candidate is active and the tool currently matches ask_pipeworx exactly. It does not discuss when to prefer ask_pipeworx_grounded or when to avoid this beta version, so it stops short of full 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the refusal reasons, the evidence field requirement, that extraction uses only the tool result, and the extra LLM call cost. No contradiction with annotations exists; this is rich behavioral disclosure.

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 dense sentences, each carrying essential information: purpose, routing mechanism, return contract, refusal reasons, use cases, and cost comparison. The content is front-loaded with the core purpose and structured logically. No filler or redundant restatement.

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 specifies the success and error return shapes. It also covers when to use, when not to use, and the behavioral guarantee. An agent has everything needed to decide to invoke and interpret the result accurately.

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 the 'question' parameter and its aliases. The description adds no parameter-level meaning beyond restating that the tool takes a question indirectly via 'ask' and 'fills arguments'. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific purpose: a hallucination-resistant answer mode that routes to tools, fetches data, and extracts a grounded answer with evidence. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing 'ONLY what the tool result contains' and the explicit refusal contract, so an agent can tell them apart without inspecting schemas.

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

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

Explicit when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also gives the alternative: 'prefer ask_pipeworx for casual lookups' plus the cost tradeoff. This fully satisfies the dimension.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account requirements, paid-tier constraints, expected latency (15-60s, up to ~90s), the contradiction[] and gaps[] behavior, and the guarantee that findings are never invented. It also explains that citations are only present when resolvable, which is critical 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 long but information-dense; nearly every clause adds operational detail. Minor deduction for its parenthetical-heavy, run-on structure, which makes the text harder to parse than necessary, but it is front-loaded with the most decision-critical constraint (account required).

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

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

With no output schema, the description fully compensates by describing the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]) and the behavior around large records and unresolvable citations. Auth, cost, latency, and exclusion cases are all covered, making this complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining what each depth level actually does (single hop, gap recovery, lead chasing, contradictions scan) and that 'thorough' requires a paid plan. It also clarifies that the question parameter accepts broad/multi-part natural language.

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 names a specific verb and resource: grounded multi-source research across Pipeworx's 1,517 structured data sources in one call. It clearly distinguishes itself from both open-web search and the sibling ask_pipeworx, and states what it returns (findings packet with citations and gaps).

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?

Usage guidance is explicit: 'If you are not signed in, use ask_pipeworx instead', 'Best for broad/multi-part questions', and 'For a single lookup use ask_pipeworx'. It also explains depth-tier behavior and the paid requirement for 'thorough', leaving no ambiguity about when to choose this tool vs 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, 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?

Goes far beyond the readOnly/idempotent annotations by disclosing fan-out across multiple data sources, fallback behavior (GDELT→GNews, patents soft-fail after May 2025), and the meaning of sources_used/sources_failed. It also explains that an empty section is 'a real no data, not a bug,' which is critical for agents interpreting results.

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

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

The description is dense and front-loaded with examples and core purpose. It is longer than strictly necessary, and some information (type/value shapes) is repeated in the schema, but every substantive behavior and edge case earns its place.

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

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

For a complex tool with no output schema, the description fully documents return sections, source fallbacks, failure semantics, and input flexibility. It covers edge cases like private companies and expected empty results, so an agent has enough context to invoke it correctly and interpret the response.

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

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

Although the schema covers the two parameters well, the description adds meaning: pass a ticker, zero-padded CIK, or company name; names resolve via SEC EDGAR; `type` accepts 'company' or 'ticker' interchangeably. It also details what the response will include (cik, company_name, resolved_from/resolved_to, etc.), giving the agent richer expectations than the schema alone.

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

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

The description starts with concrete user phrasings and states the verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from chaining individual SEC/XBRL/news lookups, and implicitly scopes to public companies (private companies are handled with a resolved:false response).

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: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also explains when results are expected to be empty (e.g., FDA products for small-molecule/generic drug companies) and what happens for private companies, preventing misuse and misinterpretation.

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?

This description goes far beyond the annotations, which only indicate readOnly/openWorld/idempotent/non-destructive behavior. It discloses that Kalshi fees are not modeled, that spreads are gross not net, that pairing is keyword-based rather than source-verified, and that null alignment means 'could not be computed' rather than confirmed. These are exactly the kind of behavioral nuances an agent needs to interpret results correctly, and nothing contradicts 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 and dense, but it is well-structured: it front-loads the core purpose, then organizes content under conceptual sections (modes, response, safety fields, codes, fee note, skipped counters). Some caveats are repeated, such as temporal_alignment caveats and the gross-vs-net fee point, making it slightly less concise than ideal. However, every sentence carries practical information needed to use the tool safely.

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

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

With no output schema, the description must fully explain response semantics, and it does: it describes leg-by-leg prices, top_spreads_pp, compatibility_warning vs compatibility_codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped_cross counters. It also covers edge cases like unknown metric types and unverifiable pairings. An agent has enough information to invoke the tool and interpret its results correctly.

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

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

Even though the schema covers all parameters, the description adds substantial semantic value: it explains the two mutually exclusive modes, lists the 10 pre-mapped topic shortcuts, and clarifies that explicit ticker/slug parameters override the topic-mapped side. It also explains that both modes run the same token-overlap matcher, which affects how the parameters should be interpreted. This is a clear case of description meaningfully enriching 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 opens with a specific and informative statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately conveys the tool's unique focus and differentiates it from single-venue or general arbitrage tools. The two modes ('topic' shortcuts and explicit ticker/slug pairing) further clarify exactly what the tool does and how it can be invoked.

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 strong context for when the tool is appropriate: it compares equivalent bet shapes and explicitly warns that non-equivalent shapes are flagged. It also cautions that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return warnings today, guiding expectations. It does not explicitly name sibling alternatives like polymarket_arbitrage, so it misses the highest bar for when-to-use versus alternatives, but the usage context is otherwise clear and actionable.

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

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

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?

Beyond the read-only/idempotent annotations, the description discloses cascading internal lookups, graceful degradation when GLEIF or OpenFIGI are unavailable, ambiguity handling via figi_candidates, explicit unresolved fields, and source-labelled identifiers. This materially enriches what the agent can expect at runtime, and there is no annotation 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?

There is no filler and every sentence adds real information, but the company branch is a dense run-on paragraph with deep parentheticals that mix output fields, input forms, ambiguity policy, and failure behavior. The content is appropriately detailed for the tool's complexity, but the structure could be much easier to scan with bullets or shorter sentences.

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

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

With no output schema, the description explains return semantics well: unresolved identifiers are stated explicitly, ambiguous FIGI matches return figi_candidates, every identifier is source-labelled, and enrichment can degrade gracefully. It is largely complete for correct invocation, though an explicit example of the returned shape would close the remaining gap.

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?

Even though schema coverage is 100%, the description adds meaning far beyond the schema: value accepts ticker, CIK, ISIN, or company name for company; brand or generic for drug; and it warns against passing trailing security-class terms in bond names. This is critical invocation guidance the schema alone does not provide.

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 and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input,' backed by concrete query examples and two supported entity types. It is clear what the tool does, but it does not explicitly name or contrast sibling tools such as entity_profile, so differentiation remains implicit.

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

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

It gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID,' plus type-specific guidance and exact input constraints, such as passing the bond issuer name only and avoiding trailing security-class words. However, it does not state when not to use this tool or name alternatives, so exclusions are absent.

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.