Adsb

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

Annotations already indicate safe behavior (readOnly, idempotent). The description adds value by listing the exact data returned (altitude, ground speed, heading, vertical rate), but does not cover potential limitations like maximum returned aircraft or data latency.

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

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

Two sentences, no filler. The first sentence defines the tool and its output, the second gives concrete use cases. Every word is purposeful and front-loaded.

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

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

Given no output schema, the description explains the returned fields (ADS-B positions). However, it misses details like response format (JSON?), pagination, or practical limits. Still, for a simple query tool, it covers core expectations.

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

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

Schema coverage is 100% with detailed descriptions (e.g., 'radius_nm: Search radius in nautical miles (default 25, max 250)'). The description only adds the concept of 'within a radius' without additional parameter context, so it meets the baseline but does not surpass it.

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: live tracking of aircraft near a location. It specifies the verb 'track' and the resource 'aircraft near a point.' The use cases 'what is flying above me' and 'planes near <place>' make it unambiguous and distinct from sibling tools like find_by_callsign.

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 ('for what is flying above me / planes near <place>'), providing clear use cases. However, it does not mention when not to use it or suggest alternatives like find_by_callsign or military_aircraft, which would strengthen 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 provide readOnlyHint, openWorldHint, idempotentHint. The description adds further behavioral context: default model (Workers AI Llama-3.3-70b free), requirement of _apiKey for Anthropic, and that the user pays Anthropic directly. It also explains the return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose ('Probe one or more LLMs for what they know about a business...'), then efficiently adds key details (default model, API key requirement, return format, use cases). Every sentence serves a clear function with no redundancy.

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

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

Given no output schema, the description adequately covers return values (per-model score, confidence, signals, raw_response + combined). All parameters are documented in schema and description. The description is complete for a probe tool with moderate complexity, though it could optionally mention rate limits or cost implications beyond the API key note.

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: clarifies that 'models' default to workers-ai, explains the purpose of _apiKey (BYO key for Anthropic), and provides example values for 'entity' and 'context'. This enriches the agent's understanding.

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

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

The description clearly states the tool probes LLMs for brand/business/product visibility and scores it 0-100, using specific verbs ('probe', 'score') and a clear resource. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on individual entity visibility across multiple models.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not explicitly state when not to use it or contrast with sibling tools like 'compare_entities' or 'scan_competitor_ai_presence', which could be alternatives for broader analysis.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description's added value is behavioral detail: it routes across many sources, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. This helps an agent predict what will happen without contradicting the read-only/idempotent annotations.

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

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

The description is front-loaded with the primary routing instruction and rich with domain examples and sample queries. It is longer than minimal, with some redundancy ('PREFER OVER WEB SEARCH' vs. 'Use whenever...'), but each section carries useful routing or behavioral information, so the length is mostly justified.

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

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

For a single-required-parameter router, the description is complete: it explains what the tool does, when to use it, what triggers it, what it returns, and when to prefer deep_research instead. The lack of an output schema is mitigated by the explicit statement that the answer is structured and comes with stable citation URIs.

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

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

Schema description coverage is 100% and the schema already documents the question parameter plus all aliases, so the baseline is 3. The description reinforces that the input is a natural-language question but does not add parameter-level semantics beyond what the schema already 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 identifies the tool as a natural-language factual question router: it routes to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It also distinguishes itself from siblings by positioning it as the preferred default over web search and explicitly contrasting with 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 with trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), concrete example queries, and an explicit alternative: use deep_research for broad/multi-part research questions. It also clarifies that breaking-news queries are already covered by ask_pipeworx, so an agent can route correctly without guessing.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing that this is an experimental live router with candidate routing improvements, that no candidate is currently active, that it currently matches ask_pipeworx exactly, and that it does not fall back to anything else. This gives the agent an accurate model of how invocation may behave over time.

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

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

The description is dense but well-structured, starting with the key fact that this is a beta version of ask_pipeworx, then explaining current state and usage. Every sentence contributes, though the date and exact tool count are slightly more detail than strictly necessary.

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 states the response shape is identical to ask_pipeworx, which is sufficient context given the sibling exists. Combined with full schema coverage and strong behavioral disclosure, the agent has what it needs to invoke the tool correctly, though an explicit example or response note would fully close the 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?

Schema description coverage is 100% and every parameter alias is documented in the input schema. The description only says 'same arguments' and does not add meaning beyond the schema, so the baseline score of 3 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?

Description states a specific resource and action: a beta version of ask_pipeworx that is a universal router with identical tools, arguments, and response shape. It clearly differentiates itself from the stable ask_pipeworx sibling by labeling it the experimental edge with candidate routing improvements.

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 exactly like ask_pipeworx when the newest routing is desired, and explains that results are compared against the stable router. It does not give explicit when-not-to-use guidance, but the beta-versus-stable distinction and current no-active-candidate note provide clear context.

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

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

The description extensively discloses behavioral traits beyond the annotations: it returns a structured success object with evidence and confidence, or an explicit refusal object with enumerated refusal_reason values. It also reveals the grounding constraint ('using ONLY what the tool result contains'), the refusal behavior when data doesn't answer, and the extra LLM call cost. No contradiction with annotations; in fact, it enriches the readOnly/openWorld hints.

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

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

The description is longer than average, but every sentence earns its place: it states the primary behavior, the routing relationship, return and refusal shapes, use cases, and cost tradeoff. The most distinguishing phrase is front-loaded, and the practical alternatives are mentioned at the end 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?

Even without an output schema, the description fully specifies both success and refusal return shapes, describes the sourcing and evidence behavior, gives usage context, and clearly differentiates from ask_pipeworx. An agent has everything necessary to decide when to invoke it and what response 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?

Schema coverage is 100%, and the schema itself documents the single required 'question' parameter and its aliases (q, prompt, text, input, query). The description does not add parameter-level detail, but it doesn't need to because the schema fully covers semantics. Baseline 3 applies when the schema carries the burden.

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 sharp functional identity — 'Hallucination-resistant answer mode for high-stakes reads' — and then explains the grounded extraction mechanism: it fetches data via the same router as ask_pipeworx but answers using only the tool result. This clearly distinguishes it from its siblings, including ask_pipeworx and ask_pipeworx_beta, by specifying a concrete, different 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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also tells the agent when not to use it: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call. This is clear routing between 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?

Beyond annotations, the description discloses resolution process, classifier fan-out, response shapes, resolver contract, parent event extractor, news fields, safety for low-confidence, closed markets, wide spreads, and resolution-rule risk. No contradiction with annotations.

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

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

Description is long but well-structured with clear sections and all details are necessary for correct use. Slightly verbose but appropriate given complexity.

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

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

Given 3 parameters and no output schema, the description is extremely complete: covers all behaviors, edge cases, response interpretation, and safety mechanisms. Leaves no ambiguity.

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

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

Schema coverage is 100% and description adds significant meaning: explains market parameter accepts slug/URL/question text, depth parameter quick vs thorough, include_raw when to use. Goes well beyond schema definitions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with explicit input types (slug, URL, question text). It distinguishes from sibling tools by specifying usage for 'should I bet on X' and contrasts with edge/arbitrage tools.

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

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

Explicitly states when to use: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' Provides extensive examples of classifiers and fan-outs, along with safety checks and blocking conditions.

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

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

Annotations already indicate readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context about data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, and citation URIs. No contradictions with annotations.

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

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

The description is informative and well-structured with clear sections, but slightly verbose. Every sentence contributes value, though some redundancy could be trimmed. Overall, it is effective without being overly long.

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

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

Given the tool's complexity (two entity types with different data sources, sorting, and citation URIs), the description is thorough. It covers all necessary aspects for an agent to select and invoke the tool correctly, even without an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description explains the 'type' parameter (company vs drug) and the 'values' parameter (tickers/CIKs for companies, drug names for drugs), including constraints like max/min items and sorting behavior, adding meaning beyond the schema.

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

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

The description uses specific verbs ('Compare', 'side-by-side comparison') and explicitly states the resources (companies or drugs) and the data pulled (SEC EDGAR, FAERS). It clearly distinguishes itself from sequential lookups.

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 context: natural language triggers (e.g., 'X vs Y', 'which is bigger'), preference over sequential lookups, and entity types with examples. Tells the agent when to use this tool and when not to.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account and paid-plan requirements, expected latency (15-60s, up to ~90s), gap[] and contradiction[] behaviors, citation URI resolvability, and semantic excerpting. This is rich behavioral context that significantly exceeds the annotation coverage, with no contradiction.

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

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

The description is front-loaded with the critical account requirement and alternative tool, then moves from core behavior to usage to deep mechanics. However, it repeats the depth enum semantics already present in the schema and is longer than strictly necessary for a two-parameter 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?

There is no output schema, so the description compensates by spelling out the findings packet structure: verbatim evidence, confidence, source, fetched_at, citation, gaps[], and contradictions[]. It also covers latency, account requirements, citation fetchability, and excerpting behavior, making it complete for correct invocation and result interpretation.

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 documents both parameters. The description adds operational meaning: examples of good research questions, the pricing/latency implications of the depth enum, and how depth levels affect hop and contradiction behavior—extending beyond the schema without contradicting it.

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 resource and action: grounded multi-source research across 1,517 structured data sources, decomposing questions into facets and routing to 5,798 tools in parallel. It explicitly distinguishes itself from open-web search and from the sibling ask_pipeworx for single lookups.

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

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

It gives explicit when-to-use guidance ('best for broad/multi-part questions over structured data') and when-not-to-use guidance ('for a single lookup use ask_pipeworx instead'). It also names the alternative for unsigned-in users, so an agent knows exactly which sibling to select.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds that results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' This discloses important behavioral traits beyond annotations, such as the richness of the response and convenience. No contradictions.

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

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

The description is two sentences with no wasted words. The first sentence states purpose and scope, the second provides usage guidance and return details. It is front-loaded and concise, earning every word.

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

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

Given no output schema, the description explains the return value: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This covers all needed context. Parameter count is high due to aliases but effectively only two parameters (query, limit), which are well-explained. The description is complete for this tool's complexity.

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

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

Schema coverage is 100% with descriptions for all parameters (including aliases). The description mentions 'query' and 'limit' but adds little beyond the schema: it says query is a 'natural language description' and the default/max limit. Since the schema already provides this, the description adds minimal semantic value, 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: 'Find tools by describing the data or task.' It lists many specific domains (SEC filings, FDA drugs, etc.), making the scope explicit. It distinguishes itself from sibling tools, which are specific functions like aircraft_near or bet_research, by being a discovery tool for browsing options.

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

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

The description explicitly advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. It does not explicitly say when not to use, but the context implies it is for exploration before picking a specific tool. Alternatives are not named, but sibling tools are distinct.

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 discloses substantial behavior beyond the read-only/idempotent annotations: it fans out across many external sources, returns `sources_used`/`sources_failed`, and explicitly states that an empty section means 'no data', not a bug. It also explains private-company fallback with `resolved:false`. This goes well beyond what annotations alone 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 long but densely informative, with user-phrase triggers front-loaded and a clear preference directive early. Every sentence adds meaningful context for a complex multi-source tool. It loses one point for some redundancy with the schema's parameter descriptions and the run-on structure of the source/return list.

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 carries the full burden of explaining return values. It enumerates all profile sections (cik, filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI), explains `sources_used`/`sources_failed`, and defines edge cases like private companies. Nothing essential is missing for correct invocation and interpretation.

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

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

The schema already describes both parameters at 100% coverage. The description adds practical value with concrete examples ('AAPL', '0000320193', 'Moderna'), clarifies that `type` is effectively interchangeable, and explains name resolution via SEC EDGAR and the private-company `resolved:false` behavior—useful nuance 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 states a specific verb and resource: it produces a 'full cross-source profile of a US public company in ONE parallel call.' It explicitly distinguishes itself from chaining single-pack SEC/XBRL/news lookups and from the broader sibling set by focusing on holistic entity profiles.

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

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

It gives an explicit preference rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also defines the accepted input shapes (ticker, CIK, company name) and the private-company exclusion behavior, so the agent knows when not to expect a full profile.

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 value by clarifying that it returns live real-time position, not a schedule lookup, and lists the specific data fields. No contradictions.

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

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

The description is two concise sentences, front-loaded with the core purpose. Every word serves a purpose with no redundancy.

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

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

Given the simplicity of the tool (1 parameter, no output schema), the description adequately explains the return value (live position fields) and the nature of the data. It is complete for an AI agent to understand what the tool does and what it returns.

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 'callsign' parameter. The tool description repeats the example format but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool tracks a flight by callsign and returns live ADS-B position data (lat/lon, altitude, ground speed, heading). It explicitly distinguishes itself from a schedule lookup, making the purpose specific and unambiguous.

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

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

The description provides a clear use case ('Track a flight by its callsign') and an example. However, it does not explicitly state when to use this tool versus sibling tools like 'aircraft_near' or 'get_aircraft', or provide when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true. The description adds context (clearing sensitive data, stale context) but does not reveal additional behavioral traits beyond what is implied by 'delete'.

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 succinct sentences with no wasted words. 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?

With one parameter, full schema coverage, annotations, and sibling links, the description is complete. It covers what, when, and relations.

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

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

Schema has 100% coverage with parameter description 'Memory key to delete'. The description does not add extra meaning beyond the schema.

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

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

The description clearly states the action ('Delete') and the resource ('previously stored memory by key'). It distinguishes itself from sibling tools 'remember' and 'recall' by specifying deletion.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with siblings, implying when not to use.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds significant context: fetches the page, extracts title/description/key links, emits standard markdown format, and outputs a ready-to-deploy blob. No contradiction with annotations.

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

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

Description is concise (3 sentences) and front-loaded: first sentence states purpose, second details process, third lists use cases. 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?

Tool has only 2 parameters and no output schema, but the description fully explains the output format (single text blob, standard markdown) and its intended placement (site-root/llms.txt). No gaps given the 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?

Schema description coverage is 100%, so baseline is 3. The description mentions the URL and the default/max for max_links but does not add new meaning beyond the schema's own descriptions.

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

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

Description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (generate), resource (llms.txt), and context (AI crawlers). It distinguishes itself from sibling tools by focusing solely on llms.txt generation.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. However, it does not explicitly state when not to use or name alternatives, which would elevate it to a 5.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: it returns live ADS-B data (not schedules) and only if the aircraft is currently transmitting. This goes beyond annotations by revealing real-time nature and the conditional availability of data.

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, with the first sentence immediately stating the action ('Track a specific aircraft') and the parameter. The second sentence adds details on return data and a qualifier. No redundant information; every word is purposeful.

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 provides a good overview of what data the tool returns (lat/lon, altitude, speed, heading) and the condition for success (currently transmitting). It is sufficiently complete for an agent to understand inputs and expected outputs, though a note on error handling would make it a 5.

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

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

The schema covers 100% of the parameter, describing 'hex' as a 24-bit ICAO hex address. The description enriches this by providing a concrete example ('a835af') and clarifying that the tool tracks a specific aircraft, tying the parameter to the tool's function. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: tracking a specific aircraft by its 24-bit ICAO hex address and returning live ADS-B position data. The verb 'track' and resource 'aircraft by hex address' are specific, and the tool distinguishes itself from siblings like 'aircraft_near' or 'find_by_callsign' by focusing on a single aircraft identified by hex.

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

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

The description provides clear context: use this tool when you have a specific ICAO hex address and need real-time position data. It notes the limitation that data is only returned 'if it is currently transmitting,' which guides proper usage. However, it does not explicitly list when not to use or mention alternatives, so it is not a 5.

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. Description adds that it returns specific fields and mentions the include_inactive parameter, reinforcing non-destructive, read-only nature.

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

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

Two sentences, front-loaded with purpose, no extraneous information. Efficient and clear.

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

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

With a single optional parameter, full schema coverage, and comprehensive annotations, the description provides all needed behavioral and usage context. No output schema is required given the described return fields.

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

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

Schema coverage is 100%, providing baseline 3. Description adds context for include_inactive by tying it to the usage of finding an id to cancel, which aids parameter understanding.

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

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

Clearly states it lists the caller's active subscriptions and enumerates return fields. Distinguishes from siblings like subscribe/unsubscribe by specifying it's for reviewing active subscriptions.

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

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

Explicitly advises using it to review current monitoring before adding more or to find an id to cancel. Provides clear usage context.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds valuable context: specific data fields (lat/lon, altitude, speed, heading), ADS-B source, and real-time nature. No contradictions.

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

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

Two concise sentences with key information front-loaded. No filler words. Efficient.

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

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

Complete for a tool with no parameters and well-covered by annotations. Description tells agent what data is returned, satisfying contextual needs.

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 in input schema, so description need not explain. Schema coverage is 100%. Baseline score of 4 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?

Description clearly states 'Live military and government aircraft...Returns real-time positions', specifying the verb and resource. Distinguishes from siblings like 'aircraft_near' and 'get_aircraft' by focusing on global military/government tracking.

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 implies usage for real-time military air traffic, but no explicit when-not-to-use or comparison to alternatives. Lacks explicit guidance but is sufficiently indicative.

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 enriches the annotations by disclosing behaviors such as the claim_token flow for anonymous reports, rate limiting to 5 per identifier per day, the fact that it's free and doesn't count against tool-call quota, and that the team reads digests daily. These are non-obvious details not available from the annotations alone.

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

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

The description is long but every sentence serves a purpose: purpose, usage exclusions, claim_token workflow, and operational limits. It is front-loaded with the core purpose and structured logically, with no filler.

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

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

Given the tool's relative complexity (4 parameters, nested object, no output schema), the description is complete. It explains the return behavior (claim_token for anonymous filings), the follow-up process, and even the roadmap impact, leaving no significant gaps in understanding.

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 semantic value by explaining the 'type' enum in context, clarifying the context object usage, and providing an explicit example of how to pass claim_token later. This goes beyond what the schema descriptions offer.

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 distinguishes the feedback tool from sibling tools (data research, alerts, etc.) by stating that it is for reporting issues with this Pipeworx connection.

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

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

Explicitly states when to use: for bug, feature/data_gap, or praise. Also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and advises filing with another server for vendor connectors. This is strong guidance beyond simple context.

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

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

Adds details beyond annotations: derived from CF analytics-engine, no PII, cached 5min-1h. No contradiction with readOnly/idempotent hints.

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

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

Three efficient sentences: core function, use cases, technical note. No fluff.

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

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

Covers input, output (top tools/packs/call volume), data source, caching. Lacks explicit return structure but sufficient for a simple query.

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 covers the single parameter with description and enum. Description reinforces window trade-offs but adds minimal new info 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 returns top tools, packs, and call volume over a window. Distinguishes from siblings like discover_tools by focusing on trending/aggregate data.

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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case). No anti-guidance, but use cases are 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?

Describes internal checks (Jaccard similarity, partition filter, fill check) and failure modes (skipped_low_similarity, placeholders filtered). Annotations declare readOnlyHint, openWorldHint, idempotentHint; description confirms safe repeated calls. 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?

Slightly verbose (~150 words) but dense with useful information. Front-loaded with purpose and modes. Every sentence earns its place, though minor trimming possible without losing clarity.

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

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

Given the complexity (multiple modes, internal logic, output format), the description is comprehensive. It explains response structure and fill check even without output schema. References sibling tool for completeness.

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%, but the description adds meaning beyond parameter names: explains the purpose of each mode, provides examples ('fed-decision-may-2026'), and clarifies behavior for each 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?

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and 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 states when to use each mode: 'Call with NO args for trending_scan', 'pass event for a specific market', 'pass topic for cross-event scan'. Also cautions against trading when realizable_edge_pp ≤ 0 and references 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 indicate read-only, open-world, idempotent, and non-destructive. The description provides extensive behavioral details: caching (1h), diagnostic outputs, model formulas, and segment logic—going far beyond annotations.

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

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

The description is very detailed and well-structured, but excessively verbose. It front-loads purpose but contains technical details that could be condensed or moved to external documentation.

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 9 parameters, no required, no output schema, and rich annotations, the description covers the output structure, diagnostics, and knob usage comprehensively. Minor gap: could briefly mention return value format.

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

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

Schema coverage is 100%, so each parameter is described in the schema. The description adds high-level context but does not significantly enhance the meaning beyond the already detailed parameter descriptions.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by being the primary edge discovery tool.

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

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

Built for 'what should I bet on today' and agents discover opportunities without paging through hundreds of markets. It explains three model families and when each applies, but doesn't explicitly state when not to use or alternative tools.

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

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

The description adds substantial behavioral context beyond annotations: it explains the time-series computation, trend classification, decay calculation, expired opportunities, snapshot gaps, and limits (60-day TTL, daily closes). This fully informs the agent of read-only, idempotent behavior.

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 somewhat verbose, with all-caps section labels and redundant phrasing. It could be more concise while retaining essential information.

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

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

Given no output schema, the description fully compensates by detailing the response fields (tracked, expired, snapshot_dates) and their semantics. It also covers limits and data granularity, making the tool's behavior completely 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?

With 100% schema coverage, baseline is 3. The description adds value by providing defaults, clamps, and response structure details not in the schema, such as the format of tracked, expired, and snapshot_dates arrays.

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 tracks edge persistence and decay from daily snapshots, answering a specific question about edge age and shrinkage. It distinguishes from sibling tools like polymarket_edges by focusing on historical time-series rather than current 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 clear context on when to use the tool (e.g., to differentiate a fresh wide edge from an old one) and explains arguments and limits. However, it does not explicitly state when not to use it or provide alternative tool names.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context: it performs a risk analysis, returns verdicts (clean|degraded|cannot_fill), and warns about partial fills. 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?

Well-structured with clear sections for single-market and basket modes, and front-loaded with a summary sentence. However, it is somewhat verbose and could be more concise without losing clarity.

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

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

Despite lacking an output schema, the description comprehensively lists all return values for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.), covers input constraints, and explains caveats like thin legs and forced directional risk.

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

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

Schema coverage is 100%, but description adds significant semantics: explains side default logic for basket (auto from partition sum), interprets size_usd differently for single-market vs basket (spend vs target proceeds vs settlement notional). This goes well 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: realizable-vs-theoretical edge check against live CLOB order-book depth for Polymarket, with explicit single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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?

Excellent guidance: explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and explains why (theoretical overround not capturable on thin books, partial basket fills convert arb to unhedged directional position).

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 the description adds substantial behavioral context beyond them: the token-overlap matcher, compatibility code semantics, the never-pair-unclassified rule, the gross-vs-net fee disclosure, and skipped comparison counters. It even clarifies that a null temporal_alignment 'means it could not be computed... not that the two sides align,' which is exactly the kind of nuance an agent needs.

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 densely packed and well organized: purpose, modes, response shape, safety fields, edge cases, and limitations are each given a sentence or two. It's front-loaded with purpose and ends with a practical caveat. Minor redundancy exists (compatibility codes are effectively listed twice), but every sentence contributes substantive guidance.

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 explain return values, and it does thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment, fees_note, skipped counters, and per-entry flags. It covers special values (null, 'unknown' legs), which means an agent can correctly interpret results without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the mode structure, the override relationships between parameters, and that 'BOTH modes run the identical token-overlap matcher.' This gives the agent contextual understanding the raw property descriptions lack.

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 opening line 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' names a specific verb/resource pair and distinguishes it from sibling Polymarket-only tools like polymarket_edges or polymarket_arbitrage. The equivalence caveat, 'when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so,' makes the tool's job unmistakable.

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

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

The description explicitly presents two modes ('TWO MODES'), explains when to use each, and clarifies override behavior ('Overrides the topic-mapped Kalshi side'), so an agent knows exactly how to invoke it. It also warns that 'pre-mapped ≠ tradeable' and most topics return warnings. However, it never names sibling alternatives or states 'use X instead when...', so exclusions are missing.

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. Description adds valuable context: scoped to identifier, and use cases beyond what annotations convey.

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

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

Concise and front-loaded. Three sentences efficiently convey purpose, usage, and pairing with siblings. 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 read tool with one optional parameter, the description covers retrieval, listing, scoping, and relationships to other tools. No output schema needed as return values are implied.

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

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

Schema coverage is 100% with description for the single parameter. Description adds meaning: 'omit to list all keys' and provides examples, going beyond the schema.

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

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

Clearly states it retrieves values saved via remember or lists all keys if key is omitted. Distinguishes from siblings (remember, forget) by specifying the complementary actions.

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

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

Explicitly describes when to use: to look up stored context like ticker, address, research notes. Mentions pairing with remember and forget, and scoping. Lacks explicit exclusions but 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 indicate read-only, idempotent, non-destructive. Description adds that mark_read flags events as read affecting future calls, and notes the feed persists. 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?

Five sentences, front-loaded with purpose, each sentence adds distinct value. No redundancy or filler.

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

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

With 5 parameters fully specified by schema, description covers return fields and side effect (mark_read). Mentions alternative access method. Complete for a query tool with no output schema.

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

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

Schema has 100% coverage, but description enriches with examples (e.g., 'sec_8k' for type) and clarifies mark_read default false, limit range, unread_only usage. Adds behavioral context beyond schema.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific return fields (source, citation_uri, payload). Distinguishes from siblings like 'list_subscriptions' by focusing on fired events rather than subscription configuration.

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 filtering options (type, since), explains mark_read behavior, and notes polling compatibility. Mentions alternative REST endpoint for scripts/dashboards. Does not explicitly contrast with all siblings but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral details: fans out to three sources (SEC EDGAR, GDELT→GNews fallback, USPTO with known API sunset), explains fallback logic, soft-fail for patents, and parameter behavior (ISO date vs relative shorthand). No contradictions.

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

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

The description is sufficiently concise for the complexity; it front-loads example queries and then provides technical details. A slightly more structured layout could improve scannability, but overall efficient.

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

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

Despite no output schema, the description mentions return structure (changes[] grouped by source, total_changes count, pipeworx:// citations) and covers multi-source fallback behavior, making it complete for agent understanding.

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: explains `since` format with examples ("2026-04-01", "7d", "30d", "3m", "1y") and clarifies `value` accepts ticker or zero-padded CIK, which enhances usability beyond the schema descriptions.

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

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

The description explicitly states the tool provides a change feed for a company (SEC, news, patents) over a time window, with clear examples like "What's new with X" and specifically distinguishes from the sibling tool entity_profile.

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

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

The description gives clear when-to-use examples (e.g., "latest on Y", "updates on Acme") and explicitly recommends entity_profile for static profiles, but does not enumerate other exclusions.

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

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

Annotations show idempotentHint=true, destructiveHint=false. Description adds persistence details (24hr for anonymous vs persistent for authenticated) and scoping by identifier, which annotations don't cover.

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

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

Three sentences: purpose, usage, behavior. No wasted words. Front-loaded with action and examples.

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 key-value store, covers all needed aspects: usage, persistence, pairing with recall/forget. No output schema needed.

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 100% with good descriptions. Description reinforces key-value pattern and provides key naming conventions (e.g., 'subject_property'), adding value beyond schema.

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

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

Description clearly states the tool saves data for later reuse across conversations/sessions, with concrete examples (resolved ticker, target address). 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 tells when to use ('when you discover something worth carrying forward') and mentions companion tools (recall, forget). Lacks explicit negative cases but sufficient for context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: cross-source enrichment, graceful degradation when GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting rather than omission, and ambiguity handling through `figi_candidates`. This is exactly the kind of runtime behavior an agent needs to know.

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 nearly every clause earns its place by addressing selection, invocation, or edge cases. It is front-loaded with the core purpose and 'Use FIRST' guidance. It could be better structured with clearer visual separation between company and drug behavior, but it is not padded.

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 carries full responsibility for explaining return behavior, and it delivers: it describes ambiguity handling, unresolved identifiers, identifier provenance, fallback behavior, and coverage limitations. An agent has enough context to decide when to call it and what results 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?

Although schema coverage is 100%, the description adds significant value beyond the schema: concrete value examples (AAPL, 0000320193, CH0038863350, 'ozempic'), the distinction between issuer names and instrument names for bonds, and the explicit warning not to pass full noun phrases. This materially reduces likely invocation errors.

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 verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also enumerates the supported entity types ('company', 'drug') and the identifier spaces involved, making the tool's purpose unmistakable and distinct from downstream profile/comparison tools.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also provides trigger-phrase examples and supported lookup contexts. However, it does not explicitly state when not to use the tool or name sibling alternatives such as entity_profile or compare_entities, so it stops short of a 5.

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, covering safety and idempotency. The description adds that the tool internally calls ai_visibility_check for each entity and returns a ranked list with score, confidence, and signal density, which provides useful behavioral context without contradicting annotations.

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

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

The description is two sentences long, front-loaded with the primary action, and efficiently packs details about process, use case, and output. 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?

Given 4 parameters (1 required), no output schema, and rich annotations, the description covers the tool's function, internal mechanism, and expected output. It lacks explicit error handling or validation notes (e.g., entity count limits), but these are partially covered by the schema's required and items constraints.

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%, explaining each parameter's type and purpose. The description adds semantic value by noting that the first entity in the 'entities' array is treated as the 'subject' for narrative, which is not in the schema. This helps the agent structure the input correctly.

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

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

The description specifies a clear verb ('Compare'), resource ('AI visibility'), and scope ('across multiple entities side-by-side'). It details the process (probes each entity with ai_visibility_check, ranks by score) and distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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 a concrete use case ('competitive AI-marketing audits') and an example question. It implicitly suggests comparing multiple competitors, but does not explicitly state when not to use (e.g., single entity) or name alternative tools. Nevertheless, the 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?

Adds significant behavioral context beyond annotations: describes partial failure degradation, timing caveat for bundlephobia (5-30s), and lists returned fields (summary, advisories, links, versions). Annotations already indicate safe, read-only, idempotent behavior.

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 yet concise, front-loading the key purpose and use case. Every sentence adds value, covering composite nature, alternatives, timing, and return structure without unnecessary fluff.

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

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

Given the tool has no output schema, the description fully covers return values (summary fields, advisory detail, links, alternative versions) and addresses edge cases (partial failures, timing). The level of detail is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description repeats schema info but adds no new meaning beyond what the schema already provides. Baseline 3 is appropriate as the schema already 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 states it's a composite check for npm packages combining deps.dev and bundlephobia data. It uses a specific verb-resource pair ('scan dependency') and distinguishes from sibling tools by specifying the ecosystem (npm only) and mentioning alternative tools for other ecosystems.

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

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

Explicitly states when to use: 'Use whenever an agent asks is X safe / popular / small' and provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds specifics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. This provides useful beyond-annotation transparency.

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

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

Three sentences, front-loaded with purpose and use case. Each sentence adds value, though slightly verbose in the third sentence. No wasted words overall.

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

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

No output schema present, but description explains return format (passages with offsets and similarity scores) and model details. Given complexity (semantic search, truncation), this is fairly complete. Missing pagination or error handling info.

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 all parameters with descriptions (100% coverage). The description adds query examples and mentions limit default, but the schema already conveys the meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool performs semantic search inside a fetched record, returning top-N passages with offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded by specifying it's for searching within already-fetched records.

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 it (record too large for prompt, saves context) and pairs it with ask_pipeworx_grounded. However, it lacks explicit 'when not to use' or alternatives for small records.

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 adds critical behavioral details: requires OAuth, phone verification for SMS, 10/day cap for SMS, webhook auto-disable after 10 failures, and one-time webhook secret. These exceed what annotations convey.

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

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

The description is well-structured and front-loaded, starting with the primary purpose then expanding on types and delivery. It is slightly long but every sentence adds value. Could be tightened by removing redundancy (e.g., 'always-on persistent feed' is restated).

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 (3 parameters, nested objects, no output schema), the description is remarkably complete. It covers all subscription types, required vs optional params, delivery options with constraints, and return value (subscription id). No gaps are evident.

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?

Despite 100% schema coverage, the description provides extensive additional context for each parameter: type enum values are explained with real examples (e.g., sec_8k items codes), params object has per-type documentation, and delivery object includes constraints like phone verification and daily cap.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, recent_alerts, and unsubscribe by focusing on creation rather than listing or removal.

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

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

The description explains when to use the tool (to set up proactive monitoring) and mentions the requirement for a Pipeworx OAuth account. It lists supported types and delivery channels but does not explicitly state when not to use it or compare to 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by detailing the output structure (category-bucketed example questions with exact tool+argument shape) and that it draws from a live catalog, offering insight beyond the annotations.

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

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

The description is front-loaded with synonyms and purpose, well-structured with usage instructions and output details. While verbose, it is efficient and each sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers purpose, when to use, what it returns, and how to use it. No gaps are 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 a description for the `topic` parameter. The description goes further by listing example values ('finance', 'pharma', etc.) and explaining that omitting it yields a cross-category spread, adding meaningful context.

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

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

The description clearly states it is the onboarding entry point for an agent that wants to know what to ask, returning category-bucketed example questions with tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on suggesting questions rather than answering or discovering tools.

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

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

Explicitly instructs to use this tool FIRST when uncertain about Pipeworx's capabilities, and gives guidance on calling with no arguments for a broad spread or passing a topic for focus. Also mentions learning how to call other meta-tools, providing clear usage context.

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

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

Beyond annotations (non-read-only, non-destructive, idempotent), the description adds critical context: ownership enforcement, deactivation vs deletion, and linking to recent_alerts for historical events. 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?

Three concise sentences: first states purpose, second adds constraint, third explains behavior. No redundant words, highly efficient.

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

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

For a single-parameter tool with no output schema, the description is complete: specifies id source, ownership, deactivation side effect, and persistence of historical events. Annotations and sibling context are fully leveraged.

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 schema already describes the id parameter as a uuid from subscribe. The description adds no further parameter details, which is adequate but not enhanced, meeting the baseline of 3.

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

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

The description clearly states the tool cancels a subscription by id, distinguishes it from subscribe (creation) and list_subscriptions (listing), and specifies the deactivation behavior, leaving no ambiguity about its function.

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

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

The description explicitly states ownership enforcement, guiding when the tool is applicable. It implicitly distinguishes from subscribe and list_subscriptions but lacks an explicit statement of when not to use it, though the constraint is clear.

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

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

Annotations already signal read-only/open-world/idempotent, and the description adds substantial behavioral context beyond them. It discloses the full verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), explains the critical distinction between could_not_verify (check did not happen, not evidence) and unsupported (no source found), and mentions verification_error{stage,detail}. This is rich, non-contradictory 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 longer than average but every sentence earns its place: trigger phrases, routing logic, return contract, and error semantics. It is front-loaded with examples and structured logically from invocation to output. The final sentence about replacing sequential calls is a valuable efficiency note rather than wasteful padding.

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 fully explains what the caller receives: a verdict enum, the grounded/structured actual value with a pipeworx:// citation, and reasoning. It covers both the financial and general paths, explains the two non-verdict outcomes (could_not_verify vs. unsupported), and specifies tolerance behavior. This is complete for a tool of this 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%: both claim and tolerance_pct have detailed descriptions. The tool description adds context about percent-delta math and tolerance capping, but it doesn't introduce meaning beyond what the schema already states. The baseline 3 is appropriate because the schema does the heavy lifting and the description does not need to compensate.

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

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

The description clearly identifies the tool as natural-language claim verification against authoritative sources, with specific examples of triggering phrases ('Is it true that…', 'fact check', 'verify the claim that…'). It explicitly distinguishes from siblings by describing the company-financial fast path vs. the grounded pipeline for all other claims, and notes it replaces 4–6 sequential calls, making its role unique among the sibling tools.

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

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

Provides explicit guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details routing behavior—company-financial claims use SEC EDGAR+XBRL, while any other factual claim falls through to the grounded pipeline—which helps the caller decide when to invoke this tool versus alternatives like ask_pipeworx_grounded or deep_research.

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